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.

Version: $Revision: 1.16 $ $Date: 2003/06/02 05:09:28 $

See Also: MediaAdaptor Root Document Behavior

Field Summary
bytealign
Justification (LEFT, RIGHT, CENTER, FILL/JUSTIFY) -- set with style sheet if possible.
static byteALIGN_INVALID
Alignment.
static StringATTR_ID
static StringATTR_SCRIPT
Associated VScript script.
intbaseline
Baseline, relative to top of bounding box.
static byteBASELINE
Alignment.
Rectanglebbox
Bounding box, in pixels, location relative to parent node.
static byteBOTH
Alignment.
static byteBOTTOM
Alignment.
static byteCENTER
Alignment.
static byteCHAR
Alignment.
static byteFILL
Alignment.
bytefloats
If floating object, side (LEFT or RIGHT) -- set with style sheet if possible.
static byteINHERIT
Alignment.
static byteJUSTIFY
Alignment.
static byteLEFT
Alignment.
protected static intMAXNONSTRUCTDEPTH
static byteMIDDLE
Alignment.
protected Stringname_
Name of node, like PARA or SECT for structural nodes, ASCII translation for leaves.
static byteNONE
Alignment.
protected List<Behavior>observers_
Behaviors that have registered interest in this node.
protected INodeparent_
Parent node in tree - access with getParentNode.
static intPROBEWIDTH
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 byteRIGHT
Alignment.
protected Mark[]sticky_
List<> of marks on leaves, subtree summaries on internal nodes.
protected shortstickycnt_
static byteTOP
Alignment.
protected booleanvalid_
Layout dirty bit.
bytevalign
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
voidaddObserver(Behavior be)
Observers get called when node is encountered in tree walk protocols (format, paint, low-level event), protocolBefore and protocolAfter methods.
voidaddSticky(Mark m)
voidaddSticky(Mark m, boolean sequence)
booleanbreakAfter()
booleanbreakBefore()
booleancheckRep()
intchildNum()
voidclipboardBeforeAfter(StringBuffer txt)
Depth-first tree traversal to build selection.
abstract voidclipboardNode(StringBuffer txt)
To build up selection, pass a StringBuffer to media-specific leaves, which fill it as appropriate for that medium.
protected Objectclone()
Deep copy of Rectangle; observers and sticky set to null.
static intcmp(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)?
NodecommonAncestor(Node b)
NodecommonAncestor(Node b, Node top)
booleancontains(Point p)
Nodes say whether it wants to see activity at point, regardless of bbox.
booleancontains(Node n)
voiddeleteObserver(Behavior be)
voiddump()
voiddump(int maxlevel)
voiddump(int level, int maxlevel)
Dump more verbose than toString().
abstract intdx()
X-coordinate transformation needed when entering this node's relative coordinate system.
abstract intdy()
Y-coordinate transformation needed when entering this node's relative coordinate system.
booleaneventBeforeAfter(AWTEvent e, Point rel)
Pass tree event.
abstract booleaneventNode(AWTEvent e, Point rel)
Process java.awt.Event or multivalent.TreeEvent (not multivalent.SemanticEvent).
NodefindBFS(String searchname, String attrname, String attrval, int maxlevel)
Breadth-first search for node with given name (generic identifier), attribute name, and attribute value.
NodefindBFS(String searchname)
Breath-first search for node with given name (generic identifier).
NodefindBFS(String searchname, String attrname, String attrval)
NodefindDFS(String searchname, String attrname, String attrval, int maxlevel)
Depth-first search for node with requested combination of name, attribute name, and attribute value.
protected NodefindDFS(String searchname, String attrname, String attrval, int level, int maxlevel)
NodefindDFS(String searchname)
Depth-first search for Node with given name.
NodefindDFS(String searchname, String attrname, String attrval)
Depth-first search for Node with given name and (name, val) attribute pair.
booleanformatBeforeAfter(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 booleanformatNode(int width, int height, Context cx)
Override this to specialize the natual layout of a node.
PointgetAbsLocation()
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.
RectanglegetBbox()
Return node bounding box.
BrowsergetBrowser()
Chains up parent links.
DocumentgetDocument()
Chains up parent links until find (lowest enclosing) Document.
NodegetElementById(String elementId)
abstract LeafgetFirstLeaf()
IScrollPanegetIScrollPane()
Chains up parent links.
abstract LeafgetLastLeaf()
StringgetName()
LeafgetNextLeaf()
Get the following leaf in a left-to-right traversal, returning null if none.
NodegetNextNode()
Get the node immediately following in a depth-first tree walk, returning null if none.
StringgetNodeName()
DOM2 nomenclature -- since method on a Node, why not "getName()"?
List<Behavior>getObservers()
Needed by Document to do clipboardBeforeAfter on root before selection.
INodegetParentNode()
DOM2 nomenclature (why not "getParent()"?).
LeafgetPrevLeaf()
Get the previous leaf in a left-to-right traversal, returning null if none.
NodegetPrevNode()
Get the node immediately previous in a depth-first tree walk, returning null if none.
PointgetRelLocation(Node relto)
Determine location of node relative to passed node, as for instance location of image relative to its Document.
RootgetRoot()
Chains up parent links.
MarkgetSticky(int inx)
intindexSticky(Mark m)
booleanintersects(Rectangle r)
Nodes say whether it wants to see activity in rectangular region, regardless of bbox.
booleanisLeaf()
booleanisStruct()
booleanisValid()
voidmarkDirty()
Mark dirty--setValid(false)--and chain of nodes up to lowest IScrollPane.
voidmarkDirtySubtree(boolean leavestoo)
Mark dirty all nodes in subtree and path to root (up and down tree).
abstract voidmarkDirtySubtreeDown(boolean leavestoo)
Mark dirty all nodes in subtree (down tree only).
voidmarkDirtyTo(Node rn)
Mark dirty all nodes in a span, parents included.
voidmorphInto(Node l)
Transfers content into passed Node, destroying original and replacing it in tree.
voidpaintBeforeAfter(Rectangle docclip, Context cx)
Depth-first tree traversal to paint tree.
abstract voidpaintNode(Rectangle docclip, Context cx)
voidreformat(Node bogus)
High performance reformatting of subtree.
voidremove()
Simple remove node from parent.
voidremoveSticky(Mark m)
voidremoveSticky(int inx)
voidremoveTidy(INode root)
Remove node from tree tidily: don't leave behind empty INode, recursively up to root.
voidrepaint(long ms, int x, int y, int w, int h)
Redraw portion of node within ms milliseconds.
voidrepaint(int x, int y, int w, int h)
voidrepaint()
voidrepaint(long ms)
Repaint node itself -- not in content coordinates.
voidscrollTo()
Scroll to show the node on the screen.
voidscrollTo(int dx, int dy, boolean pickplace)
Scroll to show the node on the screen.
abstract voidsetName(String name)
voidsetParentNode(INode p)
Used by IScrollPane to point scrollbars at it without it pointing at scrollbar.
voidsetValid(boolean state)
Set dirty bit in this node only.
intsize()
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).
intsizeSticky()
static Node[]spanChunky(Mark l, Mark r)
static Node[]spanChunky(Node l, Node r)
intstructChildNum()
StringtoString()

