NAME

       ConnectManip,  DragManip,  ManipGroup, TextManip, VertexManip - Manipulator subclasses for
       defining common direct-manipulation semantics

SYNOPSIS

       #include <Unidraw/manips.h>

DESCRIPTION

       Manipulator is an abstract base class for objects that encapsulate the mechanics of direct
       manipulation.    Subclasses  support  different  manipulation  semantics.   The  DragManip
       subclass  implements  a  downclick-drag-upclick  style  of  interaction,   with   optional
       constraints  on  motion  (for  example,  horizontal  or vertical only).  ConnectManip is a
       DragManip subclass that adds a gravitational bias towards connector views.  VertexManip is
       a  DragManip  that  supports  multiple  downclick-and-drag  interactions  terminated  by a
       distinguished  downclick.   TextManip  provides  a  text  editing   interface.    Finally,
       ManipGroup   composes   manipulator  instances  so  that  their  interaction  may  proceed
       concurrently.

DRAGMANIP PUBLIC OPERATIONS

       DragManip(
           Viewer*, Rubberband*, Transformer* = nil, Tool* = nil,
           DragConstraint = None
       )

       DragManip(
           Viewer*, Rubberband*, Transformer*, Tool*,
           DragConstraint, Coord, Coord
       )
              A DragManip uses a rubberband to animate the manipulation.  The  constructor  takes
              the  rubberband  as  a parameter along with the viewer in which it should appear, a
              transformer reflecting the transformation  that  component  views  undergo  in  the
              viewer,   the  tool  that  created  the  manipulator,  and  a  DragConstraint  that
              effectively restricts mouse motion in one or more  ways.   By  default,  motion  is
              constrained when the Shift key is held down.  The second constructor adds two Coord
              parameters.  The DragManip will use these values to override the event  coordinates
              when Grasp is first called.

       virtual void Grasp(Event&)
              DragManip  redefines  Grasp  operation  to  call  the rubberband's Track operation,
              supplying the coordinates in the event.  Grasp calls Constrain (described below) on
              the  event prior to passing the coordinate information.  The rubberband will not be
              drawn until Grasp is called.

       virtual boolean Manipulating(Event&)
              If  the  event  is  a  MotionEvent,  Manipulating  calls  Track  with  the  event's
              coordinates and returns true.  Manipulating simply returns false if the event is an
              UpEvent.  Like DragManip::Grasp, this operation calls Constrain on the event  prior
              to passing the coordinate information.

       virtual void Effect(Event&)
              Effect simply erases the rubberband by calling its Erase operation.

       virtual void SetViewer(Viewer*)
       virtual void SetRubberband(Rubberband*)
       virtual void SetTransformer(Transformer*)
       virtual void SetTool(Tool*)
       virtual void SetConstraint(DragConstraint)

       virtual Viewer* GetViewer()
       virtual Rubberband* GetRubberband()
       virtual Transformer* GetTransformer()
       virtual Tool* GetTool()
       virtual DragConstraint GetConstraint()
              Set and get the various parameters supplied to the DragManip in its constructor.

       const Event& GraspEvent()
              Return the event supplied to the last call to Grasp.

DRAGMANIP PROTECTED OPERATIONS

       void Init(
           Viewer*, Rubberband*, Transformer*, Tool*, DragConstraint
       )
              Assign the various constructor values common to both DragManip constructors.

       virtual void Constrain(Event&)
              Constrain  the  event  to  reflect  the  DragConstraint.  The event coordinates are
              constrained when the event indicates that the  shift  key  is  held  down  for  all
              DragConstraint   values   except   Gravity,   which   constrains   the  coordinates
              unconditionally with the viewer's Constrain operation.

CONNECTMANIP PUBLIC OPERATIONS

       ConnectManip(
           Viewer*, Rubberband*, Transformer* = nil, Tool* = nil
       )
              ConnectManip supports the  same  type  of  interaction  as  DragManip,  except  the
              rubberband  tracking  is  affected  by a graviational bias towards connector views.
              Whenever the user drags  near  a  connector  view,  the  tracking  coordinates  are
              suddenly  constrained  to  coincide  with  the  center  of the connector view.  The
              rubberband will not change its appearance thereafter until the  user  drags  beyond
              the gravity threshold, which corresponds to SLOP (see globals(3U)) units beyond the
              nearest point on the connector view.

       virtual boolean Manipulating(Event&)
              ConnectManip redefines Manipulating to support the gravitational effect.

       ConnectorView* GetTarget()
              Return the connector view that has captured the rubberband, if any.

