Tool(3U)

💖 Tool(3U) 💖

okay bestie, welcome to the InterViews Reference Manual page for Tool(3U) — yes it's a manpage, yes it's from 1991, and yes it still ate. let's get into it 🫶

✨ NAME ✨

Tool — the base class for tool objects, periodt

🌸 SYNOPSIS 🌸

#include <Unidraw/Tools/tool.h>

🦋 DESCRIPTION 🦋

okay so. Tool is an abstract base class for objects that support direct manipulation of components. and the way it does this?? tools use animation and other visual effects for immediate feedback, so the user genuinely feels like she's dealing with real objects. you grasp a tool, you wield it, you get the effect you wanted. main character energy fr 💅

now, that effect can be a few different things:

• it may involve a change to one or more components' internal state,
• or it may change the way components are viewed,
• or there may be no effect at all — like if the tool gets used in an inapropriate context. (and yes, that's the original spelling, we're keeping it, no cap.)

conceptually, tools do their work within viewers, where graphical component views get displayed and manipulated. so whenever a viewer receives an input event (mouse click, key press, whatever), it turns around and asks the current tool — which is defined by the enclosing editor object — to produce a manipulator object. iconic delegation honestly.

here's the whole pipeline, bestie:

1. A tool implements its CreateManipulator operation to create and initialize an appropriate manipulator, which encapsulates the tool's manipulation semantics by defining the three phases — grasp, wield, effect — of the manipulation.
2. Also, a tool can delegate manipulator creation to one or more of the GraphicView objects in the viewer, to allow component-specific interaction. 👑
3. A tool's InterpretManipulator operation accesses and analyzes information in the manipulator that characterizes the manipulation, and then creates a command that carries out the desired effect.

⚠️ important rule: if a tool delegated manipulator creation to a graphical view, then it must delegate its interpretation to that same view. matching sets only, bestie, don't mix and match 😭

🔥 PUBLIC OPERATIONS 🔥

virtual Manipulator* CreateManipulator(
   Viewer*, Event&, Transformer*
)

virtual void InterpretManipulator(Manipulator*)

• These are the operations that define how the tool reacts when it's used, and what its ultimate effect is. The tool can defer manipulator creation and interpretation to a GraphicView — which is the whole reason the same tool can behave differently depending on the component it's manipulating. flexible queen ✨
• CreateManipulator creates a manipulator that's appropriate for the tool. It receives:
  • the viewer in which the manipulation will take place,
  • an event with which to initialize the manipulator if necessary,
  • and the coordinate transformation that maps canvas coordinates into the subject's coordinate space.
• InterpretManipulator is called following manipulation and defines how to construct a command that carries out the manipulation's desired effect.

virtual void SetControlInfo(ControlInfo*)
virtual ControlInfo* GetControlInfo()

• Tools use a ControlInfo object to store information from which to build a user interface for engaging the tool. These two operations set and get that ControlInfo object. 🎀
• SetControlInfo does not delete the ControlInfo being replaced. like, it just... leaves it there. so if you needed that, you have it. 💀

virtual Component* Copy()

• Returns a copy of the tool.
• Subclasses should redefine this operation to return an instance of their type. (yes that's "should" — we're not making up extra rules here.)

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

• Read and write the tool's contents to a stream to support catalog operations.
• Read and Write typically call first the corresponding operations defined by their parent class, and then they read or write their class-specific state.
• > ⚠️ note: you must ensure that the objects are read in the same order they are written. order matters, bestie, this is not a vibe-check situation, it's a correctness situation 😭

virtual ClassId GetClassId()
virtual boolean IsA(ClassId)

• GetClassId returns the unique class identifier for the Tool subclass.
• IsA returns whether the instance is of a class or subclass corresponding to the given identifier. It 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 ensure that their identifiers are unique and that instances are written and read properly. non-negotiable, fr fr.

🎀 PROTECTED OPERATIONS 🎀

Tool(ControlInfo* = nil)

• The constructor is protected to prevent instatiation of the abstract base class. (again, original spelling, we're keeping the whole thing, no edits 💅)
• The ControlInfo object is optional — but only tools that have no visible manifestion in the interface should omit it.

ControlInfo* CopyControlInfo()

• CopyControlInfo is a convenience function that subclasses may use in their Copy operation.
• It returns a copy of the tool's ControlInfo object if it's non-nil — simply checking for a nil argument before calling the corresponding Copy on the ControlInfo object. so helpful, so thoughtful 🌸

🌈 SEE ALSO 🌈

• Catalog(3U)
• Command(3U)
• ControlInfo(3U)
• Editor(3U)
• Event(3I)
• GraphicView(3U)
• Manipulator(3U)
• Transformer(3I)
• Viewer(3U)
• classes(3U)
• istream(3C++)
• ostream(3C++)

and that's the whole page, bestie!! this one's from Unidraw, dated 24 January 1991 — yes, before some of us were born, and yet it's still serving. stay iconic, keep your IsA unique, and read your streams in order 💜✨🦋