multivalent
Class Node
public abstract
class
Node
extends VObject
implements Cloneable
Base class for nodes of the document tree (both user interface and content), providing common tree manipulation methods
as well as implementing
before and
after phases of tree walk protocols,
calling another method that can be easily overridden.
Do not subclass this class; use or subclass either of
INode for internal nodes or
Leaf for leaves.
- state:
name
, parent
, bbox, baseline, align, valign, floats
- tree manipulation operations: remove,
- tree navigation operations: getParentNode, getNextNode, getPrevNode, getFirstLeaf, getLastLeaf,
- general tree operations: commonAncestor, Node,
Node, Node
- marking of format-dirty bit: isValid, Node, markDirty, Node, markDirtyTo
- parallels to Behavior's protocols:
- translation between relative and absolute coordinate systems: dx and dy, getAbsLocation, getRelLocation
observers
- convenience hooks to
Browser
, Root
, Document
, IScrollPane
.
- for efficient operation, spans keep
stickies
, or summary information in leaves
Version: $Revision: 1.16 $ $Date: 2003/06/02 05:09:28 $
See Also: MediaAdaptor Root Document Behavior
Field Summary |
byte | align Justification (LEFT, RIGHT, CENTER, FILL/JUSTIFY) -- set with style sheet if possible. |
static byte | ALIGN_INVALID Alignment. |
static String | ATTR_ID |
static String | ATTR_SCRIPT |
int | baseline Baseline, relative to top of bounding box. |
static byte | BASELINE Alignment. |
Rectangle | bbox
Bounding box, in pixels, location relative to parent node.
|
static byte | BOTH Alignment. |
static byte | BOTTOM Alignment. |
static byte | CENTER Alignment. |
static byte | CHAR Alignment. |
static byte | FILL Alignment. |
byte | floats If floating object, side (LEFT or RIGHT) -- set with style sheet if possible. |
static byte | INHERIT Alignment. |
static byte | JUSTIFY Alignment. |
static byte | LEFT Alignment. |
protected static int | MAXNONSTRUCTDEPTH |
static byte | MIDDLE Alignment. |
protected String | name_
Name of node, like PARA or SECT for structural nodes, ASCII translation for leaves.
|
static byte | NONE Alignment. |
protected List<Behavior> | observers_
Behaviors that have registered interest in this node.
|
protected INode | parent_ |
static int | PROBEWIDTH
Some layouts ask contents how big they'd like to be, and some content will take all they can get,
as when centering or HTML HR. |
static byte | RIGHT Alignment. |
protected Mark[] | sticky_ List<> of marks on leaves, subtree summaries on internal nodes. |
protected short | stickycnt_ |
static byte | TOP Alignment. |
protected boolean | valid_ Layout dirty bit. |
byte | valign Vertical alignment -- set with style sheet if possible. |
Constructor Summary |
| Node(String name, Map<String,Object> attrs, INode parent)
Create a node with the given name, attributes and parent, any of which can be null.
|
Method Summary |
void | addObserver(Behavior be)
Observers get called when node is encountered in tree walk protocols (format, paint, low-level event),
protocolBefore and protocolAfter methods.
|
void | addSticky(Mark m) |
void | addSticky(Mark m, boolean sequence) |
boolean | breakAfter() |
boolean | breakBefore() |
boolean | checkRep() |
int | childNum() |
void | clipboardBeforeAfter(StringBuffer txt)
Depth-first tree traversal to build selection.
|
abstract void | clipboardNode(StringBuffer txt)
To build up selection, pass a StringBuffer to media-specific leaves,
which fill it as appropriate for that medium.
|
protected Object | clone()
Deep copy of Rectangle; observers and sticky set to null.
|
static int | cmp(Node ln, int lo, Node rn, int ro, INode top)
Does first (node,offset) come before (-1), at (0), or after (1) second (node,offset)?
|
Node | commonAncestor(Node b) |
Node | commonAncestor(Node b, Node top) |
boolean | contains(Point p) Nodes say whether it wants to see activity at point, regardless of bbox. |
boolean | contains(Node n) |
void | deleteObserver(Behavior be) |
void | dump() |
void | dump(int maxlevel) |
void | dump(int level, int maxlevel) Dump more verbose than toString(). |
abstract int | dx() X-coordinate transformation needed when entering this node's relative coordinate system. |
abstract int | dy() Y-coordinate transformation needed when entering this node's relative coordinate system. |
boolean | eventBeforeAfter(AWTEvent e, Point rel)
Pass tree event. |
abstract boolean | eventNode(AWTEvent e, Point rel)
Process java.awt.Event or multivalent.TreeEvent (not multivalent.SemanticEvent). |
Node | findBFS(String searchname, String attrname, String attrval, int maxlevel)
Breadth-first search for node with given name (generic identifier), attribute name, and attribute value.
|
Node | findBFS(String searchname) Breath-first search for node with given name (generic identifier). |
Node | findBFS(String searchname, String attrname, String attrval) |
Node | findDFS(String searchname, String attrname, String attrval, int maxlevel)
Depth-first search for node with requested combination of name, attribute name, and attribute value.
|
protected Node | findDFS(String searchname, String attrname, String attrval, int level, int maxlevel) |
Node | findDFS(String searchname) Depth-first search for Node with given name. |
Node | findDFS(String searchname, String attrname, String attrval) Depth-first search for Node with given name and (name, val) attribute pair. |
boolean | formatBeforeAfter(int width, int height, Context cx)
In the depth-first tree traversal to format tree,
Before and after methods of behavior observers invoked here; actual formatting passed on to formatNode().
|
abstract boolean | formatNode(int width, int height, Context cx) Override this to specialize the natual layout of a node. |
Point | getAbsLocation() Determine location of node in absolute coordinates, as opposed to parent-relative. |
List<ContextListener> | getActivesAt(int offset) |
List<ContextListener> | getActivesAt(int offset, boolean spansonly) |
List<ContextListener> | getActivesAt(int offset, List<ContextListener> base, boolean spansonly)
Collect active behaviors at point: spans, style sheet settings.
|
Rectangle | getBbox() Return node bounding box. |
Browser | getBrowser() Chains up parent links. |
Document | getDocument() Chains up parent links until find (lowest enclosing) Document. |
Node | getElementById(String elementId) |
abstract Leaf | getFirstLeaf() |
IScrollPane | getIScrollPane() Chains up parent links. |
abstract Leaf | getLastLeaf() |
String | getName() |
Leaf | getNextLeaf()
Get the following leaf in a left-to-right traversal, returning null if none.
|
Node | getNextNode() Get the node immediately following in a depth-first tree walk, returning null if none. |
String | getNodeName() DOM2 nomenclature -- since method on a Node, why not "getName()"? |
List<Behavior> | getObservers() Needed by Document to do clipboardBeforeAfter on root before selection. |
INode | getParentNode() DOM2 nomenclature (why not "getParent()"?). |
Leaf | getPrevLeaf()
Get the previous leaf in a left-to-right traversal, returning null if none.
|
Node | getPrevNode() Get the node immediately previous in a depth-first tree walk, returning null if none. |
Point | getRelLocation(Node relto) Determine location of node relative to passed node, as for instance location of image relative to its Document. |
Root | getRoot() Chains up parent links. |
Mark | getSticky(int inx) |
int | indexSticky(Mark m) |
boolean | intersects(Rectangle r) Nodes say whether it wants to see activity in rectangular region, regardless of bbox. |
boolean | isLeaf() |
boolean | isStruct() |
boolean | isValid() |
void | markDirty()
Mark dirty--setValid(false)--and chain of nodes up to lowest IScrollPane.
|
void | markDirtySubtree(boolean leavestoo)
Mark dirty all nodes in subtree and path to root (up and down tree).
|
abstract void | markDirtySubtreeDown(boolean leavestoo) Mark dirty all nodes in subtree (down tree only). |
void | markDirtyTo(Node rn)
Mark dirty all nodes in a span, parents included. |
void | morphInto(Node l)
Transfers content into passed Node, destroying original and replacing it in tree.
|
void | paintBeforeAfter(Rectangle docclip, Context cx)
Depth-first tree traversal to paint tree.
|
abstract void | paintNode(Rectangle docclip, Context cx) |
void | reformat(Node bogus)
High performance reformatting of subtree.
|
void | remove()
Simple remove node from parent. |
void | removeSticky(Mark m) |
void | removeSticky(int inx) |
void | removeTidy(INode root)
Remove node from tree tidily:
don't leave behind empty INode, recursively up to root. |
void | repaint(long ms, int x, int y, int w, int h)
Redraw portion of node within ms milliseconds.
|
void | repaint(int x, int y, int w, int h) |
void | repaint() |
void | repaint(long ms) Repaint node itself -- not in content coordinates. |
void | scrollTo() Scroll to show the node on the screen. |
void | scrollTo(int dx, int dy, boolean pickplace)
Scroll to show the node on the screen. |
abstract void | setName(String name) |
void | setParentNode(INode p) Used by IScrollPane to point scrollbars at it without it pointing at scrollbar. |
void | setValid(boolean state)
Set dirty bit in this node only. |
int | size()
Number of addressable components in node: number of children in INode,
number of letters in text leaf, zero for invisible nodes such as comments,
and otherwise usually one (the default). |
int | sizeSticky() |
static Node[] | spanChunky(Mark l, Mark r) |
static Node[] | spanChunky(Node l, Node r) |
int | structChildNum() |
String | toString() |
public byte align
Justification (LEFT, RIGHT, CENTER, FILL/JUSTIFY) -- set with style sheet if possible.
public static final byte ALIGN_INVALID
Alignment.
public static final String ATTR_ID
public static final String ATTR_SCRIPT
public int baseline
Baseline, relative to top of bounding box.
public static final byte BASELINE
Alignment.
public Rectangle bbox
Bounding box, in pixels, location relative to parent node.
Bounding box of internal node encloses all children.
public static final byte BOTH
Alignment.
public static final byte BOTTOM
Alignment.
public static final byte CENTER
Alignment.
public static final byte CHAR
Alignment.
public static final byte FILL
Alignment.
public byte floats
If floating object, side (LEFT or RIGHT) -- set with style sheet if possible.
public static final byte INHERIT
Alignment.
public static final byte JUSTIFY
Alignment.
public static final byte LEFT
Alignment.
protected static final int MAXNONSTRUCTDEPTH
public static final byte MIDDLE
Alignment.
protected String name_
Name of node, like PARA or SECT for structural nodes, ASCII translation for leaves.
Non-textual leaves should put something sensible here, e.g., HTML's ALT for images.
Media adaptor may intern name String, but such is not guaranteed by this class.
Access with getName()/setName().
public static final byte NONE
Alignment.
Behaviors that have registered interest in this node.
For each phase, these behaviors have their phaseBefore and phaseAfter methods called
every time the tree walk for that protocol traverses the node.
public static final int PROBEWIDTH
Some layouts ask contents how big they'd like to be, and some content will take all they can get,
as when centering or HTML HR. If passed layout width > PROBEWIDTH/2 (so not folled by chipped off margins/borders/padding/general fuzz),
then be nice and take little.
Used by HTML TABLE.
public static final byte RIGHT
Alignment.
List<> of marks on leaves, subtree summaries on internal nodes. Not for general use.
protected short stickycnt_
public static final byte TOP
Alignment.
protected boolean valid_
Layout dirty bit. True after formatting, false if need to be formatted before next painting.
public byte valign
Vertical alignment -- set with style sheet if possible.
public Node(String name, Map<String,Object> attrs,
INode parent)
Create a node with the given name, attributes and parent, any of which can be null.
A null name is used for non-structural internal nodes, null attributes are the same
as an empty set but use less memory, and a null parent can be set later with INode.appendChild().
Map attributes object is not cloned.
See Also: INode
public final void addObserver(
Behavior be)
Observers get called when node is encountered in tree walk protocols (format, paint, low-level event),
protocolBefore and
protocolAfter methods.
Patterned after java.util.Observable where applicable.
Observers not sorted in priority order, as they don't necessary have a priority (implements ContextListener), though they probably should be sorted.
At most one instance of a behavior be in the set of observer on a node at a time.
See Also: java.util.Observable
public void addSticky(
Mark m)
public void addSticky(
Mark m, boolean sequence)
public boolean breakAfter()
public boolean breakBefore()
public boolean checkRep()
public final int childNum()
public final void clipboardBeforeAfter(StringBuffer txt)
Depth-first tree traversal to build selection.
Before and after methods invoked here; actual selection passed on to clipboardNode().
public abstract void clipboardNode(StringBuffer txt)
To build up selection, pass a StringBuffer to media-specific leaves,
which fill it as appropriate for that medium.
Need to fix this to respect subelement addressing
protected Object clone()
Deep copy of Rectangle; observers and sticky set to null.
Need to clone when edit and split a Node.
public static int cmp(
Node ln, int lo,
Node rn, int ro,
INode top)
Does first (node,offset) come before (-1), at (0), or after (1) second (node,offset)?
Also returns 0 if two nodes are not in same subtree and so are incomparable, or one node is null.
Spans, especially the selection, use to swap endpoints if necessary to ensure that start comes before end.
Parameters: top - guaranteed common ancestor of ln and rn, e.g., some Document, or null if unknown.
Parameters: top - guaranteed common ancestor of ln and rn, e.g., some Document, or null if unknown.
Returns: null iff nodes not in same tree
public boolean contains(Point p)
Nodes say whether it wants to see activity at point, regardless of bbox.
public boolean contains(
Node n)
public void dump()
public void dump(int maxlevel)
public void dump(int level, int maxlevel)
Dump more verbose than toString().
public abstract int dx()
X-coordinate transformation needed when entering this node's relative coordinate system.
public abstract int dy()
Y-coordinate transformation needed when entering this node's relative coordinate system.
public boolean eventBeforeAfter(AWTEvent e, Point rel)
Pass tree event. Translates coordinates to relative, calls observers, untranslates coordinates.
public abstract boolean eventNode(AWTEvent e, Point rel)
Process java.awt.Event or multivalent.TreeEvent (not multivalent.SemanticEvent).
See Also: TreeEvent SemanticEvent
public
Node findBFS(String searchname, String attrname, String attrval, int maxlevel)
Breadth-first search for node with given name (generic identifier), attribute name, and attribute value.
Set parameter to null
if don't care/match anything, e.g., set node name and attribute value to
null
if just want any node that has the given attribute.
Setting attribute name to null and attribute value to non-null has the same effect as setting both to null.
public final
Node findBFS(String searchname)
Breath-first search for node with given name (generic identifier).
public final
Node findBFS(String searchname, String attrname, String attrval)
public
Node findDFS(String searchname, String attrname, String attrval, int maxlevel)
Depth-first search for node with requested combination of name, attribute name, and attribute value.
Set to
null if don't care/match anything, e.g., set node name and attribute value to
null if just want node to have some node with the given attribute.
Setting attribute name to null and attribute value to non-null has the same effect as setting both to null.
More efficient than
findBFS.
For example, this can be used to find node with given
id attribute
with the following
doc.findDFS(null, "id", desired-id-value, Integer.MAX_VALUE)
.
protected
Node findDFS(String searchname, String attrname, String attrval, int level, int maxlevel)
public final
Node findDFS(String searchname)
Depth-first search for Node with given name.
public final
Node findDFS(String searchname, String attrname, String attrval)
Depth-first search for Node with given name and (name, val) attribute pair.
public boolean formatBeforeAfter(int width, int height,
Context cx)
In the depth-first tree traversal to format tree,
Before and after methods of behavior observers invoked here; actual formatting passed on to formatNode().
In documents with layed out content, children set their dimensions and parents set their location.
In documents with absolutely positioned content, usually leaves position themselves and internal nodes compute relative coordinates.
If node is valid, its entire subtree is assumed formatted and this method returns without doing anything.
Behavior observers return
true to shortcircuit traversal of subtree, which this method on Node passes back up the tree.
Parameters: width of screen, or fraction thereof available to be taken by node height of screen, or fraction thereof available to be taken by node (largely ignored in HTML, which has infinitely long scroll, except in FRAME)
See Also: Behavior
public abstract boolean formatNode(int width, int height,
Context cx)
Override this to specialize the natual layout of a node.
public Point getAbsLocation()
Determine location of node in absolute coordinates, as opposed to parent-relative.
Collect active behaviors at point: spans, style sheet settings.
Want to pick up formatting and painting at an arbitrary point, INode or Leaf,
so have to establish graphics context anyplace.
public Rectangle getBbox()
Return node bounding box. (Not a copy.)
Chains up parent links. @return null if none.
Chains up parent links until find (lowest enclosing) Document. @return null if none.
public
Node getElementById(String elementId)
public abstract
Leaf getFirstLeaf()
Chains up parent links. @return null if none.
public abstract
Leaf getLastLeaf()
public final String getName()
public
Leaf getNextLeaf()
Get the following leaf in a left-to-right traversal, returning null if none.
Same as getNextNode().getFirstLeaf() plus a null check.
Easy to collect the content of a span with this method.
public
Node getNextNode()
Get the node immediately following in a depth-first tree walk, returning null if none.
public final String getNodeName()
DOM2 nomenclature -- since method on a Node, why not "getName()"?
public final List<
Behavior> getObservers()
Needed by Document to do clipboardBeforeAfter on root before selection. Not for general use.
public final
INode getParentNode()
DOM2 nomenclature (why not "getParent()"?).
public
Leaf getPrevLeaf()
Get the previous leaf in a left-to-right traversal, returning null if none.
Same as getPrevNode().getLastLeaf() with null check.
Easy to collect the content of a span with this method.
public
Node getPrevNode()
Get the node immediately previous in a depth-first tree walk, returning null if none.
public final Point getRelLocation(
Node relto)
Determine location of node relative to passed node, as for instance location of image relative to its Document.
Chains up parent links. @return null if none.
public
Mark getSticky(int inx)
public int indexSticky(
Mark m)
public boolean intersects(Rectangle r)
Nodes say whether it wants to see activity in rectangular region, regardless of bbox.
public boolean isLeaf()
public boolean isStruct()
public final boolean isValid()
public final void markDirty()
Mark dirty--setValid(false)--and chain of nodes up to lowest IScrollPane.
Presently, formatting takes place top down from the root (unless you call reformat) immediately before painting,
so to get formatted, use this to mark a dirty path from the node up to the root (up tree only, including self).
If an INode needs to reformat all content too (as to reflow based on new width),
as opposed to reformatting an affected subtree, also call markDirtySubtree().
public void markDirtySubtree(boolean leavestoo)
Mark dirty all nodes in subtree and path to root (up and down tree).
If leaf node dimensions are still valid, can save about half the reformatting time by not marking them dirty (pass false).
When markDirty() is obsolete, kill and rename markDritySubtreeDown to this.
public abstract void markDirtySubtreeDown(boolean leavestoo)
Mark dirty all nodes in subtree (down tree only).
public void markDirtyTo(
Node rn)
Mark dirty all nodes in a span, parents included. Used by Span but possibly generally useful.
public void morphInto(
Node l)
Transfers content into passed Node, destroying original and replacing it in tree.
Current node becomes invalid and should not be used subsequently.
public void paintBeforeAfter(Rectangle docclip,
Context cx)
Depth-first tree traversal to paint tree.
Before and after methods of observers invoked here; actual painting passed on to paintNode().
Leaves actually do painting; parents just iterate over children.
Efficiently redraws just area overlapping clipping rectangle.
Subclasses should check to see that node overlaps clip, and if so, update origin and clip, call super.paintBeforeAfter() (which will call paintNode()), then restore origin and clip.
Determine if node within the current clipping region;
if so, translate origin and clip, call observers (paintBeforeAfter), paint self (and children if any), restore origin and clip.
Classes INode and Leaf do that, and almost nodes subclasses them, so subclasses can freely
override paintNode (by INode's) and paintNodeContent (by Leaf's).
Use Graphics.translate() and Graphics.setClipBounds() in place
of any temptation to use Graphics.create() as sometimes new Graphics objects are substituted
and Graphics.create() doesn't copy the tweaks.
Translate Graphics and clipping rectangle for node's (x,y) and margin (margins)
in same coordinate space as node, with same graphics context
Invariant: Graphics and cliprect set correctly at paintBeforeAfter().
INode changes according to child's bbox and own margin in paintNode.
LATER: parallel physical layout trees rather that on structure tree, for more flexible layout and multiple views.
LATER: pass in List<> of flow regions (Dimension's), cut out what you need, protocol to ask for more (new column or page).
Returns: true to shortcircuit traversal of subtree.
public abstract void paintNode(Rectangle docclip,
Context cx)
public void reformat(
Node bogus)
High performance reformatting of subtree.
Edits to the document tree need to reformat the tree to update the display.
Ordinarily this is quite efficient. The path from the change to the root is marked dirty,
all changes are batch together in a format that happens at the next paint,
and during reformatting nodes that are still clean are not reformatted.
However some applications, such as interactive editing and the display of status messages,
need the best possible performance. If the range of changes can be bounded in some subtree,
such that if the dimensions (width and height) of the subtree remain the same after reformatting,
then reformatting can be speeded up.
This rules out floats and HTML tables that compute cell widths based on the needs of their contents.
(If the new dimensions are not the same, then
fall back to the above guaranteed correct but possibly slower reformatting.)
Subclasses override this method for correctness for that node or for greater performance.
An HTML table may compute cell widths based on the relative needs of cell contents,
and so for correctness, in general, needs a complete reformat of the table.
IParaBox can improve performance by skipping over
previous words in the paragraph, and stop reformatting if the change fits on the same line.
To use, first Node with false
on node that contains all the changes,
then make changes in the subtree, and then invoke this method on that node.
Parameters: smallerok set to true
if reformatting should be considered complete
if the dimensions of the new subtree are smaller, in addition to the case where they are exactly the same.
public void remove()
Simple remove node from parent.
See Also: removeTidy
public void removeSticky(
Mark m)
public void removeSticky(int inx)
public void removeTidy(
INode root)
Remove node from tree tidily:
don't leave behind empty INode, recursively up to
root.
See Also: remove
public void repaint(long ms, int x, int y, int w, int h)
Redraw portion of node within ms milliseconds.
Translates coordinates from relative to screen as ascend tree.
Like java.awt.Component's repaint().
public void repaint(int x, int y, int w, int h)
public void repaint()
public void repaint(long ms)
Repaint node itself -- not in content coordinates.
public void scrollTo()
Scroll to show the node on the screen.
public void scrollTo(int dx, int dy, boolean pickplace)
public abstract void setName(String name)
public void setParentNode(
INode p)
Used by IScrollPane to point scrollbars at it without it pointing at scrollbar. Not for general use.
public final void setValid(boolean state)
Set dirty bit
in this node only.
See Also: markDirty
public int size()
Number of addressable components in node: number of children in INode,
number of letters in text leaf, zero for invisible nodes such as comments,
and otherwise usually one (the default).
public int sizeSticky()
public final int structChildNum()
public String toString()