VERTEXMANIP PUBLIC OPERATIONS

       VertexManip(
           Viewer*, GrowingVertices*, Transformer* = nil,
           Tool* = nil, DragConstraint = None
       )
              VertexManip is like DragManip  but  supports  multiple  drags  and  clicks  in  one
              manipulation.   The  VertexManip  constructor  restricts  the  rubberband  to be an
              instance of GrowingVertices.

       virtual boolean Manipulating(Event&)
              This operation is similar to DragManip's,  except  it  calls  AppendVertex  on  the
              GrowingVertices  rubberband on each down-click and returns false if and only if the
              middle button is pressed.

       GrowingVertices* GetGrowingVertices()
              Return the GrowingVertices instance.  Use  this  operation  as  an  alternative  to
              GetRubberband when that operation isn't specific enough.

TEXTMANIP PUBLIC OPERATIONS

       TextManip(Viewer*, Painter*, Coord tabwidth, Tool* = nil)
       TextManip(
           Viewer*, Painter*, Coord lineheight, Coord tabwidth,
           Tool* = nil
       )
              Create  a  TextManip, supplying (at minimum) a viewer, a painter with which to draw
              (usually reflecting graphics attributes defined by the  enclosing  editor  object),
              and  the  width  of  a tab character.  Tab characters in the text will position the
              following character at an integral multiple of tabwidth from the beginning  of  the
              line.   The distance between baselines in the text can be specified with the second
              constructor;  this  value  corresponds  to  the  font  height  by  default.   These
              constructors  create text manipulators containing no text initially; the lower left
              corner of the first line of text (including the descender) will  be  positioned  at
              the coordinates in the event passed to the Grasp operation.

       TextManip(
           Viewer*, const char* buf, int bufsize, Coord x, Coord y,
           Painter*, Coord tabwidth, Tool* = nil
       )

       TextManip(
           Viewer*, const char* buf, int bufsize, Coord x, Coord y,
           Painter*, Coord lineheight, Coord tabwidth, Tool* = nil
       )
              Create  text manipulators initialized with text by passing a buffer of text and its
              size.  A copy of the buffer is used internally.  The x and y parameters specify the
              position  of  the  lower  left  corner  of  the  first  line of text (including the
              descender).  These coordinates will override the coordinates specified by the event
              passed to Grasp.

       virtual void Grasp(Event&)
              Positions  and draws the text.  If the position-specifing constructors were used to
              create the instance, then the manipulator will use the event coordinates to set the
              insertion point's position in the text.

       virtual boolean Manipulating(Event&)
              Handle keystrokes and/or mouse motion events to support basic text editing.  Motion
              events are interpreted to support text selection; selected  text  is  displayed  in
              reverse  colors.   The  Manipulating  operation  returns  false  if  a downclick is
              detected outside the text or if HandleKey (described below) returns false.

       virtual void Effect(Event&)
              Effect damages the viewer area that TextManip corrupted during editing.

       virtual Painter* GetPainter()
       virtual Coord GetLineHeight()
       virtual Coord GetTabWidth()
       virtual const char* GetText(int&)
       virtual void GetPosition(Coord&, Coord&)
              Return various parameters specified in the constructor.  GetText returns a  pointer
              to  the  internal  buffer  containing the text; the reference parameter returns the
              buffer's size.

       const Event& GraspEvent()
              Return the event supplied to the last call to Grasp.

TEXTMANIP PROTECTED OPERATIONS

       virtual boolean HandleKey(Event&)
              This operation defines TextManip's default key bindings as described below.  Unless
              otherwise noted below, this function returns true.

              (^P) backward line

              (^N) forward line

              (^B) backward character

              (^F) forward character

              (ESC) terminate text entry, causing HandleKey to return false

              (^A) beginning of line

              (^E) end of line

              (^D) delete character

              (DEL) (^H) delete backward character

       int Dot()
       int Mark()
              The  current  selection  is  bounded  by  two  indices  into  the  text buffer.  By
              convention these indices are called dot and mark.  Dot is  the  position  at  which
              text  will  be  inserted  and  deleted.  Mark locates the end of the selection that
              moves as the selection is modified.  When the  selection  is  empty  (an  insertion
              point), dot and mark are equal.

       void InsertText(const char* string, int count)
       void InsertCharacter(char)
       void DeleteText(int count)
       void DeleteCharacter(int)
       void DeleteLine()
       void DeleteSelection()
              Edit the text buffer at the current selection.  InsertText inserts count characters
              from string after dot.  The selection becomes  an  insertion  point  following  the
              newly  inserted  text.   InsertCharacter  replaces  the  selected characters with a
              single character.  DeleteText  deletes  count  characters  at  dot.   If  count  is
              positive,  the  characters  following  dot  are  deleted;  if count is negative the
              characters before dot are deleted.  The selection becomes an insertion point in the
              place  of the deleted text.  DeleteSelection deletes the text between dot and mark,
              changing the selection to an insertion  point.   DeleteCharacter  is  identical  to
              DeleteText  if  the  dot  and  mark  are not the same; otherwise it is identical to
              DeleteSelection.  DeleteCharacter provides a convenient way to express the behavior
              of  the  backspace  and delete operations.  Finally, DeleteLine deletes the line of
              text containing mark.  The selection becomes an insertion point at mark.

       void BackwardCharacter(int count)
       void ForwardCharacter(int count)
       void BackwardLine(int count)
       void ForwardLine(int count)
       void BackwardWord(int count)
       void ForwardWord(int count)
              Move the current selection forward or backward  by  the  specified  number  of  the
              specified  units.   The  default  movement is one unit.  The selection is not moved
              before the beginning of after the end of the text.

       void BeginningOfLine()
       void EndOfLine()
       void BeginningOfWord()
       void EndOfWord()
       void BeginningOfSelection()
       void EndOfSelection()
       void BeginningOfText()
       void EndOfText()
              Move the current selection forwards or backwards to the specified  feature  of  the
              text.

       void Select(int dot)
       void Select(int dot, int mark)
       void SelectMore(int mark)
       void SelectAll()
              Modify  the  current  selection in terms of text indices.  With a single parameter,
              Select moves both dot and mark to the specified index.  With  two  parameters,  dot
              and  mark  can  be  controlled  independently.  SelectMore leaves dot unchanged and
              moves mark.  SelectAll sets dot to the end of the text and mark to the beginning.

       int Locate(Coord x, Coord y)
       boolean Contains(Coord, Coord)
              Locate returns the text index most closely matching the  point  (x,  y).   Contains
              returns whether the text contains the point (x, y).

