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

Chapter 1 - Newton Works / Using the Newton Works Interface

Creating the ViewDef

Certain slots are required for all viewDefs, such as symbol, type, protection, etc. These slots are not documented in this chapter unless their values are Newton Works-specific. For details on the standard viewDef slots and methods, refer to the "Stationery Reference" chapter of Newton Programmer's Reference. For information regarding viewDefs for printing (print formats) refer to the "Routing Interface Reference" chapter of Newton Programmer's Reference. Newton Works does not expect any slots other than the standard ones required for all print formats.

For the main viewDef, the methods and slots that Newton Works uses are explained in the following subsections according to their function.

Supporting Document Find

A Newton Works document Find operation is a search initiated by the user invoking the Find or Find Again commands in an open Newton Works document. Such a search operates only on the open document. Contrast this with a Newton Find operation, which applies to all or selected installed applications. Supporting the latter kind of Find operation is described in the section "Supporting Newton Find Operations".

To support a document Find operation, your viewDef is responsible for putting the Find and Find Again commands into the appropriate button in the application status bar. To do this, add the items {keyMessage: 'NewtworksFind} and {keyMessage: 'NewtworksFindAgain} to the appropriate picker array. Typically, these commands are found in the picker displayed by the Tools button. The methods NewtworksFind and NewtworksFindAgain are defined in Newton Works, so the behavior will be correct as long as these methods are called. For example, the behavior for the Find command is to display the Find slip, shown in Figure 1-4.

For more information about adding items with command-key shortcuts to pickers, see the section "About Displaying Command-Key Combinations in Menus". This section explains the usage of the keyMessage slot shown above.

Figure 1-4 Find slip

Next, your viewDef must implement the *FindChange method. This method is called when the user taps one of the action buttons ("Change All", "Change," "Change,Find," or "Find") in the Find slip. This method is passed two parameters: the first identifies the action requested by the user, and the second contains the string to find, and the string to replace it with, if appropriate (for a Change action). Your *FindChange method must do the requested find or replace operation and update the view appropriately.

The recommended user interface guidelines for doing find or replace operations are as follows:

• Start the find or replace operation from the current highlight range, or from the insertion point if there is no highlight range.
• Wrap the search around to the beginning of the document if the end is reached, making a page flipping sound when the end of the document is passed.
• Stop when the entire document has been searched.
• For a find operation, if an item is found, display the portion of the document containing the item and highlight the item.

If you don't implement the *FindChange method, do not add the Find and Find Again commands to a picker, since Find can't operate in your viewDef.

Supporting Data Storage

Newton Works automatically handles saving the current entry periodically (every 30 seconds or after 2 seconds of no system activity). Before saving the entry, Newton Works sends your viewDef the *SaveData message. The *SaveData method is passed the current entry. In this method, you can update any slots or data structures in the entry or do any other processing necessary.

You must return a value indicating if the entry should actually be saved. Return nil if it does not need to be saved or true to save the entry. Alternatively, you can return the symbol 'NoRealChange. This causes the entry to be saved, but the modification time stamp is not updated. You might want to do this if the change was insignificant, such as a change in the highlight location but not a change in the data itself.

Note

Even if you return nil from *SaveData, the entry still might be saved, if Newton Works detects that it has been modified, for example by one of the NewtApp framework protos.

Note that your *SaveData method does not actually do the saving operation. That is performed by Newton Works after *SaveData returns. Also, your *SaveData method does not need to check all the viewDef fields to see if they have changed, if your fields are based on the NewtApp slot-view protos. That is because these slot-view protos handle saving their own data when it is changed.

In addition to the automatic periodic saving that Newton Works performs, you can manually invoke a save operation on the current entry by calling the newtEntryView method StartFlush. Just send this message to self, like this:

 :StartFlush();

The StartFlush method starts the flush timer that calls the method EndFlush after 5 seconds. EndFlush sends your viewDef the *SaveData message, as described previously, and saves the entry, if appropriate. This is the standard way of saving stationery data outside the automatic saving mechanism described previously.

It is possible for your *SaveData method to be passed an entry that is invalid or read-only. In the *SaveData method, before you do begin any operations that write to the soup entry, you should perform this check:

 If EntryValid(entry) and not EntryStore(entry):IsReadOnly()

    then // do the operation

Supporting Scrolling

If the documents created by your stationery can be larger than what can be displayed on the screen at one time, then you'll want to provide a mechanism for the user to scroll the view. Newton Works can display scroll bars for you and can facilitate scrolling with some support from you in your viewDef.

