multivalent

Class Behavior

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.

Protocols: restore, build (before / after, format (before / after, paint (before / Behavior, clipboard (Behavior / Behavior, semantic events (Behavior / Behavior, low-level events (Behavior / Behavior), destroy.

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

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.13 $ $Date: 2003/06/02 04:43:07 $

Field Summary
static StringATTR_BEHAVIOR
Class name to instantiate for behavior.
protected Stringname_
Logical name.
Method Summary
voidbuildAfter(Document doc)
Traverses all behaviors from lowest to highest priority, during which tweaks hack their content into the tree,
voidbuildBefore(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.
booleancheckRep()
booleanclipboardAfter(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.
booleanclipboardBefore(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.
NodecreateUI(String type, String title, Object script, INode parent, String category, boolean disabled)
Convenience function for UI building.
voiddestroy()
Protocol.
booleaneventAfter(AWTEvent e, Point rel, Node n)
During Behavior, the behaviors that take primary action to that event should do so, after having given other behaviors the opportunity to filter it during eventBefore.
booleaneventBefore(AWTEvent e, Point rel, Node n)
booleanformatAfter(Node node)
A tree walk protocol, called after observed node has been formatted.
booleanformatBefore(Node node)
A tree walk protocol, called before observed node has been formatted.
BrowsergetBrowser()
Convenience method to fetch Browser from Layer.
DocumentgetDocument()
Convenience method to fetch Document from Layer.
static BehaviorgetInstance(String logicalname, String behaviorclass, ESISNode children, Map<String,Object> attr, Layer layer)
Centralized behavior instantiation factory: instantiate all behaviors through this method -- never use new behavior(...)
static BehaviorgetInstance(String logicalname, String behaviorclass, Map<String,Object> attr, Layer layer)
Used in hub instantiation.
LayergetLayer()
Link to containing layer, which links to Document and so on to Root, Browser, Multivalent.
StringgetName()
Returns the String used to instantiate the Behavior via Behavior.
StringgetPreference(String name, String defaultval)
Convenience method for getting preference in class Multivalent.
RootgetRoot()
Convenience method to fetch Root from Browser.
booleanisEditable()
booleanpaintAfter(Context cx, Node node)
A tree walk protocol, called before observed node has been painted.
booleanpaintBefore(Context cx, Node node)
A tree walk protocol, called before observed node has been painted.
voidputPreference(String name, String val)
Convenience method for putting preference in class Multivalent.
voidredo()
Future protocol: Name and all overloads reserved for future use.
voidrestore(ESISNode n, Map<String,Object> attr, Layer layer)
Takes the place of a constructor's initialization functions; that is, it is invoked exactly once immediately after object instantiation.
voidrestoreChildren(ESISNode n, Layer layer)
Recursively process ESIS children, restore children as behaviors.
ESISNodesave()
Build up save data as ESIS tree, then write that out.
booleansemanticEventAfter(SemanticEvent se, String msg)
Round robin distribution to all behaviors.
booleansemanticEventBefore(SemanticEvent se, String msg)
Round robin distribution to all behaviors.
voidsetName(String name)
StringtoString()
Dump name of behavior and identifying/distinguishing short excerpt of content.
voidundo()
Future protocol: Name and all overloads reserved for future use.

Field Detail

ATTR_BEHAVIOR

public static final String ATTR_BEHAVIOR
Class name to instantiate for behavior. Saved/restored in hubs.

name_

protected String name_
Logical name.

Method Detail

buildAfter

public void buildAfter(Document doc)
Traverses all behaviors from lowest to highest priority, during which tweaks hack their content into the tree,

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

checkRep

public boolean checkRep()

clipboardAfter

public boolean clipboardAfter(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.

clipboardBefore

public boolean clipboardBefore(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.

createUI

public Node createUI(String type, String title, Object script, INode parent, 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 java.lang.String or SemanticEvent

See Also: SemanticUI

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.

eventAfter

public boolean eventAfter(AWTEvent e, Point rel, Node n)
During Behavior, the behaviors that take primary action to that event should do so, after having given other behaviors the opportunity to filter it during eventBefore.

eventBefore

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

See Also: SemanticEvent java.awt.AWTEvent Browser LensMan

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.

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.

getBrowser

public Browser getBrowser()
Convenience method to fetch Browser from Layer.

getDocument

public Document getDocument()
Convenience method to fetch Document from Layer.

getInstance

public static Behavior getInstance(String logicalname, String behaviorclass, ESISNode children, Map<String,Object> attr, Layer layer)
Centralized behavior instantiation factory: instantiate all behaviors through this method -- never use new behavior(...). Behavior 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(String logicalname, String behaviorclass, Map<String,Object> attr, Layer layer)
Used in hub instantiation.

getLayer

public Layer getLayer()
Link to containing layer, which links to Document and so on to Root, Browser, Multivalent.

getName

public String getName()
Returns the String used to instantiate the Behavior via Behavior. 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.

getPreference

public String getPreference(String name, String defaultval)
Convenience method for getting preference in class Multivalent.

getRoot

public Root getRoot()
Convenience method to fetch Root from Browser.

isEditable

public boolean isEditable()

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.

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.

putPreference

public void putPreference(String name, String val)
Convenience method for putting preference in class Multivalent.

redo

public final void redo()
Future protocol: Name and all overloads reserved for future use.

restore

public void restore(ESISNode n, Map<String,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.

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.

semanticEventAfter

public boolean semanticEventAfter(SemanticEvent se, 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).

semanticEventBefore

public boolean semanticEventBefore(SemanticEvent se, 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).

setName

public void setName(String name)

toString

public String toString()
Dump name of behavior and identifying/distinguishing short excerpt of content.

undo

public final void undo()
Future protocol: Name and all overloads reserved for future use.