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)