Multivalent API

multivalent
Class Behavior

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

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

Multivalent API