First, you must supply the method GetScrollableRect in your viewDef. This method must return a bounds frame that describes the rectangle enclosing the scrollable part of the view (usually the currently visible part of the data, not including rulers or other tools). Newton Works automatically displays scroll bars at the right side and bottom of the view, as needed. The scroll bars are displayed in the stationery's topmost view, not inside the scrollable view.

If you return nil from GetScrollableRect, Newton Works does not display any scroll bars and scrolling functionality is not supplied by Newton Works. You can return nil if you want to provide your own scrolling functionality or if you don't need scrolling.

You also must supply a group of methods in the viewDef that return status information. GetScrollValues should return {x: (1000 - width), y: (1000 - height)}.

Next, you may want to supply methods that update your view in response to a scroll request. Two methods, ViewScrollDownScript and ViewScrollUpScript must update the view in response to a Down or Up arrow key, respectively. If you don't define these methods, then Newton Works performs the default action of scrolling down or up one screenful.

Finally, the Scroll method is passed a frame with x and y slots, describing how far to scroll in each direction.

Note that you must call the Newton Works method *UpdateAllScrollers from your Scroll as needed to recalculate the internal scroller data structures.

Providing Status Bar Buttons

To provide any custom buttons in the status bar, you can specify button view templates in one of two slots in your viewDef: statusLeftButtons and statusRightButtons. Specify an array of one or more button templates in the statusLeftButtons slot to include them at the left side of the status bar, but to the right of the New button, as shown in Figure 1-5. They are laid out from left to right, beginning with the first button in the array.

Specify an array of one or more button frames in the statusRightButtons slot to include them at the right side of the status bar, but to the left of the Routing and Filing buttons. They are laid out from right to left, beginning with the first button in the array.

Figure 1-5 Status bar buttons

If you are registering tools for your Newton Works stationery or documenting your tool format for other developers to use, you should include a Tools button on the status bar that displays a picker listing the installed tools. You can use the Newton Works method *GetNewtWorksTools to return an array of tools registered for your stationery.

There is a notification method that you can supply in your viewDef that is called if some other package installs or removes an auxiliary button in the Newton Works status bar. This method is UpdateStatusBar message simply allows you to update your own buttons.

This viewDef method is also called anytime the status bar is redrawn by the newtApp base method UpdateStatusBar. For example, this can happen when the screen is rotated, and you might want to show a different number of buttons depending on how much screen width is available.

The newtApp base UpdateStatusBar method. Whatever you set up in the two button arrays in your method is added to the existing status bar buttons when the status bar is redrawn.

Providing Help

The user accesses Help by tapping the Help command in the Information picker ("i" button on the status bar). When this command is chosen, you can either do a custom operation for your stationery, or open a help book, or both. When this command is chosen, Newton Works first conditionally sends your viewDef the *DoHelp message. You can do any kind of special processing in this method. If you also want to open a help book, you must return the symbol 'loadHelp from the *DoHelp method.

If *DoHelp is not implemented, or if it returns 'loadHelp, then Newton Works opens a help book. Two slots in the viewDef are used to identify the help book and location to which it is opened: helpManual and viewHelpTopic. The helpManual slot must contain a help book frame (the book frame produced by Newton Book Maker). The viewHelpTopic slot sets the topic to which that help book should open. This must be a string that matches one of the .subject lines in the help book. Refer to Newton Book Maker User's Guide and the sample code available on help books for more details about help book frames and topics.

Notification of Changes

There are global preferences that apply to all Newton Works applications. These are accessed by the user through the Works Prefs choice on the Info picker. Currently, the global preferences contain two items: a choice of using metric measurement units (rather than English) and a setting to always store new documents internally (rather than on a storage card).

If the global preferences for Newton Works are changed, Newton Works sends the current viewDef the *PrefsChanged message, passing the global preferences frame. This allows you to respond appropriately, if necessary, to the user's wishes.

If the view bounds of your view change, Newton Works sends the viewDef the ViewChangedScript message. This could happen if the horizontal scroller is no longer needed, or if the icon bar is moved from the side to the bottom on a MessagePad 2000 unit, and so forth. This viewDef method is a standard view method that is also called anytime a view is changed as a result of a SetValue call.

The ViewChangedScript method is passed two parameters, the slot that changed and the view that changed. For more information, see the Newton Programmer's Reference.