25

File Dialogs

Four modal dialogs let the user choose from files, folders, or volumes. Nothing happens to any files directly as a result of these dialogs; the dialogs just return a pathname, which the script may use as desired. Except for file.getDisk-Dialog(), these are familiar standard Mac OS dialogs. For more about file pathnames, see Chapter 31, Driving the System; for string verbs that manipulate pathnames, see Chapter 14, Strings and Chars.

To let the user choose a file:

file.getFileDialog (text, addrResult, fileTypes)

To let the user choose a folder:

file.getFolderDialog (text, addrResult)

To let the user choose a volume:

file.getDiskDialog (text, addrResult)

To let the user specify a folder and enter a filename:

file.putFileDialog (text, addrResult)

Another standard Mac OS modal dialog, the PPCBrowser, lets the user choose from applications running on the local (AppleTalk) network. There is no need to be logged into any of the other computers, and choosing an application does not actually link to it; there is no need to supply any passwords. But only processes on computers with program linking turned on will be visible.

To let the user choose a running process:

sys.browseNetwork (text, creatorCode, addrResult)

The value returned by sys.browseNetwork() at addrResult can be used subsequently to address communications to the chosen process; see Chapter 32, Driving Other Applications.

A purely informational dialog tells things like the size, creation and modification dates, and type and creator of a file; basically, it's a more informative version of the Finder's Get Info dialog. It's hard to imagine this being used in a script; rather, it's the sort of thing one might use while writing a script.

To display the file info dialog:

dialog.fileInfo (pathname)

Modal Example

For our first example, we make a dialog like Frontier's dialog.confirm(), except that it has the stop-sign icon (already present in the resource chain as the 'ICON' whose ID is 0).

We will store the resources as database entries, bringing them into the resource chain just before showing the dialog. A major advantage of this strategy is that we can package in a subtable both the resources and the dialog "glue" script which the caller calls to display the dialog; this is aesthetically neat, and makes it easy to distribute the dialog to other users. We'll call the subtable stopDialog.

We start by drawing the dialog in ResEdit; in Figure 25-1, it is shown with its items numbered. Item 4, the static text of the dialog, will be set according to the parameter provided by the caller. Item 1, the OK button, will be the default.

We assign both the 'DLOG' and the 'DITL' ID numbers of 25000, because Frontier reserves this number, by convention, for temporarily loaded resources. Make sure that the 'DLOG' is set to use 'DITL' 25000, and that Initially Visible is unchecked in the 'DLOG' edit window so that we can set item 4 before the dialog appears. Now save the dialog resources. Let's say they are saved in a file called ResFile.

We will need a utility script to import the resources. Thus, we have an edit cycle where we edit the dialog resources in ResEdit, save them, import them with our utility script, and show the dialog in Frontier, until we are satisfied with the results. The utility script might look like this:

if not defined (people.[user.initials].stopDialog)

    new(tableType, @people.[user.initials].stopDialog)

local (dummy)

rez.getNthResource ("HD:resfile", 'DLOG', 1, @dummy, @stopDialog.stopDLOG)

rez.getNthResource ("HD:resfile", 'DITL', 1, @dummy, @stopDialog.stopDITL)

Our dialog glue script should obviously work like dialog.confirm(): it will take one parameter, the prompt text, and it will return false or true as the user clicks Cancel or OK. With this in mind, we can write the proc.

When first called, with a parameter of -1, the proc should set item 4 to the prompt, which we call s, and permit the dialog to be shown. Thereafter, if item 2 or item 1 is hit, it must close the dialog. To tell the script as a whole which item was hit, we use a variable global to the proc, which we call userHitOK. The proc is now complete!

Thus far, our glue script looks like this:

on run (s)

    local (userHitOK = false)

    on theProc(whatItem)

        case whatItem

            -1

                dialog.setValue (4, s) « s is the prompt

                return true « show the dialog

            1; 2

                userHitOK = (whatItem == 1)

                return false « close the dialog

We've defined the proc, but the glue script doesn't yet do anything. What it should do is load the resources into the resource chain, and show the dialog with dialog.run(). This will hand control over to the proc. When dialog.run() returns, the dialog has been dismissed, and the proc has set userHitOK according to whether OK was hit. So all we have to do is return userHitOK. There is no need to remove the resources from the resource chain; we don't care if a script overwrites them later on. So now we have:

on run (s)

    local (userHitOK = false)

    on theProc(whatItem)

        case whatItem

            -1

                dialog.setValue (4, s)

                return true

            1; 2

                userHitOK = (whatItem == 1)

                return false

    rez.putResource (frontier.getFilePath(), 'DITL', 25000, \

        @stopDialog.stopDITL)

    rez.putResource (frontier.getFilePath(), 'DLOG', 25000, \

        @stopDialog.stopDLOG)

    dialog.run (25000, 1, @theProc)

    return userHitOK

if run("Do you really want to erase your entire hard disk?")

    dialog.notify("You're lucky I was just kidding.")

I have added a two-line stub so we can test the glue script. Pressing its Run button brings up the test version of the dialog, as shown in Figure 25-2.

Modeless Example

Next, we illustrate a modeless dialog, with radio buttons for good measure. The purpose of the dialog will be to create a new non-scalar database entry. Again, we will package the glue script and the dialog resources in a subtable, which we will call entryMaker.

Figure 25-3 shows the dialog as drawn in ResEdit. Make sure to give the 'DLOG' window a title, so that it can be referred to in UserTalk with a window reference (in this case we call it "Make New Entry").

Figure 25-4 shows how the dialog will look when displayed in Frontier.

The proc has rather more to do than in our previous example, though there is nothing particularly hard about it. Management of the radio buttons is up to us, and we must also give the dialog its actual functionality, so that it really does create a new table entry.

The proc is initially called with a parameter of -1, whereupon it initializes the radio buttons and edit text. Subsequently, if one of the radio buttons is hit, we set it, remember what datatype it signifies, change the edit text to match, and clear the other radio buttons. When the OK button is hit, we check whether the window behind the dialog is a table, and, if it contains an entry with the name the user has provided, we make sure it's okay to replace it. If all is well, we create the new entry as specified.

Notice the use of dialog.setValue() and dialog.getValue() throughout, the variables global to the proc to maintain state from one call to the next, and the fact that we always return true (because closing the window is entirely up to the user).

on run ()

    local (whatType = scriptType, whatName = "newScript")

    local (typeList = {scriptType, wptextType, outlineType, tableType})

    local (nameList = {"newScript", "newWptext", "newOutline", "newTable"})

    on theProc(whatItem)

        case whatItem

            -1

                dialog.setValue(3, true)

                dialog.setValue(7, "newScript")

            3; 4; 5; 6

                local (x)

                for x = 3 to 6

                    dialog.setValue (x, whatItem == x)

                dialog.setValue (7, nameList [whatItem - 2])

                whatType = typeList [whatItem - 2]

            1

                local (theTable = window.next("Make New Entry"))

                if typeOf(theTable^) ≠ tableType

                    dialog.notify (theTable + " isn't a table.")

                else

                    whatName = dialog.getValue (7)

                    if defined (theTable^.[whatName])

                        if !(dialog.yesNo("Replace existing "+whatName+"?"))

                            return true

                    new (whatType, @theTable^.[whatName])

        return true

    rez.putResource (frontier.getFilePath(), 'DITL', 25000, @entryMaker.ditl)

    rez.putResource (frontier.getFilePath(), 'DLOG', 25000, @entryMaker.dlog)

    dialog.runModeless (25000, 1, @theProc)

run()

File-Based Resources

In the previous examples, the resources live in the database and are loaded into the resource fork of the database file just before showing the dialog. This makes the edit cycle a two-step process, because the resources are edited in ResEdit and must then be imported into the database.

An alternative approach is to leave the resources in the ResEdit file, and then, when the time comes to display the dialog, to load the resources directly into the resource chain by calling dialog.loadFromFile() . This verb returns the ID of the 'DLOG', so you can hand the result to dialog.run() or dialog. runModeless():

dialog.run (dialog.loadFromFile ("HD:resfile"), 1, @theProc)

In fact, there is another utility script, dialog.runFromFile(), consisting essentially of this very line.

