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 Behavior

    java.lang.Object
      multivalent.VObject
          multivalent.Behavior

Direct Known Subclasses:
  About, Action, Anno, Annos, AttrUI, Autosearch, BindingsDefault, BindingsEmacs, BindingsMacintosh, BindingsTk, BindingsWindoze, Bookmark, BrowseScrollViz, CacheControl, ClipMarkup, ClipProvenance, ContractualObligation, Cookies, CursorMark, Debug, DebugMode, DeleteBehavior, DisableTree, DnD, DocumentPopup, Executive, FontFaceMenu, FontRender, ForwardBack, History, HttpHeaders, Layer, LayerMan, Lens, LensMan, LinkMarkup, LinkMe, ManualPageVolume, MediaAdaptor, MediaLoader, Menubar, Multipage, NodeActivity, Note, OcrView, OpenFile, Outliner, OutlineUI, PauseNGo, PersonalAnnos, PhoneMe, Print, PublishAnno, RemoteControl, ReportBug, RestoreReport, ReverseLink, Robust, RobustReport, SaveAnnoAs, SaveAs, ScrollbarViz, Search, SearchHit, SeeMono, SelectionUI, SemanticUI, ShowDocTree, ShowHeaders, SimpleAnchorScrollTo, SlideShow, SlideShowLinks, Span, SpanUI, SpeedRead, StandardEdit, StandardFile, Stats, Stop, StyleSheetSetter, SystemEvents, TableSort, Toolbar, ViewSource, WindowUI, Zoom

public abstract class Behavior
extends VObject

The Behavior is the primary way to extend the system. In fact, behaviors realize all user-level functionality. Behaviors have great power and access to all parts of the system.

