Interactor(3I)

💖 Interactor — the base class for interactive objects (that's Interactor(3I) bestie, from InterViews) 💖

✨ SYNOPSIS ✨

#include <InterViews/interactor.h>

---

🌸 DESCRIPTION 🌸

Okay so back in 2.6, Interactor was THE base class for every single interactive object that ever existed. Nowadays? It's still here, just chilling, provided purely for backward compatibility. She's retired but she still shows up. Queen behaviour. 👑

Every interactor has a shape member variable, and that bad boy defines the desired characteristics of screen space in terms of size, shrinkability, and stretchability. This info is what gets used to allocate display space for the interactor, and then the interactor's canvas member variable gets set to the actual space obtained. The lower left corner of the canvas is addressed by (0, 0), and the upper right by the member variables (xmax, ymax). Simple as. 🎯

The input member variable is the normal sensor for reading events. The output member variable is the standard painter for doing graphics operations. And listen — interactors generally should NOT set output. It either gets inherited (and shared) from the interactor's parent, or it gets set by user customization attributes. Don't fight the system, bestie. 🙅‍♀️

An interactor may optionally define the perspective member variable to represent the portion of total area that the interactor is displaying. Perspectives let interactors coordinate with other interactors — think scrollers — that wanna control the display area. Teamwork makes the dream work. 🫶

An interactor also may specify certain characteristics of the interactor's canvas, like:

• whether it's read-only or read/write 📖
• whether its contents should be saved when not visible 💾

Interactors also may specify the visual format and interpretation of the input pointing device (e.g., mouse cursor) when it's inside the interactor's canvas. Cursor glow-up, fr fr. 🖱️✨

To be mapped to some portion of the display, an interactor must have been inserted into a scene, called its parent. The interactor gets mapped when its parent is mapped. The root scene for the display can be accessed through a World(3I) object. It's giving family tree but make it pixels. 🌳

---

🎀 CONSTRUCTORS 🎀

• Interactor() — Construct an interactor. The input sensor and output painters are initialized to nil. Fresh out the box, no thoughts, head empty. 🐣
• Interactor(const char* name) — Construct an interactor associated with the string name. That string is used to customize the behavior of the interactor according to user preferences. Behaviour can also be customized on a per-class basis using the subclass name. And ngl, even though it's not explicitly documented: an instance of any object inheriting from interactor may be constructed with an additional argument (appearing first) containing the string name. For example, both of these are valid, no cap:

HGlue(natural, stretch)
HGlue("somename", natural, stretch)

• ~Interactor() — The base destructor automatically deletes the base fields, including shape, canvas, input, and output. She cleans up after herself. Self-care era. 🧹💅

---

💜 CONFIGURATION 💜

• void Align(Alignment, int w, int h, Coord& l, Coord& b) — Return the coordinates at which an object with the given width and height will have the given alignment within the interactor's canvas. Math but make it cute. 📐
• void SetClassName(const char*)
• const char* GetClassName()
• void SetInstance(const char*)
• const char* GetInstance() — Set/get the class or instance name for an interactor. These names are used to determine user style preferences. Heads up though: SetClassName and SetInstance can only be performed by subclasses. Sorry bestie, not everyone gets backstage access. 🚫🎟️
• void Config(Scene* s) — Configure this interactor and its descendants according to user preferences. The scene s is assumed to be the interactor's parent and is used to inherit attribute values. You don't have to call this yourself — it happens automatically when the ancestors of an interactor become known (e.g., when the interactor or an ancestor is inserted into a world). It's self-configuring, main character energy. ✨

---

Configuration involves a traversal of the interactor hierarchy. For each interactor in the hierarchy, the output painter is either inherited from its parent or copied from its parent if there are user preferences specific to the interactor for painter attributes such as colors, font, and brush.

Okay let's do the example because it's lowkey iconic. Suppose the user preference is:

A*B*font:9x15

and the interactor hierarchy is A.B.C.D (each . representing a nesting level in the hierarchy). Then:

• Interactors A and B will share the same output painter
• C will copy B's output and change the font to 9x15
• D will share C's output

See? The font change propagates down like gossip. 🗣️💬

---

After assigning the output painter, configuration is performed recursively on any children interactors. The final step at each node in the traversal is to call the virtual Reconfig operation.

• virtual void Reconfig() — Perform any configuration specific to a particular interactor. This operation should minimally compute the interactor's shape based on the shape of its children and/or the characteristics of its output painter (e.g., font). It can also retrieve user preferences specific to this interactor's class or instance name using GetAttribute. Do the bare minimum but do it well, honestly relatable. 😌
• const char* GetAttribute(const char*) — Retrieve the value of a user preference with the given name. GetAttribute searches for the most specific match to the current context. It always finds the most relevant one, she's thorough like that. 🔍
• virtual void Reshape(Shape&)
• Shape* GetShape() — Set/get the shape of an interactor. Reshape is a suggestion that an interactor's shape should change to the given one. The default operation sets the interactor's shape to the new shape and calls Scene::Change on the interactor's parent. > ⚠️ Suggested shape information may be lost when an interactor is configured — so it's best to avoid use of Reshape. The same affect can usually be achieved by putting the interactor in a box along with a particular shape of glue. Don't waste your time on something that might ghost you. 💀
• void SetCursor(Cursor*)
• Cursor* GetCursor() — Set/get the cursor that will be displayed when the pointing device is inside the interactor's canvas. If the interactor does not explicitly set its cursor, it will use its parent's cursor. In that case, GetCursor returns nil. Inherited lewks, we love to see it. 💅

---

🦋 INTERACTOR HIERARCHY 🦋

• Scene* Parent() — Return the interactor's parent, or nil if the interactor has not been inserted into a scene. Orphan era. 😭
• World* GetWorld() — Return a pointer to the world the interactor has been inserted into, or nil if the interactor's root ancestor is not mapped.
• void GetRelative(Coord& x, Coord& y, Interactor* = nil) — Map coordinates that are relative to this interactor's canvas to be relative to another interactor's canvas. If the other interactor is nil, then the coordinates are made relative to the world. Coordinate teleportation, but make it geometric. 🌀
• virtual void GetComponents(Interactor**, int, Interactor**&, int&) — Construct an array of pointers to the interactors contained within this interactor. The first and second parameters specify an array of interactors that is already allocated. This array is used if it is large enough — otherwise a new array is allocated from free store. The third and fourth parameters return which array was used and the actual number of components. This operation is only defined by scenes; the default operation sets the number of elements to zero. Recycling when possible, allocating when necessary — environmentally conscious queen. ♻️👑

---

🔥 OUTPUT 🔥

• Canvas* GetCanvas() const — Return the interactor's canvas, which may be nil if the interactor is not mapped to a display.
• ManagedWindow* GetTopLevelWindow() const — Return the top-level window associated with the interactor, if it is mapped and top-level. Only for the ones at the top of the food chain. 👑
• virtual void Draw() — Draw is used to display the contents of an interactor, including the contents of any interior interactors. The default Draw operation calls Redraw(0, 0, xmax, ymax). Interactors usually don't need to redefine Draw unless they contain interior interactors (i.e., scene subclasses) — most simple interactors redefine only Redraw. Don't overthink it bestie, just redraw. 🎨
• virtual void Highlight(boolean) — Turn highlighting on or off, depending on whether the parameter is true or false. The default operation is a nop. Literally does nothing. Relatable. 🫠
• void SetCanvasType(CanvasType)
• CanvasType GetCanvasType() — Set/get the type of canvas desired for an interactor. > ⚠️ This operation must be performed before an interactor is mapped. Timing is everything, periodt. ⏰

The possible canvas types are:

• CanvasShapeOnly — meaning the interactor performs no input or output (e.g., glue)
• CanvasInputOnly — meaning the interactor performs no output
• CanvasInputOutput — which is the default
• CanvasSaveUnder — which suggests that the interactor will be mapped for a short time (e.g., a popup menu) and that the information under the canvas should be saved
• CanvasSaveContents — which suggests that Redraw calls are expensive and should be avoided by caching the display
• CanvasSaveBoth — which requests both CanvasSaveUnder and CanvasSaveContents

Pick your fighter. 🌈

• void Sync()
• void Flush() — Sync waits until any pending operations have completed. Flush makes sure the local buffer of pending operations (if any) is sent to the display. An input operation will do a Sync automatically if it would block — thus, applications generally need not call Sync or Flush explicitly. She handles it for you, you're welcome. 🫶

---

💖 INPUT 💖

okay so input is literally the whole vibe of an interactor — it's how it knows what's happening. let's get into it.

• void Listen(Sensor*) — when an interactor gets mapped onto a display, its input interest is determined by its input sensor. You can swap in a different sensor with the Listen operation. Wanna switch back to input? Call Listen(input). periodt.
• void Read(Event&) boolean Read(long sec, long usec, Event&) — every application has a single input queue of events. Any interactor can use Read to take the next event from the queue. Redraw and Resize operations may be called as a side effect of a Read (or any input operation). The target field of the event specifies the interactor for which the event is intended, which is not necessarily the same as the interactor that performed the Read. The target is normally the interactor whose canvas is under the pointing device. The second form of Read behaves differently if there are no events to read: it times out after the given number of seconds and microseconds have elapsed and returns false to the calling program. 🕰️
• void UnRead(Event&) — UnRead puts an event back on the input queue as if it had never been read. it's giving undo but for events 💅
• virtual void Handle(Event&) — when an interactor wishes to pass an event to another interactor, it calls the other interactor's Handle operation. So input flow control can be either procedural with Read or event-driven with Handle. choose your fighter ✨
• void Run() — Run implements a simple event dispatching loop. It calls Read to get the next event and passes the event to the target interactor via Handle. The loop terminates if the Handle operation sets the event's target to nil. bye bestie 👋
• void QuitRunning(Event&) — QuitRunning sets the event's target to nil. A Handle operation can call it to make Run exit its event dispatching loop. it's the emergency exit fr fr
• boolean Check() — Check determines whether an event of interest has occurred. 🔍
• void Poll(Event&) — Poll sets an event to reflect the current input state. Input polling can be wasteful of cycles and should be avoided if possible. > not me wasting cycles... 💀
• int CheckQueue() — CheckQueue returns the number of input packets that have been queued within the application. The event queue manager always reads as much information as possible from input; thus, a single Read might store many events in a local buffer. Subsequent reads can simply access the buffer. This buffer can include out-of-band packets, such as those requiring a Redraw. The number returned by CheckQueue does not correspond, therefore, to the actual number of input events. so like, don't @ me if the math isn't mathing 🧮

---

🦋 VIEWS 🦋

• virtual void Adjust(Perspective&) — Adjust suggests to an interactor that its perspective should change to the given perspective; the interactor may choose to accept any part of the new perspective and must ensure that the parameter matches its (new) perspective before returning. Adjust can be used by another interactor to scroll, pan, or zoom an interactor. it's giving gentle suggestion, not a demand 💁‍♀️
• Perspective* GetPerspective() — GetPerspective returns the perspective associated with an interactor or nil if the interactor has not assigned one. no perspective? nil. iconic.
• virtual void Update() — change the display to reflect some change in state that the interactor depends on. This operation is used in a number of contexts. One example is in managing perspectives. If an interactor changes its perspective (e.g., the total of size of what it is displaying changes), it must notify its perspective, which in turn calls Update on the interactors that access the perspective (such as a scroller). the way that perspective gossip travels... 🫶

---

🔒 PROTECTED OPERATIONS 🔒

• virtual void Redraw(Coord l, Coord b, Coord r, Coord t) — the Redraw operation is called when some portion of the Interactor needs to be redrawn, presumably because it was previously obscured. The Redraw operation should NOT redraw interior interactors; the Interviews library or the Draw operation will call their Redraw operations automatically. The default Redraw operation does nothing. > do NOT redraw interior interactors, bestie. let the library handle it. 🚫
• virtual void RedrawList(int n, Coord l[], Coord b[], Coord r[], Coord t[]) — RedrawList notifies an interactor that several areas of its canvas need to be redrawn, presumably because it was raised to the top of other canvases. The default RedrawList operation redraws each area separately with Redraw. it's like a to-do list but for pixels ✨
• virtual void Resize() — Resize notifies an interactor that its canvas has been created or modified. Only scenes are typically concerned with Resize, as they must place their component interactors within the new or resized canvas. The default Resize operation does nothing. scenes stay busy 🎬

---

👀 SEE ALSO 👀

• InterViews Reference Manual
• Perspective(3I)
• Scene(3I)
• Sensor(3I)
• Shape(3I)
• World(3I)

---

k bye bestie 💖 this was from the InterViews Reference Manual, Interactor(3I) — no date on this one, but you know the vibe. periodt. 🌈