This approach shortens the edit cycle: edit the resources in ResEdit, save the resource file, and display the dialog in Frontier immediately. The disadvantage is that now you have an extra file without which the dialog won't work; keeping the resources in the database is neater and makes it much easier to distribute your dialog to other users.

Anatomy of a MacBird Card

When you work with a card from within MacBird, it contains three primary sorts of things. First, there are the items of the dialog, the buttons and text fields and such, usually referred to as objects, which you draw and edit as graphics.

Second, there are scripts associated with each object in the card. These are of two kinds. A button can have an action script ; this is accessed by choosing Button Info from the Object menu. The action script runs when the button is pressed. And any dialog item can have a recalculation script ; this is accessed by selecting the item and choosing Recalculation from the Object menu. A recalculation script runs in response to an external event: when first starting up the card, or when another object in the card is changed, or at preset intervals of time; the object's value is set to the result of the script.

Both recalculation scripts and action scripts are dynamically scoped: they are considered, while running, to exist at the point where card.run() was called. This means that they have access to variables and handlers that are in scope at that point of the calling script, making it possible to share information between the calling script and the card scripts.

Third, there is the card's table (which I'll call the "card-table"). This is a Frontier table embedded in the card's data; to access it, you choose Edit Table from the Edit menu in MacBird, which switches to Frontier to display the table.6 The recalculation scripts and action scripts have an implicit with to this table; so they can access scripts and other objects that are stored there. Indeed, it is common to make recalculation scripts and action scripts mere one-liners that call card-table scripts. Scripts in the card table also have an implicit with to other objects in the card-table; but they do not have access to variables and handlers in scope in the caller at the point where card.run() was called.

If the card-table contains a menubar object called menubar, and if the dialog is modeless, the menubar will appear at the top of the screen whenever the dialog is frontmost. If a script in the card-table, or a handler in scope in the caller, has the name startCard, it is called automatically before the dialog becomes visible.

Since objects in the card-table are visible to action scripts, to recalculation scripts, and to card-table scripts, the card-table can be used as a kind of global storage while the card is running. But this is not persistent storage. When card.run() is called, a copy of the card-table within the card object is created temporarily in the database; this copy is not saved back into the card object, so any changes made in the card-table are lost when the card closes. Also, because it is impossible to form an object reference to the card-table, it is impossible for a script to create a new object in it.

Card Verbs

The card verbs are not well documented. Fortunately, most of them are identical to the corresponding cardEditor verbs, which are documented (in DocServer). And it is easy to find out what the card verbs are, by looking in system.verbs.app.card. For example, to learn about card.getCardGrid(), read about cardEditor.getCardGrid() in DocServer.

The vast majority of card verbs are seldom used (and several are not meant to be used directly at all). Here, only the commonest are discussed. Only card.run() requires that the card object be specified; the others are valid only from within card scripts, and apply automatically to the card in which they live or from which they are called.

To display a card-based dialog:

card.run (addrCardObject)

To close a displayed card-based dialog:

card.close ()

window.close (windowRef  )

window.close() is the way to close modeless dialogs, which are ordinary windows.

To learn whether a card is modal:

card.isModal ()

To learn or set the enabled status of a dialog item:

card.getObjectEnabled (objectName)

card.setObjectEnabled (objectName, enabled?)

To learn or set the visibility of a dialog item:

card.getObjectVisible (objectName)

card.setObjectVisible (objectName, visible?)

To learn or set the boolean status of a dialog item:

card.getObjectFlag (objectName)

card.setObjectFlag (objectName, boolean)

To learn or set the text of a dialog item:

card.getObjectText (objectName)

card.setObjectText (objectName, string)

To learn or set the menu item list of a popup menu:

card.popup.getMenu (objectName)

card.popup.setMenu (objectName, string)

To learn or set the visibility of a popup menu's title:

card.popup.getHasLabel (objectName)

card.popup.setHasLabel (objectName, visible?)

To learn or set which menu item of a popup menu is chosen:

card.popup.getCheckedItem (objectName)

card.popup.setCheckedItem (objectName, itemNumber)

card.popup.getSelectedText (objectName)

card.popup.setSelectedText (objectName, itemText)

