NAME

       Selection - maintains a list of selected graphical component views

SYNOPSIS

       #include <Unidraw/selection.h>

DESCRIPTION

       A Selection manages a set of distinguished graphical component views, usually those in which the user has
       expressed  interest  by selecting them with a tool or command.  Each selection object maintains a list of
       graphical component views and provides operations  for  iterating  through  and  manipulating  the  list.
       Components,  commands,  tools,  and  editors  often  rely  on one or more selection objects to supply the
       components on which they operate.

PUBLIC OPERATIONS

       Selection(Selection* = nil)
              Create a new selection object, optionally containing references to the same  views  as  the  given
              selection object.

       virtual ~Selection()
              Destroy  a  selection instance.  Deleting the selection does not in turn delete the view instances
              it maintains.

       void Show(Viewer* = nil)
       void Update(Viewer* = nil)
       void Hide(Viewer* = nil)
       void Init(Viewer* = nil)
              These operations affect how the selection is represented visually in the viewer.   Show  instructs
              the  views to initialize and draw their handles to highlight themselves, thus indicating that they
              are selected. To do so, it calls RedrawHandles on each  view.   Update  makes  handles  of  newly-
              selected,  unhighlighted  views appear by calling DrawHandles on all its views.  Hide unhighlights
              the views by calling their EraseHandles operation.  Finally, Init initializes each view's  handles
              without  drawing them (in case the handles' appearance may have changed) by calling InitHandles on
              each.

       void Clear(Viewer* = nil)
              Remove all views from the Selection object, hiding their handles in the process.

       void Append(GraphicView*)
       void Prepend(GraphicView*)
       void InsertAfter(Iterator, GraphicView*)
       void InsertBefore(Iterator, GraphicView*)
       void Remove(GraphicView*)
       void Remove(Iterator&)
              Operations for modifying the selection's list of views.  Append and Prepend add a  GraphicView  to
              the  end  and  the  beginning  of  the  list, respectively.  InsertAfter and InsertBefore insert a
              GraphicView after and before the GraphicView pointed to by the iterator, respectively.  The Remove
              operations remove a view from the list (without deleting it).  You can remove a view  instance  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 view as a side effect.

       GraphicView* GetView(Iterator)
       void SetView(GraphicView*, Iterator&)
              GetView returns the view to which an iterator points.  SetView initializes an iterator to point to
              a particular view in the list; it initializes the iterator to point to a nil instance if the given
              GraphicView is not in the selection list.

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

       boolean IsEmpty()
       boolean Includes(GraphicView*)
       int Number()
              Operations that return information about the selection object's contents.  IsEmpty returns whether
              the selection list is empty, Includes returns whether the list contains the given view, and Number
              returns the number of views in the list.

       void Sort(GraphicView*)
              Sort  the views in the selection list to conform to their order in the given GraphicView's list of
              children.  The selection list's order usually reflects the order in which the  user  selected  the
              objects,  not  their  order in their parent. Sort is useful in operations that modify or depend on
              the parent view's structure.

       void Merge(Selection*)
       void Exclusive(Selection*)
              Operations that change the selection object's contents based on another selection's.   Merge  adds
              the  views  in  the given selection to those already in the selection object (the union of the two
              sets), while Exclusive adds those views not already in this object and  removes  those  common  to
              both  (the  union minus the intersection of the two sets).  Neither of these operations change the
              contents of their argument.

       void GetBox(Coord&, Coord&, Coord&, Coord&)
              Return the bounding box circumscribing the views in the selection list.

PROTECTED OPERATIONS

       UList* Elem(Iterator)
       GraphicView* View(UList*)
              Selection stores its views on a UList, which is accessible via the _ulist protected  member.   The
              Selection's  iteration  operations  store the UList containing the current view in their iterator.
              Elem is a convenience function for returning the UList to  which  an  iterator  points,  and  View
              extracts the GraphicView that a UList element contains.

SEE ALSO

       GraphicView(3U), Iterator(3U), UList(3U), Viewer(3U)

Unidraw                                           6 August 1990                                    Selection(3U)