MANIPGROUP PUBLIC OPERATIONS

       ManipGroup(Viewer* = nil, Tool* = nil)
              Create a ManipGroup, optionally supplying a viewer and a tool.

       virtual void Grasp(Event&)
              The Grasp operation simply calls Grasp on each child in insertion order.

       virtual boolean Manipulating(Event&)
              Manipulating  calls  the  corresponding  operation  on  each  child, skipping those
              children that have returned false in previous calls (up to the last  Grasp).   This
              function returns false when all children have done so.

       virtual void Effect(Event&)
              ManipGroup's Effect operation calls Effect on each child.

       virtual void SetViewer(Viewer*)
       virtual void SetTool(Tool*)
       virtual Viewer* GetViewer()
       virtual Tool* GetTool()
              Set  and  get  the  ManipGroup's  viewer  and  tool.   The  set  operations set the
              ManipGroup's values for these parameters and call the corresponding  operations  on
              their children.  The get operations simply return the ManipGroup's values.

       virtual void First(Iterator&)
       virtual void Last(Iterator&)
       virtual void Next(Iterator&)
       virtual void Prev(Iterator&)
       virtual boolean Done(Iterator)
              Operations  for  iterating  over the ManipGroup's children, if any.  First and Last
              initialize an iterator to point to the beginning and end of the list  of  children,
              respectively.   Next increments the iterator to point to the following child, while
              Prev decrements the iterator to point to the preceding child.  Done returns whether
              or not the iterator points beyond the first or last child in the list.

       Manipulator* GetManip(Iterator)
       void SetManip(Manipulator*, Iterator&)
              GetManip  returns  the  child  manipulator  to  which an iterator points.  SetManip
              initializes an iterator to point to a particular child; it initializes the iterator
              to  point  to  a  nil  instance  if  the  given  Manipulator  is not a child of the
              ManipGroup.

       void Append(
           Manipulator*,
           Manipulator* = nil, Manipulator* = nil, Manipulator* = nil
       )

       void Prepend(
           Manipulator*,
           Manipulator* = nil, Manipulator* = nil, Manipulator* = nil
       )

       void InsertBefore(Iterator, Manipulator*)
       void InsertAfter(Iterator, Manipulator*)
       void Remove(Manipulator*)
       void Remove(Iterator&)
              Operations for modifying the ManipGroup's list of children.  Append and Prepend add
              up  to four child manipulators, in order, to the end and the beginning of the list,
              respectively.  InsertAfter and InsertBefore insert a child  after  and  before  the
              manipulator pointed to by the iterator, respectively.  The Remove operations remove
              a child from the list (without deleting it).  You can remove a child  by  referring
              to  it  explicitly  or  by specifying an iterator.  If an iterator is supplied, the
              Remove operation will advance it to point to the following child as a side effect.

MANIPGROUP PROTECTED OPERATIONS

       UList* Elem(Iterator)
       Manipulator* Manip(UList*)
              ManipGroup stores its children on a  UList,  which  is  accessible  via  the  _kids
              protected  member.  The Selection's iteration operations store the UList containing
              the current child in their iterator.  Elem is a convenience function for  returning
              the  UList  to  which an iterator points, and Manip extracts the child that a UList
              element contains.

SEE ALSO

       Connector(3U),  Event(3I),  Iterator(3U),   Manipulator(3U),   Painter(3I),   Rubband(3I),
       Tool(3U), Transformer(3I), UList(3U), Viewer(3U), globals(3U)