bionic (3) Selection.3U.gz

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)