Field Detail

align

public byte align
Justification (LEFT, RIGHT, CENTER, FILL/JUSTIFY) -- set with style sheet if possible.

ALIGN_INVALID

public static final byte ALIGN_INVALID
Alignment.

ATTR_ID

public static final String ATTR_ID

ATTR_SCRIPT

public static final String ATTR_SCRIPT
Associated VScript script.

See Also: VButton

baseline

public int baseline
Baseline, relative to top of bounding box.

BASELINE

public static final byte BASELINE
Alignment.

bbox

public Rectangle bbox
Bounding box, in pixels, location relative to parent node. Bounding box of internal node encloses all children.

BOTH

public static final byte BOTH
Alignment.

BOTTOM

public static final byte BOTTOM
Alignment.

CENTER

public static final byte CENTER
Alignment.

CHAR

public static final byte CHAR
Alignment.

FILL

public static final byte FILL
Alignment.

floats

public byte floats
If floating object, side (LEFT or RIGHT) -- set with style sheet if possible.

INHERIT

public static final byte INHERIT
Alignment.

JUSTIFY

public static final byte JUSTIFY
Alignment.

LEFT

public static final byte LEFT
Alignment.

MAXNONSTRUCTDEPTH

protected static final int MAXNONSTRUCTDEPTH

MIDDLE

