---

NEW: Opening a Specified Document in Works (5/27/97)

Q: How do you make Newton Works open a particular document?

A: The easiest way is to use the ShowFoundItem method of the Works base view only as shown below. ShowFoundItem is generally intended for internal use by the application itself. However, it provides handy access for navigating to a particular soup entry, so Works supports using it for this purpose only. Do not attempt to use ShowFoundItem to do more than simply bring up an entry in the Works application.

The 2nd argument (the finder) to ShowFoundItem may be difficult to specify because Works can use stationery provided by 3rd parties, which may have special requirements for the finder. In Works, the stationery is responsible for adding data to the finder when a find is performed, and so the stationery may rely on that data being present when ShowFoundItem is later used. For all the stationery types that exist at the time this Q&A was written, a minimal finder frame of {findWords: [""]} is sufficient to allow the stationery to show the item. Please note that this is NOT a fully specified finder, however it is sufficient for the FindSoupExcerpt method, which is used widely. A full finder frame which accomplishes the same thing might look like this:

    {owner: GetRoot().NewtWorks,
     findType: 'text,
     findWords: [""],
     items: [{_proto: theEntry, title: "None"}]}

For Works stationery developers, we recommend not making any assumptions about the contents of the finder frame when implementing your ViewDef's ShowFoundItem method. (Note that ShowFoundItem is a Works-specific requirement of stationery. Generic ViewDefs do not require a ShowFoundItem method.)

Here is an inspector example of navigating Works to one of each existing stationery. The example assumes a new untitled document of each type exists. (You'll want to have your own code that finds the appropriate Works soup entry to open.)

    // make sure Works is open
    GetRoot().NewtWorks:Open();

    // find an entry
    s := GetUnionSoup("NewtWorks");
    theEntry := s:Query({text: "Untitled Paper"}):Entry();

    // show it
    GetRoot().NewtWorks:ShowFoundItem(e, {findWords: [""]});

    // the rest of them
    theEntry := s:Query({text: "Untitled Drawing"}):Entry();
    GetRoot().NewtWorks:ShowFoundItem(e, {findWords: [""]});

    theEntry := s:Query({text: "Untitled Calculations"}):Entry();
    GetRoot().NewtWorks:ShowFoundItem(e, {findWords: [""]});

    theEntry := s:Query({text: "Untitled Spreadsheet"}):Entry();
    GetRoot().NewtWorks:ShowFoundItem(e, {findWords: [""]});

    // cleanup
    theEntry := s := nil;