Multivalent API

multivalent
Class Span

java.lang.Object
  extended by multivalent.VObject
      extended by multivalent.Behavior
          extended by multivalent.Span
All Implemented Interfaces:
ContextListener, EventListener, java.util.EventListener
Direct Known Subclasses:
ActionSpan, AnchorSpan, AwkSpan, BackgroundSpan, BlinkSpan, BoldSpan, BoxSpan, ElideSpan, FamilySpan, FontSpan, HyperlinkSpan, InvisibleSpan, ItalicSpan, LabelSpan, MonospacedSpan, MoveTextSpan, Notemark, OutlineSpan, OverstrikeSpan, PlainSpan, PointSpan, RelPointSpan, SelectionSpan, SidebarSpan, SignalSpan, SpanPDF, StrokeSpan, SubSupSpan, UnderlineSpan

public class Span
extends Behavior
implements ContextListener, EventListener

A Span (aka Range aka Tk tag), such as a hyperlink or executable copy editor mark, is a linear range of content that can control appearance and receives events. It efficiently covers any amount of tree, not restricted by structural node hierarchy. Spans are robust to insertions and deletions, during runtime and across save/restore editing of base document.

Span is not an abstract class, and in fact should be heavily used itself. It can be used to store metadata, via attributes. It can be created with a semantic name and its properties set in the style sheet. If a style sheet is independent of a style sheet (as with a user annotation), one should use a "general span". If different behavior is needed, as opposed to appearance, then subclasses are appropriate.

Version:
$Revision: 1.14 $ $Date: 2003/06/02 05:10:38 $
See Also:
Mark

Field Summary
static java.lang.String GI_END
           
static java.lang.String GI_START
           
static java.lang.String MSG_DELETE
          For use in interactive editing, deletes span, moving selection to old extent.
static java.lang.String MSG_EDIT
          Request for interactive editing of span attributes.
static java.lang.String MSG_MORPH
          For use in interactive editing, moves Span to extent of selection.
static java.lang.String MSG_UNATTACHED
          Announce span that could not be reattached with confidence.
 java.util.Map<java.lang.String,java.lang.Object> pend
           
 java.util.Map<java.lang.String,java.lang.Object> pstart
           
 
Fields inherited from class multivalent.Behavior
ATTR_BEHAVIOR, name_
 
Fields inherited from class multivalent.VObject
attr_
 
Fields inherited from interface multivalent.ContextListener
LITTLE, LOT, PRIORITY_LENS, PRIORITY_MAX, PRIORITY_MIN, PRIORITY_SELECTION, PRIORITY_SPAN, PRIORITY_STRUCT, SOME
 
Constructor Summary
Span()
           
 
Method Summary
 boolean appearance(Context cx, boolean all)
          Resets the graphics context every time the object is added to or dropped from the set active over the portion of the document being drawn.
 void buildAfter(Document doc)
          Attach to document tree based on saved anchor description.
 boolean checkRep()
          Checks "representation invariant" (see MIT SE), and returns true iff object is valid, which should be always
 boolean close(Node end)
          Close span at end of passed Node, and attach Span to tree.