- `behavior creation`
- accessors: `getName()`, `getLayer()`,
- Protocols: `restore`, build (`before` / `after`, format (`before` / `after`, paint (`before` / `paintAfter(Context, Node)`, clipboard (`clipboardBefore(StringBuffer, Node)` / `clipboardAfter(StringBuffer, Node)`, semantic events (`semanticEventBefore(SemanticEvent, String)` / `semanticEventAfter(SemanticEvent, String)`, low-level events (`eventBefore(AWTEvent, Point, Node)` / `eventAfter(AWTEvent, Point, Node)`), `destroy`.
- convenience: `getDocument()`, `getRoot()`, `getBrowser()`, preferences `get` / `set`
- software engineering: `getLogger()`, `checkRep()`
- (temporary user interface building: `createUI(String, String, Object, INode, String, boolean)`)

All behaviors must subclass this class and override the proper protocol methods (build, format, paint, and so on, most with before and after phases) and take the appropriate action when called upon by the system framework. The system framework coordinates behaviors along protocols, and if a behavior adheres to proper implementation of the protocols, it should cooperate well with arbitrary other behaviors.

Behaviors should not define constructors. The system needs a `public` no-argument constructor, to restore by name (with `getInstance(String, String, ESISNode, Map, Layer)` which in turn uses `Class.forName(String)` and `Class.newInstance()`). The easiest way to accomplish this is to declare the class public and rely on the default no-argument constructor. (Do initialization in `restore(ESISNode, Map, Layer)`.)

The file `multivalent/devel/MyBehavior.java` in the source code .zip file is a convenient template for writing general behaviors. If a behavior is a `Span` or `Lens` or resembles the function of another behavior, you can instead copy that source code and modify it.

Version:
  $Revision: 1.15 $ $Date: 2005/07/05 04:23:24 $

Field Summary
`static java.lang.String` | `ATTR_BEHAVIOR` Class name to instantiate for behavior.
`protected java.lang.String` | `name_` Logical name.

Fields inherited from class multivalent.VObject
`attr_`

Constructor Summary
`Behavior()`

Method Summary
`void` | `buildAfter(Document doc)` Traverses all behaviors from lowest to highest priority, during which tweaks hack their content into the tree,
`void` | `buildBefore(Document doc)` A round robin protocol, here traversing all behaviors from highest to lowest priority, during which main contributors of document content (called media adaptors) hack their content into the tree, and annotators set Marks to robust anchor to locations to hack in buildAfter so as not to disturb positioning by other annotations.
`boolean` | `checkRep()` Checks "representation invariant" (see MIT SE), and returns true iff object is valid, which should be always
`boolean` | `clipboardAfter(java.lang.StringBuffer sb, Node node)` A tree walk protocol, called after observed node has been given a chance to contribute to the growing selection content in the passed StringBuffer.
`boolean` | `clipboardBefore(java.lang.StringBuffer sb, Node node)` A tree walk protocol, called before observed node has been given a chance to contribute to the growing selection content in the passed StringBuffer.
`Node` | `createUI(java.lang.String type, java.lang.String title, java.lang.Object script, INode parent, java.lang.String category, boolean disabled)` Convenience function for UI building.
`void` | `destroy()` Protocol.
`boolean` | `eventAfter(java.awt.AWTEvent e, java.awt.Point rel, Node n)` During `eventBefore(AWTEvent, Point, Node)`, the behaviors that take primary action to that event should do so, after having given other behaviors the opportunity to filter it during `eventBefore`.
`boolean` | `eventBefore(java.awt.AWTEvent e, java.awt.Point rel, Node n)`
`boolean` | `formatAfter(Node node)` A tree walk protocol, called after observed node has been formatted.
`boolean` | `formatBefore(Node node)` A tree walk protocol, called before observed node has been formatted.
`Browser` | `getBrowser()` Convenience method to fetch Browser from Layer.
`Document` | `getDocument()` Convenience method to fetch Document from Layer.
`static Behavior` | `getInstance(java.lang.String logicalname, java.lang.String behaviorclass, ESISNode children, java.util.Map<java.lang.String,java.lang.Object> attr, Layer layer)` Centralized behavior instantiation factory: instantiate all behaviors through this method -- never use `new behavior(...)`
`static Behavior` | `getInstance(java.lang.String logicalname, java.lang.String behaviorclass, java.util.Map<java.lang.String,java.lang.Object> attr, Layer layer)` Used in hub instantiation.
`Layer` | `getLayer()` Link to containing layer, which links to Document and so on to Root, Browser, Multivalent.
`static java.util.logging.Logger` | `getLogger()`
`java.lang.String` | `getName()` Returns the String used to instantiate the Behavior via `getInstance(String, String, Map, Layer)`.
`java.lang.String` | `getPreference(java.lang.String name, java.lang.String defaultval)` Convenience method for getting preference in class Multivalent.
`Root` | `getRoot()` Convenience method to fetch Root from Browser.
`boolean` | `isEditable()`
`boolean` | `paintAfter(Context cx, Node node)` A tree walk protocol, called before observed node has been painted.
`boolean` | `paintBefore(Context cx, Node node)` A tree walk protocol, called before observed node has been painted.
`void` | `putPreference(java.lang.String name, java.lang.String val)` Convenience method for putting preference in class Multivalent.
`void` | `redo()` Future protocol: Name and all overloads reserved for future use.
`void` | `restore(ESISNode n, java.util.Map<java.lang.String,java.lang.Object> attr, Layer layer)` Takes the place of a constructor's initialization functions; that is, it is invoked exactly once immediately after object instantiation.
`void` | `restoreChildren(ESISNode n, Layer layer)` Recursively process ESIS children, restore children as behaviors.
`ESISNode` | `save()` Build up save data as ESIS tree, then write that out.
`boolean` | `semanticEventAfter(SemanticEvent se, java.lang.String msg)` Round robin distribution to all behaviors.
`boolean` | `semanticEventBefore(SemanticEvent se, java.lang.String msg)` Round robin distribution to all behaviors.
`void` | `setName(java.lang.String name)`
`java.lang.String` | `toString()` Dump name of behavior and identifying/distinguishing short excerpt of content.
`void` | `undo()` Future protocol: Name and all overloads reserved for future use.

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

### ATTR_BEHAVIOR

    public static final java.lang.String ATTR_BEHAVIOR

  Class name to instantiate for behavior. Saved/restored in hubs.

  See Also:
    Constant Field Values

### name_

    protected java.lang.String name_

  Logical name.

Constructor Detail

### Behavior

    public Behavior()

Method Detail

### getName

    public java.lang.String getName()

  Returns the String used to instantiate the Behavior via `getInstance(String, String, Map, Layer)`. This can be the same as getClass().getName(), such as `multivalent.std.lens.Note`, but usually should be a short name referring to the type of behavior, such as "Note", which can then be mapped into a specific Java class name via the table in a user's `Preferences.txt` file.

  Specified by:
    `getName` in class `VObject`

### setName

    public void setName(java.lang.String name)

### getLayer

    public Layer getLayer()

  Link to containing layer, which links to Document and so on to Root, Browser, Multivalent.

### getDocument

    public Document getDocument()

  Convenience method to fetch Document from Layer.

### getRoot

    public Root getRoot()

  Convenience method to fetch Root from Browser.

### getBrowser

    public Browser getBrowser()

  Convenience method to fetch Browser from Layer.

### getPreference

    public java.lang.String getPreference(java.lang.String name,
                                          java.lang.String defaultval)

  Convenience method for getting preference in class Multivalent.

### putPreference

    public void putPreference(java.lang.String name,
                              java.lang.String val)

  Convenience method for putting preference in class Multivalent.

### isEditable

    public boolean isEditable()

### getInstance

    public static Behavior getInstance(java.lang.String logicalname,
                                       java.lang.String behaviorclass,
                                       ESISNode children,
                                       java.util.Map<java.lang.String,java.lang.Object> attr,
                                       Layer layer)

  Centralized behavior instantiation factory: instantiate all behaviors through this method -- never use `new behavior(...)`.
  - remapping of names so can dynamically replace references in old hubs
  - centralized, correct instantiation and error handling
  `restore(ESISNode, Map, Layer)` is called as part of instantiation, serving the place of arguments to a constructor. Logical names are normalized to all lowercase.

### getInstance

    public static Behavior getInstance(java.lang.String logicalname,
                                       java.lang.String behaviorclass,
                                       java.util.Map<java.lang.String,java.lang.Object> attr,
                                       Layer layer)

  Used in hub instantiation.

### save

    public ESISNode save()

  Build up save data as ESIS tree, then write that out. Makes node with GI = behavior name, same attributes, and possibly some children. Attributes are cloned, so if you want to stuff attributes from state, do that before `super.save()`. Always have `ATTR_BEHAVIOR` from save (short) classname.

### restore

    public void restore(ESISNode n,
                        java.util.Map<java.lang.String,java.lang.Object> attr,
                        Layer layer)

  Takes the place of a constructor's initialization functions; that is, it is invoked exactly once immediately after object instantiation. When restored from hub, passed XML content subtree if any as first parameter and attributes from XML tag's attributes. This protocol cannot be short-circuited.

### restoreChildren

    public void restoreChildren(ESISNode n,
                                Layer layer)

  Recursively process ESIS children, restore children as behaviors. Not called by default from restore() because behaviors may selectively process children.

### buildBefore

    public void buildBefore(Document doc)

  A round robin protocol, here traversing all behaviors from highest to lowest priority, during which main contributors of document content (called media adaptors) hack their content into the tree, and annotators set Marks to robust anchor to locations to hack in buildAfter so as not to disturb positioning by other annotations. That is, behaviors build the document tree by constructing nodes, which themselves are usually specialized for concrete document types. This protocol cannot be short-circuited.

  See Also:
    `Mark`

### buildAfter

    public void buildAfter(Document doc)

  Traverses all behaviors from lowest to highest priority, during which tweaks hack their content into the tree,

### formatBefore

    public boolean formatBefore(Node node)

  A tree walk protocol, called before observed node has been formatted.

  Returns:
    `true` to short-circuit to formatAfter at that node, bypassing formatting of the subtree. Could be used on collapsed outline sections to save work formatting content that wouldn't be displayed anyhow.

### formatAfter

    public boolean formatAfter(Node node)

  A tree walk protocol, called after observed node has been formatted. For instance, Search uses this to keep its coordinates of matches current.

  Returns:
    `true` to short-circuit formatting of rest of protocol, which consists exclusively of higher-priority behaviors, which almost never want to do.

### paintBefore

    public boolean paintBefore(Context cx,
                               Node node)

  A tree walk protocol, called before observed node has been painted. Called in same coordinate space as node's painting. Can be used draw special background, but usual background setting is done by spans or style sheets.

  Returns:
    `true` to short-circuit to paintAfter at that node, bypassing painting of the subtree.

### paintAfter

    public boolean paintAfter(Context cx,
                              Node node)

  A tree walk protocol, called before observed node has been painted. Called in same coordinate space as node's painting. Use to draw annotations at node's location. For instance, Search uses this to decorate the scrollbar (a type of node) with location of matches.

### clipboardBefore

    public boolean clipboardBefore(java.lang.StringBuffer sb,
                                   Node node)

  A tree walk protocol, called before observed node has been given a chance to contribute to the growing selection content in the passed StringBuffer. As a special case, observers on the root are always called, even if the selection is for only a part of the document. This way, a behavior could add author and title attribution to all selections. Remember that in addition to appending text to a StringBuffer, text can be inserted anywhere.

  Returns:
    `true` to short-circuit to selectAfter at that node, bypassing selection of the subtree. For instance, if you're selecting bibliographic entries, you might want to generate BibTeX or IEEE formatting rather than straight text; likewise, on math, generate Lisp, TeX, or Mathematica.

### clipboardAfter

    public boolean clipboardAfter(java.lang.StringBuffer sb,
                                  Node node)

  A tree walk protocol, called after observed node has been given a chance to contribute to the growing selection content in the passed StringBuffer. As a special case, observers on the root are always called, even if the selection is for only a part of the document.

### semanticEventBefore

    public boolean semanticEventBefore(SemanticEvent se,
                                       java.lang.String msg)

  Round robin distribution to all behaviors. Message and clientData unpacked from SemanticEvent for convenience. Message is interned, so if you compare to a literal, you can use "==". Message can't be changed (it can be short-circuited out of), but client data can be mutated as it is passed along (so it's not passed as a parameter).

### semanticEventAfter

    public boolean semanticEventAfter(SemanticEvent se,
                                      java.lang.String msg)

  Round robin distribution to all behaviors. Message and clientData unpacked from SemanticEvent for convenience. Message is interned, so if you compare to a literal, you can use "==". Message can't be changed (it can be short-circuited out of), but client data can be mutated as it is passed along (so it's not passed as a parameter).

### eventBefore

    public boolean eventBefore(java.awt.AWTEvent e,
                               java.awt.Point rel,
                               Node n)

  See Also:
    `SemanticEvent`, `AWTEvent`, `Browser`, `LensMan`

### eventAfter

    public boolean eventAfter(java.awt.AWTEvent e,
                              java.awt.Point rel,
                              Node n)

  During `eventBefore(AWTEvent, Point, Node)`, the behaviors that take primary action to that event should do so, after having given other behaviors the opportunity to filter it during `eventBefore`.

### undo

    public final void undo()

  Future protocol: Name and all overloads reserved for future use.

### redo

    public final void redo()

  Future protocol: Name and all overloads reserved for future use.

### destroy

    public void destroy()

  Protocol. Cleans up state before being decommissioned: remove from Layer, observed nodes, .... Clients shouldn't hold a pointer/handle to object after destroy() as it is in an invalid state. This protocol cannot be short-circuited.

### getLogger

    public static java.util.logging.Logger getLogger()

### createUI

    public Node createUI(java.lang.String type,
                         java.lang.String title,
                         java.lang.Object script,
                         INode parent,
                         java.lang.String category,
                         boolean disabled)

  Convenience function for UI building. Returns created widget for further configuration. This will be replaced by a separate GUI-handling behavior, but not for a while. UI widgets can be made from a hub with SemanticUI.

  Parameters:
    `type` - is one of "button", "checkbox", "radiobox", "menubutton", "separator", "entry", "label".
    `title` - can be HTML fragment.
    `script` - can be a `String` or `SemanticEvent`
  See Also:
    `SemanticUI`

### 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 `VObject`

### toString

    public java.lang.String toString()

  Dump name of behavior and identifying/distinguishing short excerpt of content.

  Overrides:
    `toString` in class `java.lang.Object`

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