Newton Developer Technical Information: Newton Programmer's Guide: 2.1 OS Addendum /

Chapter 1 - Newton Works / Using the Newton Works Interface

Working With the Tools Picker

You can add tools to the Tools picker of any Newton Works stationery that supports additional tools. For example, you might add a thesaurus to the word processor. The user accesses such tools from the Tools button in the status bar. When the user taps the Tools button, a picker of available tools is displayed, as shown in Figure 1-6. The application viewDef is responsible for displaying the tools installed for that viewDef, and for calling the tool correctly when it's chosen from the Tools picker.

Figure 1-6 Tools picker

Note that the Tools button already exists in the built-in Newton Works stationery, but if you are creating your own stationery, you must add the Tools button to the status bar yourself. For details on how to do this, see the section "Providing Status Bar Buttons". If you are adding a tool to a different type of stationery that supports tools, you may need to add the Tools button if there are no other tools registered. Don't assume that the button already exists.

You register a tool for an application by calling the *RegNewtWorksTool method. To remove a tool you've added, call *UnregNewtWorksTool. You can call *GetNewtWorksTools to return an array of registered tools for a particular application, or you can call *GetNewtWorksTool to return a particular tool.

Within the viewDef or status bar context, you can use the syntax newtAppBase:MethodName to call these methods. For example: newtAppBase:*GetNewtWorksTools(sym). Outside the viewDef, you'll need to call these methods like this:

 GetRoot().newtWorks:RegNewtWorksTool(toolSym, toolFrame);

Whenever a tool is installed or removed for the current document, the system sends the message *ToolsChanged to the viewDef. If you choose to implement it, this method allows you to update the tools picker, if necessary, or do other work. Note that an even better way of making sure the tools picker is current is to generate it dynamically when the user taps the Tools button.