public static final byte MIDDLE
Alignment.

name_

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().

NONE

public static final byte NONE
Alignment.

observers_

protected List<Behavior> observers_
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.

parent_

protected INode parent_
Parent node in tree - access with getParentNode.

PROBEWIDTH

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.

RIGHT

public static final byte RIGHT
Alignment.

sticky_

protected Mark[] sticky_
List<> of marks on leaves, subtree summaries on internal nodes. Not for general use.

stickycnt_

protected short stickycnt_

TOP

public static final byte TOP
Alignment.

valid_

protected boolean valid_
Layout dirty bit. True after formatting, false if need to be formatted before next painting.

valign

public byte valign
Vertical alignment -- set with style sheet if possible.

Constructor Detail

Node

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

Method Detail

addObserver

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

addSticky

public void addSticky(Mark m)

addSticky

public void addSticky(Mark m, boolean sequence)

breakAfter

public boolean breakAfter()

breakBefore

public boolean breakBefore()

checkRep

public boolean checkRep()

childNum

public final int childNum()

clipboardBeforeAfter

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().

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

clone

protected Object clone()
Deep copy of Rectangle; observers and sticky set to null. Need to clone when edit and split a Node.

cmp

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.

commonAncestor

public Node commonAncestor(Node b)

commonAncestor

public Node commonAncestor(Node b, Node top)

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

contains

public boolean contains(Point p)
Nodes say whether it wants to see activity at point, regardless of bbox.

contains

public boolean contains(Node n)

deleteObserver

public void deleteObserver(Behavior be)

dump

public void dump()

dump

public void dump(int maxlevel)

dump

public void dump(int level, int maxlevel)
Dump more verbose than toString().

dx

public abstract int dx()
X-coordinate transformation needed when entering this node's relative coordinate system.

dy

public abstract int dy()
Y-coordinate transformation needed when entering this node's relative coordinate system.

eventBeforeAfter

public boolean eventBeforeAfter(AWTEvent e, Point rel)
Pass tree event. Translates coordinates to relative, calls observers, untranslates coordinates.

eventNode

public abstract boolean eventNode(AWTEvent e, Point rel)
Process java.awt.Event or multivalent.TreeEvent (not multivalent.SemanticEvent).

See Also: TreeEvent SemanticEvent

findBFS

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.

findBFS

public final Node findBFS(String searchname)
Breath-first search for node with given name (generic identifier).

findBFS

public final Node findBFS(String searchname, String attrname, String attrval)

findDFS

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).

findDFS

protected Node findDFS(String searchname, String attrname, String attrval, int level, int maxlevel)

findDFS

public final Node findDFS(String searchname)
Depth-first search for Node with given name.

findDFS

public final Node findDFS(String searchname, String attrname, String attrval)
Depth-first search for Node with given name and (name, val) attribute pair.

formatBeforeAfter

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

formatNode

public abstract boolean formatNode(int width, int height, Context cx)
Override this to specialize the natual layout of a node.

getAbsLocation

public Point getAbsLocation()
Determine location of node in absolute coordinates, as opposed to parent-relative.

