Component(3U)

💖 Component(3U) 💖

okay bestie, so this one is from the InterViews Reference Manual, section 3U — it's the Component page and it is literally the blueprint for every little object in your drawing. let's get into it 🫶

---

✨ NAME ✨

Component — the base class for objects that model domain-specific elements. she's the mom of the whole family tree, no cap 👑

---

✨ SYNOPSIS ✨

#include <Unidraw/Components/component.h>

---

✨ DESCRIPTION ✨

so Component is an abstract base class for objects that get created, edited, and composed together to form domain-specific drawings. basically: components are the objects of interest in an editing domain, and they encapsulate both their appearance and their semantics. iconic behavior 💅

here's the tea: components are partitioned into a subject and zero or more views 🦋

• the subject encapsulates the context-independent state and operations of a component
• each view supports a context-dependent presentation of the subject

and when the subject's state gets modified, it notifies all its views so they can change their own state or appearance to reflect that modification. it's giving "group chat, but for state changes" 📣

the Component class defines the protocol for component subjects, while ComponentView is the abstract base class that defines the protocol for component views. go read ComponentView(3U) for more on the view side of things, bestie.

---

✨ PUBLIC OPERATIONS ✨

• virtual void Interpret(Command*)
• virtual void Uninterpret(Command*)

Interpret does a component-specific operation based on what type of command you handed it. Uninterpret reverses the effects of a preceding Interpret. and here's the important part: the component is responsible for storing enough state — either in itself or in the command — to actually carry out the Uninterpret operation. so don't be out here reversing stuff you never saved, bestie 😭

• virtual void Attach(ComponentView*)
• virtual void Detach(ComponentView*)

Attach adds a component view to the component's list of views. ⚠️ heads up though: by default these operations do not check to make sure the view is actually compatible with the subject. Detach removes the argument from the component's list of views.

• virtual void Notify()

tells the component's views that its state has changed. this operation calls Update on every single view in the component's list of attached views. it's a whole roll call 🗣️

• virtual void Update()

other classes can use this operation to notify the component subject of a possible change in state that the component depends upon. by default this operation does nothing — it's just sitting there, vibing 🙈

• virtual Component* GetParent()
• virtual TransferFunct* GetTransferFunct()

return the component's parent and its transfer function, if any. both of these return nil by default.

• virtual Component* GetRoot()

returns the root component in this hierarchy. GetRoot calls GetParent recursively and returns the last non-nil parent, if any. climbing all the way to the top of the tree, main character energy 🌈

• virtual StateVar* GetState(const char*)

a component may maintain a string-to-state-variable mapping so it can give external access to any state variables it defines. GetState returns a state variable given an identifying string. defining a mapping like this lets other objects (usually commands) query the component for state variables it may define without extending the component protocol — which can potentially allow interchange of components from different applications. this operation returns nil by default.

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

these are the operations for iterating over the component subject's children, if it has any. First and Last initialize an iterator to point to the beginning and the end of the list of children, respectively. Next increments the iterator to point to the following child, while Prev decrements it to point to the preceding child. Done returns whether or not the iterator points beyond the first or last child in the list. so basically: walk the list, don't fall off the edges 🚶♀️✨

• virtual Component* Copy()

returns a copy of the component. subclasses should redefine this operation to return an instance of their type.

• virtual void Read(istream&)
• virtual void Write(ostream&)

read and write the component's contents to a stream to support catalog operations. Read and Write typically call the corresponding operations defined by their parent class first, and then read or write their class-specific state. and bestie, listen: you must ensure that the objects are read in the same order they are written. same order, always. periodt. 🔥

• virtual ClassId GetClassId()
• virtual boolean IsA(ClassId)

GetClassId returns the unique class identifier for the Component subclass, while IsA returns whether the instance is of a class or subclass corresponding to the given identifier. IsA typically checks the given identifier against the instance's own (as defined by its GetClassId operation) and, failing that, calls its parent classes' IsA operation. all subclasses must redefine GetClassId and IsA to make sure their identifiers are unique and that instances get written and read properly. non-negotiable, fr fr.

• virtual ClassId GetSubstId(const char*& delim)

a Component subclass can redefine GetSubstId to specify a component that can substitute for it. this lets applications that don't define a particular component subclass still read in a substitute that's compatible with the subclass. the substitute class should be one of the predefined components in the Unidraw library — that guarantees all applications can instantiate the substitute. 🫶

GetSubstId returns the class identifier for the substitute. when another Unidraw application's catalog reads this object, it can create an instance of the substitute (which it's guaranteed to define) instead of the original (which it may not define).

the original should read and write a superset of the substitute's data. the catalog will read to the end of the substitute's data and then advance the stream to the point following the sequence of characters specified by delim, saving the extra characters between the two points in the stream. when the substitute object is saved subsequently, the original class identifier will be written along with the substitute's data plus the extra characters saved previously. so information needn't be lost just because an unsophisticated application read and wrote it. slay for data preservation 💾💖

• ComponentView* Create(ClassId)

create a view instance that's appropriate for the component subject, given a view category. the relationship between subjects, views, and view categories is encoded in their class identifiers. see classes(3U) for more on class identifiers and view categories.

---

🎀 PROTECTED OPERATIONS 🎀

• void Component()

the Component class is abstract, so the constructor is protected. you can't just instantiate her directly, bestie — she's for the subclasses 💅

• ComponentView* View(UList*)

every component maintains a list of its views, implemented with a UList. this operation returns the component view associated with a given entry in the UList.

• virtual void SetParent(Component* child, Component* parent)

notify a child component that it has a new or different parent. by default this operation does nothing. composite components should call this function in their structure-modifying operations, and components that keep information about their parents should redefine it to update that information.

---

🌸 SEE ALSO 🌸

Catalog(3U), Command(3U), ComponentView(3U), Creator(3U), Iterator(3U), StatVar(3U), TransferFunct(3U), UList(3U), classes(3U), istream(3C++), ostream(3C++)

---

and that's the whole page, bestie!! go forth and subclass responsibly 👑

this cutie dropped from Unidraw on 20 August 1990 — yeah, she's an elder icon and she still ate. 💜✨