Modal Example

To illustrate, we rewrite our earlier resource-based examples as MacBird cards. We start with our stop-sign dialog. We'll need a glue script and a card object. We'll call the glue script run() and the card object stopCard, and we'll keep them in a subtable called stopDialog2.

First, recall how we're going to want to call the dialog; the glue script needs to work like dialog.confirm(), taking as parameter a string which is the dialog's prompt, and returning true or false as the user clicked OK or Cancel. So here is the glue script:

on run (s)

    local (result)

    card.run (@stopDialog2.stopCard)

    return result

if run("Do you really want to erase your entire hard disk?")

    dialog.notify("Lucky for you I was just kidding.")

Now s and result, our local variables, will be available to the card's recalculation and item scripts while it runs. Keeping this mind, Figure 25-5 shows our stop-sign dialog drawn in MacBird.

The dialog contains four items: an icon, a non-editable text, the Cancel button, and the OK button. The non-editable text has a recalculation script which runs on card startup and says simply:

s

The Cancel button has an action script, which says:

card.close(); result = false

The OK button has an action script, which says:

card.close(); result = true

That's all! The non-editable text says ERROR when we edit the card within MacBird, because there is no context in which to understand s; but if we click stopDialog2.run()'s Run button to test the dialog, we see the dialog shown in Figure 25-6.

Modeless Example

The "Make New Entry" dialog is much like our resource-based version, except that the pieces of the action, instead of being distributed over callbacks to a proc, are distributed over various recalculation and action scripts, and instead of communicating with one another through variables global to the proc, they communicate with one another through entries in the card-table. One major difference is that in the card-based version, we don't have to manage the highlighting of the radio buttons: that's taken care of for us.

Let's name the card object entryMaker2. It needs to be designated as modeless. It is clear how to draw it in MacBird; Figure 25-7 shows the dialog in action, when card.run(@entryMaker2) has been called.

For simplicity, the radio buttons have item names identical to their titles: "Script", "Wptext", "Table", and "Outline". The editable text field is named "editText", and has a recalculation script which is triggered when another item changes; the recalculation script calls setEditText(), which is in the card-table. The OK button has an action script which calls makeNewEntry(), also in the card-table.

The card-table contains five items. We have just met two of them: the scripts setEditText() and makeNewEntry(). There is also a boolean, okPressed, and a string4, whatType. These will allow the scripts to communicate with one another. Finally, there is a startCard() script, which says:

okPressed = false

The reason for this is that a recalculation script triggered a change in another item has no way of knowing what item was changed. We want the editable text to change when a radio button is pressed, but not when the OK button is pressed. So we use okPressed as a flag, to tell the recalculation script when to change and when not.

Here is setEditText(): remember, this is called by the editable text field's recalculation script every time the user clicks a button, and its result becomes the text of the text field:

local (x, buttonNames = {"Script", "Table", "Wptext", "Outline"})

local (typeList = {scriptType, tableType, wptextType, outlineType})

if okPressed

    okPressed = false

    return card.getObjectText("editText")

for x = 1 to 4

    if card.getObjectFlag(buttonNames[x])

        whatType = typeList[x]

        return "new" + (buttonNames[x])

When the user presses the OK button, okPressed is set to true by the OK button's action script; so in order to keep the editable text field from changing its text, setEditText() returns its current text! If the user presses a radio button, that button highlights and the other radio buttons are unhighlighted, automatically; now we check each radio button to find which one is highlighted, and use the result to set whatType and the text of the editable text field.

Finally, here is makeNewEntry(), called when the user presses the OK button:

local (theTable = window.next("Make New Entry"))

if typeOf(theTable^) ≠ tableType

    dialog.notify (theTable + " isn't a table.")

else

    local (whatName = card.getObjectText("editText"))

    if (!defined (theTable^.[whatName])) \

    or (dialog.yesNo ("Replace existing " + whatName + "?"))

        new (whatType, @theTable^.[whatName])

okPressed = true

This is almost identical to the proc of the resource-based version; the chief difference is a slight rearrangement so that the very last thing we do, regardless of the execution path, is set okPressed to true, so that setEditText() won't change the value of the editable text field.