getActivesAt

public List<ContextListener> getActivesAt(int offset)

getActivesAt

public List<ContextListener> getActivesAt(int offset, boolean spansonly)

getActivesAt

public List<ContextListener> getActivesAt(int offset, List<ContextListener> base, boolean spansonly)
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.

getBbox

public Rectangle getBbox()
Return node bounding box. (Not a copy.)

getBrowser

public Browser getBrowser()
Chains up parent links. @return null if none.

getDocument

public Document getDocument()
Chains up parent links until find (lowest enclosing) Document. @return null if none.

getElementById

public Node getElementById(String elementId)

getFirstLeaf

public abstract Leaf getFirstLeaf()

getIScrollPane

public IScrollPane getIScrollPane()
Chains up parent links. @return null if none.

getLastLeaf

public abstract Leaf getLastLeaf()

getName

public final String getName()

getNextLeaf

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.

getNextNode

public Node getNextNode()
Get the node immediately following in a depth-first tree walk, returning null if none.

getNodeName

public final String getNodeName()
DOM2 nomenclature -- since method on a Node, why not "getName()"?

getObservers

public final List<Behavior> getObservers()
Needed by Document to do clipboardBeforeAfter on root before selection. Not for general use.

getParentNode

public final INode getParentNode()
DOM2 nomenclature (why not "getParent()"?).

getPrevLeaf

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.

getPrevNode

public Node getPrevNode()
Get the node immediately previous in a depth-first tree walk, returning null if none.

getRelLocation

public final Point getRelLocation(Node relto)
Determine location of node relative to passed node, as for instance location of image relative to its Document.

getRoot

public Root getRoot()
Chains up parent links. @return null if none.

getSticky

public Mark getSticky(int inx)

indexSticky

public int indexSticky(Mark m)

intersects

public boolean intersects(Rectangle r)
Nodes say whether it wants to see activity in rectangular region, regardless of bbox.

isLeaf

public boolean isLeaf()

isStruct

public boolean isStruct()

isValid

public final boolean isValid()

markDirty

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().

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.

markDirtySubtreeDown

public abstract void markDirtySubtreeDown(boolean leavestoo)
Mark dirty all nodes in subtree (down tree only).

markDirtyTo

public void markDirtyTo(Node rn)
Mark dirty all nodes in a span, parents included. Used by Span but possibly generally useful.

morphInto

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.

paintBeforeAfter

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.

  • paintNode

    public abstract void paintNode(Rectangle docclip, Context cx)

    reformat

    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.

    remove

    public void remove()
    Simple remove node from parent.

    See Also: removeTidy

    removeSticky

    public void removeSticky(Mark m)

    removeSticky

    public void removeSticky(int inx)

    removeTidy

    public void removeTidy(INode root)
    Remove node from tree tidily: don't leave behind empty INode, recursively up to root.

    See Also: remove

    repaint

    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().

    repaint

    public void repaint(int x, int y, int w, int h)

    repaint

    public void repaint()

    repaint

    public void repaint(long ms)
    Repaint node itself -- not in content coordinates.

    scrollTo

    public void scrollTo()
    Scroll to show the node on the screen.

    scrollTo

    public void scrollTo(int dx, int dy, boolean pickplace)
    Scroll to show the node on the screen.

    See Also: for explanation of pickplace option.

    setName

    public abstract void setName(String name)

    setParentNode

    public void setParentNode(INode p)
    Used by IScrollPane to point scrollbars at it without it pointing at scrollbar. Not for general use.

    setValid

    public final void setValid(boolean state)
    Set dirty bit in this node only.

    See Also: markDirty

    size

    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).

    sizeSticky

    public int sizeSticky()

    spanChunky

    public static Node[] spanChunky(Mark l, Mark r)

    spanChunky

    public static Node[] spanChunky(Node l, Node r)

    structChildNum

    public final int structChildNum()

    toString

    public String toString()