static int closeAll(Node subtree)
          Close all spans in subtree.
 boolean contains(Mark m)
           
 boolean contains(Node n, int off)
          Is (Node, offset) contained within span?
 void destroy()
          Removes span from document and its layer.
 void event(java.awt.AWTEvent e)
          Receives synthesized MouseEvent.MOUSE_ENTERED, MouseEvent.MOUSE_EXITED, MouseEvent.MOUSE_PRESSED, ....
 Mark getEnd()
          (Node, offset) of end of span.
 int getPriority()
          Self-reported priority relative to others of the same class, e.g., other spans.
 Mark getStart()
          (Node, offset) of start of span.
 boolean isSet()
          Is Span attached to tree?
 void markDirty()
           
 void move(Leaf ln, int lo, Leaf rn, int ro)
          Save move, for interactive use: selection, annotations.
 void move(Mark l, Mark r)
           
 void move(Span s)
          Span endpoints assumed valid; just moveq + reformatting and repainting.
 void moveq(Leaf ln, int lo, Leaf rn, int ro)
          "move quick" just updates summaries, so more efficient than move(), if caller: guarantees that first node comes before second node (so the system doesn't have to spend time checking this), and handles all reformatting and repainting (including marking tree nodes dirty) Useful using during initial tree builds, when adding spans and formatting in batch(es).
 void moveq(Mark start, Mark end)
           
 void moveq(Span span)
          Useful to morph to the selection.
 void moveqSwap(Leaf ln, int lo, Leaf rn, int ro)
          Like moveq(), swapping endpoints if necessary, so that left comes before right in tree order.
 void open(Node start)
          During document creation, open span at first leaf to be created after passed node.
 void repaint()
           
 void repaint(long ms)
          Repaints smallest subtree containing both endpoints.
 void restore(ESISNode n, java.util.Map<java.lang.String,java.lang.Object> attr, Layer layer)
          Given ESIS subtree, pluck class-specific information from attributes, call super.restore() for locations.
 ESISNode save()
          Stuff instance state into attributes; if save buffer not null, write out corresponding XML.
 boolean semanticEventAfter(SemanticEvent se, java.lang.String msg)
          Recognize "deleteSpan " and "morphSpan ".
 boolean semanticEventBefore(SemanticEvent se, java.lang.String msg)
          Morphing and deletion menu items in popup.
static void stretch(Leaf l, INode within)
          Removing leaf from tree, but preserve its span transitions by stretching end transitions to previous node and start transitions to next node.
 java.lang.String toString()
          Subclasses should extend to check any attributes they add.
 
Methods inherited from class multivalent.Behavior
buildBefore, clipboardAfter, clipboardBefore, createUI, eventAfter, eventBefore, formatAfter, formatBefore, getBrowser, getDocument, getInstance, getInstance, getLayer, getLogger, getName, getPreference, getRoot, isEditable, paintAfter, paintBefore, putPreference, redo, restoreChildren, setName, undo
 
Methods inherited from class multivalent.VObject
attrEntrySetIterator, attrKeysIterator, clearAttributes, getAttr, getAttr, getAttributes, getGlobal, getValue, hasAttributes, putAttr, removeAttr, setAttributes
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MSG_DELETE

public static final java.lang.String MSG_DELETE
For use in interactive editing, deletes span, moving selection to old extent.

"deleteSpan".

See Also:
Constant Field Values

MSG_MORPH

public static final java.lang.String MSG_MORPH
For use in interactive editing, moves Span to extent of selection.

"morphSpan".

See Also:
Constant Field Values

MSG_EDIT

public static final java.lang.String MSG_EDIT
Request for interactive editing of span attributes.

"editSpan".

See Also:
Constant Field Values

MSG_UNATTACHED

public static final java.lang.String MSG_UNATTACHED
Announce span that could not be reattached with confidence.

"unattachedSpan": arg= Span instance.

See Also:
Constant Field Values

GI_START

public static final java.lang.String GI_START
See Also:
Constant Field Values

GI_END

public static final java.lang.String GI_END
See Also:
Constant Field Values

pstart

public java.util.Map<java.lang.String,java.lang.Object> pstart

pend

public java.util.Map<java.lang.String,java.lang.Object> pend
Constructor Detail

Span

public Span()
Method Detail

getStart

public final Mark getStart()
(Node, offset) of start of span.


getEnd

public final Mark getEnd()
(Node, offset) of end of span.


isSet

public boolean isSet()
Is Span attached to tree?


getPriority

public int getPriority()
Description copied from interface: ContextListener
Self-reported priority relative to others of the same class, e.g., other spans. Use the constants defined here, such as ContextListener.PRIORITY_LENS, modified by ContextListener.LITTLE/ContextListener.SOME/{#link LOT}.

Specified by:
getPriority in interface ContextListener

appearance

public boolean appearance(Context cx,
                          boolean all)
Description copied from interface: ContextListener
Resets the graphics context every time the object is added to or dropped from the set active over the portion of the document being drawn. These behaviors can come from the style sheet, be ad hoc spans, be lenses, or come from elsewhere. Should be fast.

Specified by:
appearance in interface ContextListener
all - all attributes or exclude those that are not inherited

open

public void open(Node start)
During document creation, open span at first leaf to be created after passed node. Typically, document formats begin spans before the content to which they apply has been seen, which means bookkeeping for the span name, type, start point, attributes and so on for when then end of span is seen, and adjusting the start point to the first leaf created after last node known at open. Instead, media adaptors can create the span and configure it and set the start point with open with the last node created, which can be an internal node, and close(Node) adjusts the start point. If both start and end points already exist, use moveq(Leaf,int, Leaf,int). All spans opened should be closed.

See Also:
and, for examples of use

close

public boolean close(Node end)
Close span at end of passed Node, and attach Span to tree. Since this is used during tree construction, no nodes are marked dirty as that would be redundant. If the span cannot be attached, the caller probably wants to destroy() it; however, the HTML media adaptor takes the case of HTML 0-length >a name=...< spans and instead attaches and 'id' attribute to the previous node.

Returns:
true if attached span, false if couldn't attach or 0-length

closeAll

public static int closeAll(Node subtree)
Close all spans in subtree. Useful in a couple ways: for a media adaptor to conveniently and concisely close all pending spans at the end of a document, and to guarantee that all spans are closed even if an explicit end to the span is missing in the concrete document.

Returns:
count of spans successfully attached to tree

move

public void move(Leaf ln,
                 int lo,
                 Leaf rn,
                 int ro)
Save move, for interactive use: selection, annotations. Sets start point < end point, handles necessary reformatting and repainting. Reformats both old range and new range, as with style sheets and hardcode in subclasses, can't tell when that's not necessary. (Or, moveq() + swapping endpoints if necessary + reformatting/repainting.)


move

public void move(Span s)
Span endpoints assumed valid; just moveq + reformatting and repainting.


move

public void move(Mark l,
                 Mark r)

moveqSwap

public void moveqSwap(Leaf ln,
                      int lo,
                      Leaf rn,
                      int ro)
Like moveq(), swapping endpoints if necessary, so that left comes before right in tree order.


moveq

public void moveq(Leaf ln,
                  int lo,
                  Leaf rn,
                  int ro)
"move quick" just updates summaries, so more efficient than move(), if caller:
  1. guarantees that first node comes before second node (so the system doesn't have to spend time checking this), and
  2. handles all reformatting and repainting (including marking tree nodes dirty)
Useful using during initial tree builds, when adding spans and formatting in batch(es). Checks that endpoint offsets are valid, that is, >=0 and

moveq

public void moveq(Mark start,
                  Mark end)

moveq

public void moveq(Span span)
Useful to morph to the selection.


contains

public boolean contains(Node n,
                        int off)
Is (Node, offset) contained within span?


contains

public boolean contains(Mark m)

stretch

public static void stretch(Leaf l,
                           INode within)
Removing leaf from tree, but preserve its span transitions by stretching end transitions to previous node and start transitions to next node. If there is no previous node for and end transition, or next node for a start, the span is removed.


repaint

public void repaint(long ms)
Repaints smallest subtree containing both endpoints.


repaint

public void repaint()

destroy

public void destroy()
Removes span from document and its layer. Different from moveq(null), which removes from document tree but not from layer. If caller will handle all reformatting and repainting, as during a batch destory(), first moveq(null) on span.

Overrides:
destroy in class Behavior

markDirty

public void markDirty()

save

public ESISNode save()
Stuff instance state into attributes; if save buffer not null, write out corresponding XML. Subclass should override if have interesting content (can stuff content into attr then super.save()). If span is not attached to tree at save time, its old attachment points are retained. This way, spans that can't be attached presently can be tried again without degradation.

Overrides:
save in class Behavior

restore

public void restore(ESISNode n,
                    java.util.Map<java.lang.String,java.lang.Object> attr,
                    Layer layer)
Given ESIS subtree, pluck class-specific information from attributes, call super.restore() for locations. Attributes named start and end are reserved to hold Robust Location data.

Overrides:
restore in class Behavior
See Also:
RobustLocation

buildAfter

public void buildAfter(Document doc)
Attach to document tree based on saved anchor description. Not used/needed during creation of fresh spans as during interactive annotation.

Overrides:
buildAfter in class Behavior

semanticEventBefore

public boolean semanticEventBefore(SemanticEvent se,
                                   java.lang.String msg)
Morphing and deletion menu items in popup.

Overrides:
semanticEventBefore in class Behavior

semanticEventAfter

public boolean semanticEventAfter(SemanticEvent se,
                                  java.lang.String msg)
Recognize "deleteSpan " and "morphSpan ".

Overrides:
semanticEventAfter in class Behavior

event

public void event(java.awt.AWTEvent e)
Receives synthesized MouseEvent.MOUSE_ENTERED, MouseEvent.MOUSE_EXITED, MouseEvent.MOUSE_PRESSED, .... For the purposes of event passing, functions more as tree node than behavior (with before/after).

Specified by:
event in interface EventListener

checkRep

public boolean checkRep()
Description copied from class: VObject
Checks "representation invariant" (see MIT SE), and returns true iff object is valid, which should be always.

Overrides:
checkRep in class Behavior

toString

public java.lang.String toString()
Subclasses should extend to check any attributes they add.

Overrides:
toString in class Behavior
Parameters:
endpoints - if false, don't consider endpoints. public boolean equals(Object o, boolean endpoints) { return this == o; ? if (this == o) return true; if (o==null || !(o instanceof Span)) return false; Span span2 = (Span)o; boolean eq = true; if (eq && endpoints) { eq = (!isSet() && !span2.isSet()) || (getStart().equals(span2.getStart()) && getEnd().equals(span2.getEnd())); // check pstart and pend too? } if (eq) eq = getName().equals(span2.getName()); // attributes ... return eq; }

Multivalent API