Selection(3U)

💖 Selection(3U) 💖

okay bestie, we're in the InterViews Reference Manual and today's main character is Selection — she maintains a list of selected graphical component views. yes, that kind of list. let's go 🎀

---

✨ NAME ✨

Selection — maintains a list of selected graphical component views 🦋

---

🌸 SYNOPSIS 🌸

#include <Unidraw/selection.h>

---

💅 DESCRIPTION 💅

so like, a Selection manages a set of distinguished graphical component views — usually the ones the user has expressed interest in by selecting them with a tool or a command. yk, the chosen ones. 👑

each selection object maintains a list of graphical component views and provides operations for iterating through and manipulating the list. and bestie, everyone leans on these — components, commands, tools, and editors often rely on one or more selection objects to supply the components on which they operate. it's giving popular. it's giving essential. 💖

---

🔥 PUBLIC OPERATIONS 🔥

Selection(Selection* = nil)

create a new selection object, optionally containing references to the same views as the given selection object. so if you pass a selection in, your new one is basically its twin. ✨

virtual ~Selection()

destroy a selection instance. important caveat bestie: deleting the selection does not in turn delete the view instances it maintains. so don't be out here thinking the views go down with the ship, because they do not. 💀

void Show(Viewer* = nil) / void Update(Viewer* = nil) / void Hide(Viewer* = nil) / void Init(Viewer* = nil)

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. let's break it down:

• 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. glow up activated. 🌟
• Update makes handles of newly-selected, unhighlighted views appear by calling DrawHandles on all its views. the late arrivals finally get their moment. 🙈
• Hide unhighlights the views by calling their EraseHandles operation. bye bestie, we don't see you anymore. 🌫️
• Init initializes each view's handles without drawing them (in case the handles' appearance may have changed) by calling InitHandles on each. prep work, no spotlight. 🎀

void Clear(Viewer* = nil)

remove all views from the Selection object, hiding their handles in the process. full reset, everything gone, handles tucked away. ✨

void Append(GraphicView*) / void Prepend(GraphicView*) / void InsertAfter(Iterator, GraphicView*) / void InsertBefore(Iterator, GraphicView*) / void Remove(GraphicView*) / void Remove(Iterator&)

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. the rundown:

• Append and Prepend add a GraphicView to the end and the beginning of the list, respectively. back of the line vs. front of the line, no cap. 🚶‍♀️
• InsertAfter and InsertBefore insert a GraphicView after and before the GraphicView pointed to by the iterator, respectively. cutting the line, but make it legal. 💅
• the Remove operations remove a view from the list (without deleting it — say it with me, 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. heads up on that side effect, it's lowkey sneaky. 👀

GraphicView* GetView(Iterator) / void SetView(GraphicView*, Iterator&)

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. so if she's not on the list, she's not getting in. 🙅‍♀️

void First(Iterator&) / void Last(Iterator&) / void Next(Iterator&) / void Prev(Iterator&) / boolean Done(Iterator)

void First(Iterator&)
void Last(Iterator&)
void Next(Iterator&)
void Prev(Iterator&)
boolean Done(Iterator)

operations for iterating over the selection list. the whole vibe:

• 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. forward and backward, we contain multitudes. 🦋
• Done returns whether or not the iterator points beyond the first or last view in the list. your lil "are we there yet" check. 🫶

boolean IsEmpty() / boolean Includes(GraphicView*) / int Number()

boolean IsEmpty()
boolean Includes(GraphicView*)
int Number()

operations that return information about the selection object's contents. the gossip:

• IsEmpty returns whether the selection list is empty. 🕳️
• Includes returns whether the list contains the given view. 🔍
• Number returns the number of views in the list. math era. 🔢

void Sort(GraphicView*)

sort the views in the selection list to conform to their order in the given GraphicView's list of children. here's the tea: 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. so when the parent's opinion matters, you call her. 👑

void Merge(Selection*) / void Exclusive(Selection*)

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 — that's the union of the two sets. everyone's invited. 🌈
• Exclusive adds those views not already in this object and removes those common to both — that's the union minus the intersection of the two sets. chaotic, but mathematically correct. 💀

neither of these operations change the contents of their argument. the other selection stays unbothered, as she should. 💅

void GetBox(Coord&, Coord&, Coord&, Coord&)

return the bounding box circumscribing the views in the selection list. wrap it up, box it in. 🎁

---

🧚 PROTECTED OPERATIONS 🧚

UList* Elem(Iterator) / GraphicView* View(UList*)

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. two little helpers doing the most. 🫶

---

🌟 SEE ALSO 🌟

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

---

and that's the whole page bestie, we ate and left no crumbs 💖 this was brought to you by Unidraw, dated 6 August 1990, filed under Selection(3U) — iconic then, iconic now, periodt. 🎀✨