Tool(3U)						    InterViews Reference Manual 						  Tool(3U)

NAME

       Tool - base class for tool objects

SYNOPSIS

       #include <Unidraw/Tools/tool.h>

DESCRIPTION

       Tool is an abstract base class for objects that support direct manipulation of components.  Tools employ animation and other visual effects
       for immediate feedback to reinforce the user's perception that he is dealing with real objects.	The user  grasps  and  wields  a  tool	to
       achieve	a  desired effect.  The effect may involve a change to one or more components' internal state, or it may change the way components
       are viewed, or there may be no effect at all (if for example the tool is used in an inapropriate context).

       Conceptually, tools do their work within viewers, in which graphical component views are displayed  and	manipulated.   Whenever  a  viewer
       receives  an input event (such as a mouse click or key press), it in turn asks the current tool (defined by the enclosing editor object) to
       produce a manipulator object. A tool implements its CreateManipulator operation to create and initialize an appropriate manipulator,  which
       encapsulates  the  tool's manipulation semantics by defining the three phases (grasp, wield, effect) of the manipulation.  Moreover, a tool
       can delegate manipulator creation to one or more of the GraphicView objects in the  viewer  to  allow  component-specific  interaction.	 A
       tool's  InterpretManipulator  operation	accesses  and analyzes information in the manipulator that characterizes the manipulation and then
       creates a command that carries out the desired effect.  If a tool delegated manipulator creation to a graphical view, then it must delegate
       its interpretation to the same view.

PUBLIC OPERATIONS

       virtual Manipulator* CreateManipulator(
	  Viewer*, Event&, Transformer*
       )

       virtual void InterpretManipulator(Manipulator*)
	      Operations  that	define	how  the tool reacts when it is used and its ultimate effect.  The tool can defer manipulator creation and
	      interpretation to a GraphicView.	This allows the same tool to behave differently depending on the component it manipulates.

	      CreateManipulator creates a manipulator that is appropriate for the tool.  It receives the viewer in  which  the	manipulation  will
	      take place, an event with which to initialize the manipulator if necessary, and the coordinate transformation that maps canvas coor-
	      dinates into the subject's coordinate space.  InterpretManipulator is called following manipulation and defines how to  construct  a
	      command that carries out the manipulation's desired effect.

       virtual void SetControlInfo(ControlInfo*)
       virtual ControlInfo* GetControlInfo()
	      Tools  use  a  ControlInfo object to store information from which to build a user interface for engaging the tool.  These operations
	      set and get the ControlInfo object.  SetControlInfo does not delete the ControlInfo being replaced.

       virtual Component* Copy()
	      Return a copy of the tool.  Subclasses should redefine this operation to return an instance of their type.

       virtual void Read(istream&)
       virtual void Write(ostream&)
	      Read and write the tool's contents to a stream to support catalog operations.  Read and write typically call first the corresponding
	      operations  defined  by  their parent class, and then they read or write their class-specific state.  Note that you must ensure that
	      the objects are read in the same order they are written.

       virtual ClassId GetClassId()
       virtual boolean IsA(ClassId)
	      GetClassId returns the unique class identifier for the Tool subclass, while IsA returns whether the instance is of a class  or  sub-
	      class  corresponding  to	the given identifier.  IsA typically checks the given identifier against the instance's own (as defined by
	      its GetClassId operation) and, failing that, calls its parent classes' IsA operation.  All subclasses must redefine  GetClassId  and
	      IsA to ensure that their identifiers are unique and that instances are written and read properly.

PROTECTED OPERATIONS

       Tool(ControlInfo* = nil)
	      The constructor is protected to prevent instatiation of the abstract base class.	The ControlInfo object is optional, but only tools
	      that have no visible manifestion in the interface should omit it.

       ControlInfo* CopyControlInfo()
	      CopyControlInfo is a convenience function that subclasses may use in their Copy operation.  It returns a copy  of  the  tool's  Con-
	      trolInfo object if it non-nil, simply checking for a nil argument before calling the corresponding Copy on the ControlInfo object.

SEE ALSO

       Catalog(3U),   Command(3U),   ControlInfo(3U),	Editor(3U),  Event(3I),  GraphicView(3U),  Manipulator(3U),  Transformer(3I),  Viewer(3U),
       classes(3U), istream(3C++), ostream(3C++)

Unidraw 							  24 January 1991							  Tool(3U)