Control(3I)

💖 Control(3I) 💖

okay bestie, gather round — this is the InterViews Reference Manual page for Control and ControlState, and yes we are about to make select-and-execute-an-action sound as cute as it actually is. no cap.

✨ NAME ✨

Control, ControlState — pick an action and then actually do it. the choosing and the doing. iconic behavior honestly. 👑

🌸 SYNOPSIS 🌸

#include <InterViews/control.h>

that's it. that's the whole vibe. one include and you're in. ✨

🦋 DESCRIPTION 🦋

okay so. a control is a monoscene that lets an action be selected and executed. that's literally its whole personality. 💅

the component of a control is what decides the appearance associated with that control — so like, the component is the ~lewk~, the control is the ~behavior~. main character energy fr fr.

a control state is a subject that coordinates a whole group of related controls, like a little friend group chat for controls. 📱 the control state holds a pointer to the currently selected control — if any, because sometimes nobody's selected and that's valid too bestie.

controls are lowkey the goat for grabbing input and moving over potentially selectable items. examples of controls include:

• popup menus
• pull-down menus
• menu items

and here's the tea 🍓 — it is generally not necessary to call functions directly on a control. she handles herself. let her cook. 🙈

👑 PUBLIC OPERATIONS 👑

• Control(Interactor*) — construct a brand new control, and use the given interactor as its component. build her. ✨
• ~Control — destruct a control. and heads up bestie, because a control is a monoscene, deleting it implies deleting its component interactor too. 😭 so like, one deletion, two gone. no take-backs.
• ControlState* State() and void SetState(ControlState*) — get or set the control state that's associated with a control. getter, setter, the classic duo. 💫
• virtual void Handle(Event&) — controls start out inactive, like you at 7am. a DownEvent causes a control to become active. if an active control receives an EnterEvent, it will set the current selection to itself (she said "it's me, I'm the selection" 💅). if an active control receives a LeaveEvent, it will set the current selection to nil — and yeah, nil is the void, the nothing, the ghosting. 💀
• virtual void Enable(boolean) and boolean Enabled() — depending on the argument, Enable enables (true) or disables (false) the control. control subclasses can check whether the control is enabled with the Enabled operation and then take whatever action is appropriate. so basically: true = slay, false = sit down. 🪑
• virtual void Select() — highlight the control and call the protected virtual functions Open and Grab (see below, we'll get there bb 🫶).
• virtual void Unselect() — call the protected virtual function Close, and then unhighlight the control. order matters bestie, don't flip it. ⭐
• virtual void Do() — implement a selected action. when a control sees an UpEvent, it calls Do on the current selection. this is the moment everything was building toward. 🎬
• Control* ParentControl() and Control* RootControl() — okay so plot twist: the control hierarchy does not necessarily correspond to the interactor hierarchy. they're two different maps, iykyk. these operations return the control's parent control or the root of the control hierarchy, if any, as defined by control subclasses. 🌈

🔥 PROTECTED OPERATIONS 🔥

• virtual void Down() and virtual void Up() — Down and Up are called when the control receives a DownEvent and an UpEvent, respectively. by default, Down activates the control if it is enabled, and Up deactivates the control and calls Do on the current selection. default behavior ate, ngl. 🍽️
• virtual void Enter() and virtual void Leave() — Enter makes the control the current selection if it is enabled and active, while Leave nullifies the current selection if the control is enabled and active. two conditions, both required, no shortcuts. 💯
• virtual void Open() and virtual void Close() — the base class Open and Close do nothing, but subclasses may insert and remove an interactor, such as a pull-down menu. the base class is a chill girl who does nothing; subclasses are the overachievers. 💅
• virtual void Grab() — Grab reads input and only passes through an event if its target is an active control. gatekeeping, but make it functional. 🚪
• virtual void Skip() — Skip reads and discards input events until it reads an event targeted for a control that is currently grabbing input, as indicated by IsGrabbing (see below). throw it out, throw it out, oh wait this one's for us — keep it. 🗑️
• virtual void Busy() and virtual void Done() — the Up operation calls Busy just before it calls Do on the target, and it calls Done immediately afterwards. these operations do nothing by default; subclasses may reimplement them to start and stop some indication that the control is doing its job. like a little "working on it ✨" spinner, but make it yours.
• virtual boolean IsGrabbing(Interactor*) — returns true if the given interactor is grabbing control. simple. honest. we love her. 💖
• void Reparent(Control* target, Control* parent) — set target's parent to parent. controls that compose child controls should call this operation on their children. yes bestie, you have to tell your kids who their parent is, they can't just guess. 🫶

🌈 SEE ALSO 🌈

• Event(3I)
• Interactor(3I)
• Menu(3I)
• Scene(3I)

go read those next, they're all part of the same friend group. 💜

and that's the page!! this one came from InterViews, dated 15 September 1989, and it's the Control(3I) entry — so yeah, 1989 called and it's still giving. mwah, go forth and select your actions responsibly. 🎀🦋💖