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  coordinates  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 subclass 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 ControlInfo 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++)