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

Chapter 1 - Newton Works / Using the Newton Works Interface

Creating the DataDef

You must use the standard stationery proto, newtStationery, to create a dataDef for Newton Works. The superSymbol slot of the dataDef must be set to the symbol 'newtWorks. This associates the stationery with the Newton Works application.

Note that as in the NewtApp framework, the symbol of the dataDef is used as the class slot of soup entries created by that dataDef.

Certain slots are required for all dataDefs, such as symbol, name, description, superSymbol, icon, StringExtract, TextScript, FillNewEntry, etc. For details on these standard NewtApp slots and methods, refer to the "NewtApp Reference" chapter of Newton Programmer's Reference. The only dataDef slot unique to Newton Works is the prefs slot. See the next section for details on how it is used.

Supporting Application-Defined Preferences

The dataDef can specify an application-specific preferences command that appears in the Info button picker when the user is viewing an entry of the dataDef. If this command is chosen, a preferences slip is displayed. To implement this feature, define a slot called prefs in the dataDef. This slot contains a frame defining the command name and icon to show in the Info picker and the frame contains a view template defining the actual preferences slip. Figure 1-2 shows an example of the Info picker with one application-specific preferences command added for the word processor stationery type (paper).

Note that there are also global preferences that apply to all Newton Works applications. These are accessed through the Works Prefs choice on the Info picker. For more information about handling global preferences, see the section "Notification of Changes".

Figure 1-2 Info picker

When the user chooses the application-specific preferences command from the Info button, Newton Works sets the slots target (the soup entry being viewed), newtAppBase (the Newton Works base view), and viewDefView (the current viewDef) appropriately in the preferences view template. Then it calls BuildContext(prefsTemplate) to create and display the preferences view.

The preferences view must read the appropriate preferences slots in its ViewSetupFormScript method (or other initialization method), and write the slots in its ViewQuitScript method (or before it closes). The preferences reside in the application preferences frame, which you can get using the newtApplication method GetAppPreferences. The preferences for the dataDef must reside in a subframe for that dataDef within the preferences frame. For example,

 prefsFrame := newtAppBase:GetAppPreferences().(kDataSymbol);

should return the preferences for the dataDef identified by kDataSymbol.

To save the preferences, call EntryChangeXmit(prefsFrame, kDataSymbol).

Note that the preferences view must be closed by calling newtAppBase:RememberedClose(base), otherwise, Newton Works keeps a reference to the view and it uses up RAM. For example, here's how you would write the ButtonClickScript method for the close box of the preferences view:

 ButtonClickScript: func() begin

   newtAppBase:RememberedClose(base);
 end

Adding Information to the Title Slip

The dataDef can specify extra information that appears in the title slip for documents. To do so, you must implement the *InfoBoxExtract method in the dataDef. This method is called conditionally by Newton Works whenever the title slip is opened.

You must return a shape from the *InfoBoxExtract method. This shape is shown at the bottom of title slip, after the standard contents. You could return a text summary made into a shape, or a small sketch of a drawing, or anything else useful to show in the title slip. Figure 1-3 shows an example of the title slip for the Newton Works word processor. It has one extra line, showing the number of pages, added to the default slip. Here's an example of code that could be used to add that line:

 InfoBoxExtract: func(target, maxSize, viewDefView) begin

   local numPages := if viewDefView then viewDefView:?GetCountPages();
   if numPages then
      [MakeText(ParamStr("Number of Pages: ^0, [numPages]), 
maxSize.left, maxSize.top, maxSize.right, maxSize.top+15)];
 end

If you don't want to add any extra information, don't implement the *InfoBoxExtract method, or return nil from it.

Figure 1-3 Title slip

Supporting Newton Find Operations

A Newton Find operation is a search initiated by the user tapping the main Find icon. Such a search can include all, some, or just one Newton application. In this kind of Find operation, Newton Works is considered a single application, including all of the individual stationery installed in it. Contrast this with a Newton Works document Find operation, which is initiated by the user tapping the Find choice in the Tools picker inside a particular document. This kind of Find operation applies only to the single Newton Works document that is open, and is described in the section "Supporting Document Find".

To support a Newton Find operation that includes Newton Works, Newton Works first uses the FindStringInFrame function to search for a specified string in all soups. If this function does not find a match in a particular soup entry, Newton Works sends your dataDef the *FindFn message to allow you to do your own search of that soup entry. Note that *FindFn is called only if Newton Works doesn't find a match by using FindStringInFrame.

The *FindFn method gives you the opportunity to find data that may be stored in non-standard ways, that only your stationery knows how to decode. For example, if you compress entries, you might need to decompress them in order to do a search.

After the Find operation finishes, the system creates a Find overview that displays the found items. It uses the FindSoupExcerpt function to get a string for each item in the overview. The system sends the FindSoupExcerpt message to the dataDef for each item found in the Newton Works soups. You must supply this method in your dataDef if you want to specially construct the text that is shown for an item in the overview.

If the soup entries contain text information and you don't want to do anything special to construct the overview text, you don't need to implement the FindSoupExcerpt method. In this case, the system calls the root view method FindSoupExcerpt to obtain the overview text. This method calls the StringExtract method of the dataDef to obtain the overview text, or uses other means, if that method returns nothing.

In situations where the FindStringInFrame function is able to find a match, the root view method FindSoupExcerpt will also be able to display some text for the Find overview. If your Newton Works soup entries store string data with which these functions work, then you don't need to do anything else to support Newton Find operations.

In situations where the FindStringInFrame function does not work to search a soup entry, you'll need to implement both *FindFn and FindSoupExcerpt methods in your dataDef if you want your data to be searchable in global Find operations.

Finally, if your soup is such that sometimes the FindStringInFrame function will find a match and sometimes the *FindFn is needed, then you must implement a FindSoupExcerpt method that can handle both cases. In the case of special data found by your own *FindFn method, you will need to return a string for the overview from FindSoupExcerpt. In the case of simple string data found by FindStringInFrame, your FindSoupExcerpt method can call the root method FindSoupExcerpt to get the overview string, like this:

 GetRoot():FindSoupExcerpt(entry, resultFrame)

When the user taps an item in the Find overview, or if only a single item is found, the system sends the ShowFoundItem message to the application that owns that item. For a Newton Works soup item, this message is sent to your stationery viewDef. You must open the appropriate document, highlight the target text, and, if necessary, scroll it to display the text. Note that even though this message is sent to the viewDef, it is documented in this section for completeness.

Note that the FindSoupExcerpt and ShowFoundItem methods are documented in the Newton Programmer's Reference, since they are standard Newton 2.0 methods. Their use is also covered extensively in the chapter on Find in the Newton Programmer's Guide.