Defined in Tool.Def Mixes in with Object
The Tool mixin provides the most basic interface for minimal tools. It provides its heirs with two methods for determining tool type and one method for defining the tool operation. Even though you probably won't work directly with this mixin, you'll probably find this section handy, since it discusses the General and Special Theories of Magic Cap tools.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
Instantiate: never Subclass: sometimes Call its methods: sometimes
You probably won't use the Tool mixin directly. Instead, to create your own tools you'll subclass from a class like ChooseableTool or one of its subclasses, which all inherit from the Tool mixin. Two high-profile classes inherit from the Tool mixin: the ChooseableTool and Window classes. Chooseable tools are the objects you and your users will interact with as tools. They take advantage of all that the Tool mixin can offer. Some subclasses of the Window class (such as the MagicWindow class) behave as tools when touched in certain circumstances.
There are three basic kinds of tools: writing tools, touch tools, and everything else.
Writing tools are tools that write on the screen by creating new objects. Examples are the various draw tools (which create scribbles), the shape tools (which create and stretch shapes), and the text field tools (which position new text fields and make them available for typing).
There is only one touch tool: the touch tool, which is the indexical iTouchTool. (The lesson tool behaves almost exactly like the touch tool, but isn't quite just a touch tool.) When the touch tool is active and the user hits the screen, the touch tool sends a touch to the hit object. For a discussion of touch tools, see the section describing class TouchTool.
The third kind of tool was described above as "everything else": tools that don't create objects and don't just send touches. The move tool, the stretch tool, and the copy tool are examples of this kind of tool.
You will probably never create your own touch tools, but will often create new writing and "other" tools.
You might find these indexicals helpful while working with tools:
| iCurrentTool | the DirectID of the current tool |
| iToolGadget | the tool gadget |
| iTouchTool | the touch tool |
| iToolWindow | the tool window associated with the tool gadget |
Each of the standard tools also has an indexical associated with it. See the file Indexicals.h for a complete list.
The Tool mix-in has the following methods you might Override:
| Method | When to override |
|---|---|
| IsWritingTool | If your tool creates new objects, override to return true |
| IsWritingOrTouchTool | If your tool is a writing tool or a touch tool, override to return true |
| TouchTarget | Always override to define the tool action |
The Tool mixin doesn't define any fields.
The following classes are related to the Tool mixin: ChooseableTool, ToolButton, ToolGadget, and TouchTool.
operation TouchTarget(target: Viewable; touchInput: TouchInput), noMethod; call: rarely Override: always
The system calls this method when the user touches the screen while your tool is the current tool. You must override this method to implement the action of your tool.
operation IsWritingTool(): Boolean; call: rarely Override: sometimes
By default IsWritingTool returns false. If your tool is a writing toolif it creates new objects like scribbles, shapes, or fieldsyou should override IsWritingTool to return true.
operation IsWritingOrTouchTool(): Boolean; call: rarely Override: sometimes
By default IsWritingOrTouchTool returns the same value that IsWritingTool returns. You should override this method if your subclass should return anything other than what IsWritingTool does, which won't be often. You should only do so if your tool is a wrapper for the touch tool (like the lesson tool), or some other touch-only tool.