Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Multivalent API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## multivalent
Class Span

    java.lang.Object
      multivalent.VObject
          multivalent.Behavior
              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.

- moving: `open(Node)`, `close(Node)` / `closeAll(Node)`, `move(Leaf,int, Leaf,int)` / `Span` / `Mark`, `moveq(Leaf,int, Leaf,int)` / `Span` / `Mark`
- relationship to tree: `getStart()`, `getEnd()`, `isSet()`, `contains(Node,int)` / `Mark`
- editing-related: `stretch(Leaf,INode)`,
- display and events: `getPriority()`, `appearance(Context, boolean)`, `repaint()` / `long`, `markDirty()`,
- events: `getPriority()`, `event(AWTEvent)`

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 `open`ed should be `close`d.

  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; }

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Multivalent API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD