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

Chapter 1 - Newton Works / Newton Works Interface Reference

Newton Works Base Application Slots and Methods /

RegNewtWorksTool

newtAppBase:RegNewtWorksTool(toolSym, toolFrame)

Registers a tool for the viewDef identified by the dataTypeSymbol slot in the toolFrame frame.

toolSym

A unique symbol under which to register the tool.

toolFrame

A frame describing the command to appear in the Tools picker. Each command is a frame similar to the frames passed to PopupMenu, as documented in the section "Specifying the List of Items for a Popup" (page 6-37) in Newton Programmer's Guide. The standard slots (such as item, icon, and all other slots supported by PopupMenu) define the appearance of the command in the viewDef's Tools button, but each viewDef defines the additional slots it expects to see in this frame.

Every toolFrame must also contain the slot dataTypeSymbol that contains a symbol identifying the dataDef for which it's registered. For example, tools for the word processor have the symbol 'paper.

return value

Returns non-nil if the tool was successfully registered, or nil if it was not.

DISCUSSION

For 'drawPaper (Draw) or 'paper (Word Processor) stationery, provide the following additional slots and methods in toolFrame:

CmdFunc(viewDefView, newtAppBase)

A method called when the command is chosen from the Tools button. viewDefView is the main viewDef. newtAppBase is the Newton Works application. The return value of this method is not used.

keyCommand

Optional, used by Word Processor stationery only. A frame with command key information, containing the same slots as the frames used to register command keys, as described in "The Command-Key Mapping Frame". To register a command key that activates an item on the Tools picker, the keyCommand frame must contain the method KeyFn(keyView). This method is called when the command key for this item is pressed. It is passed the key view, which will be the viewDefView or a child of it. This function should perform the action as if the command were chosen from the Tools picker. The return value of this function is not used.

Note

The keyCommand frame has a keyMessage slot that contains a symbol identifying a function. You should specify a symbol that contains your developer signature appended to it in order to uniquely identify it. This is because the Word Processor creates a slot of this name in its base view, and you don't want to conflict with any other tools that might specify a function with the same name.

If you are registering a tool for the Word Processor and including the keyCommand frame in the toolFrame, and thus are specifying a KeyFn method, you don't need to supply a CmdFunc method. This is because if a CmdFunc method does not exist, then Newton Works calls the KeyFn method in the keyCommand frame when a tool is chosen.

Normally you would want the KeyFn method in the keyCommand frame to do the same thing as the CmdFunc method in toolFrame anyway. The KeyFn method is called if the user presses the command-key combination for the tool and the CmdFunc method is ordinarily called if the tool is chosen from the Tools picker directly.

A tool can be registered for only one dataDef with each call to *RegNewtWorksTool; to register a tool for more than one datadef, call *RegNewtWorksTool again with the new dataTypeSymbol and a different toolSym.