Chapter 2: Explorer's Guide to Frontier

This chapter presents a brief tour of UserLand Frontier using lots of screen shots and a limited amount of commentary. Its purpose is to help you get acquainted with the elements and capabilities of Frontier so that you have a framework within which to understand the rest of this guide.

Put on your explorer's hat. We can't tell you everything about the software in this tour. But don't be afraid to take detours or tinker with aspects of the product that you find interesting. You can quit without saving changes, or use the Revert command on the File menu, which is a good safety valve in case you make a bunch of changes and then can't figure out how to get back where you started.

It's a good idea, too, to use the Backup command in the Main menu to create a backup of the primary Frontier file before you make any changes.

This chapter begins with a brief discussion of the several types of files that make up Frontier's environment. Then it moves through the main components of Frontier, in the following order:

• the Main Window

• the Quick Script window

• the Object Database and Table Windows (where we'll also discuss variables briefly)

• word processing windows

• outline windows

• the Menubar Window (where we'll also see where scripts connected to the Menubar are stored)

The chapter concludes with an example of a typical, though abbreviated, Frontier session, where you'll create a new object in the database, write a short script to make use of it, define a menu, and attach a script to a menu item to work with the newly created object.

Frontier.root

At the most basic level, Frontier consists of just two files: the application and a file called Frontier.root -- which you'll come to think of as simply "the root" -- is where Frontier stores all of its information.

Your Frontier scripts and their associated data will also be stored in this file. In addition, you may find the Object Database that is at the heart of this file to be a handy place to keep lots of other information. We'll have much more to say on this subject in Chapter 6, which is devoted entirely to the Object Database.

Desktop scripts, import/export files

As you work with Frontier, you will probably create or use at least two other kinds of files: desktop script files and import/export files. These two file types have identical icons.

A desktop script file is similar to a Macintosh stand-alone application except that it can't run without Frontier. There are a number of these files included with Frontier (in the "Desktop Scripts" folder); you may create others. The entire "Chapter 9" is devoted to the topic of Desktop scripts.

Import/export files contain Frontier objects which have been exported from the root file to share with others or keep as a separate backup. If you double-click an exported Frontier file, it will launch Frontier (unless Frontier is already running) and then ask you where you want to store the object you are about to import. It presents a default the location from which it was exported; that's usually where you want to put it.

Utility applications

The UserLand Utilities folder contains four applications that are useful in conjunction with Frontier:

1. BarChart -- a simple scriptable charting program. Used in sample scripts and in this tutorial.

2. DocServer -- provides online documentation for all of Frontier's built-in verbs.

3. uBASE -- a simple scriptable fast flat-file database.

4. MacBird -- a user interface design tool.

Of course all these apps are very scriptable by Frontier. With the exception of BarChart, separate documentation is available for each of these applications.

Extensions

The Misc Stuff folder contains a sub-folder called "Copy to System Folder" which provides two new extensions for use with Frontier.

OSA Menu allows you to add scripts to the Finder's menu bar when Frontier is running. See Using the Scriptable Finder from Apple for more info.

IdleTime makes it possible for scripts to know how long its been since there's been any human activity (mouse clicks, keystrokes, disk insertions) on the system. This makes it possible for server-based utilities to be kinder to system managers working on the system. See the IdleTime page for details.

As usual, to install these extensions, copy them to your System Folder and restart your system.

The Main Window

When you launch Frontier you'll see a small window -- about the size of a title bar -- with a close box, a down arrow for a popup menu, some text, a flag and a resize box (see Figure 2-1).

Figure 2-1. Frontier's Main Window

This window is called the Main Window. When you click on the flag at the right end of the window, the window gets taller, revealing four previously hidden buttons (see Figure 2-2). If you save with the window in this position, it will open this way next time you launch Frontier. You can also move the window to a different place on the screen; the location will be remembered.

Figure 2-2. Main Window Expanded to Show Buttons

Each of the four buttons in the expanded Main Window opens a window showing something from the Object Database.

"Menu Bar" gets you to the menu editor window. That's where you edit or change the commands in the menubar, or the scripts linked into them. "Object DB" opens a table editor window showing the top level of the Frontier Object Database. "Quick Script" opens a window where you can type short commands to Frontier. "Tech Support" displays a small dialog with help resources. This button's behavior is implemented as a script; you can customize it as you see fit.

Normally, the Main Window in Frontier displays version information about Frontier, the amount of memory available, the current time, and how many "threads" are running. You can call one of Frontier's built-in verbs to display your own message in this window. As you open other windows, the Main Window may get hidden. To bring it to the front, select "Frontier.root" from the Windows menu. When it's in front, you can change the font, size and style for the message text; just select the desired combination from the Edit menu.

Note that the buttons are just convenient shortcuts; see The Open Menu page for the equivalent menu commands.

The Quick Script Window

First, let's look at the "Quick Script" button, and the window it opens, the Quick Script window (see Figure 2-3).

Figure 2-3. The Quick Script Window

To use the Quick Script window, just type an expression into the editing area (the larger rectangle at the top of the window) and either click on the "Run" button or press the Enter key (not the Return key). In Figure 2-4, the user has typed an arithmetic expression into the window and executed it. The result is shown in the message area at the bottom of the window.

Figure 2-4. Sample Quick Script Expression

When you type into the Quick Script window you're actually writing and running a one-line UserTalk script. To prove it, try typing something that makes no sense, as in Figure 2-5.

Figure 2-5. Nonsense Entry in Quick Script Window

Frontier responds with an error window with a message explaining why it didn't like what you typed (see Figure 2-6). Although the window looks similar to Quick Script, notice that the title is "Error Info" and the button is labelled "Go To". Clicking on the button will take you to the source of the error. This feature doesn't save much time when running from one-liners from the Quick Script window, but it's a big help later on when you write complete scripts.

Figure 2-6. Typical Error Message

Type the script shown in Figure 2-7 into the Quick Script window and press the Enter key (or click Run):

Figure 2-7. One-Line Script in Quick Script Window

Now, check out the Main Window. As you can see (Figure 2-8), the text in parentheses in the small script you just typed appears in the Main Window in place of the status information that was there originally. (You can return the Main Window to its normal task of showing you the present time and memory available simply by clicking on it.)

Figure 2-8. Message Displayed in Main Window

The first part of the script you typed in Figure 2-7 -- the word msg -- is a Frontier "verb" (a command or function). It requires one parameter, a string of characters surrounded by double quotes. The parameter must be enclosed in parentheses. (In fact, even if a verb has no parameters, it still requires parentheses.) The msg verb displays the string parameter in the Main Window.

All Frontier verbs return a value when they execute unless they produce an error message. When you run a script from the Quick Script window, this result will be displayed in the message area of that window. As you can see in Figure 2-7, msg returned a value of "true," indicating that the verb executed successfully. (In fact, msg always returns "true" because it can't fail.)

The Frontier scripting language UserTalk implements hundreds of verbs. They all follow the same pattern. Verbs have names, take parameters (enclosed in parentheses), and return values. (Full documentation on the UserTalk verbs can be found in DocServer.)

Editorial Note: The material stored in DocServer is also a website. For example, msg, points to a page of docs on the msg verb. In some places in the text of the User's Guide we link to the docs for the verb if we felt it would help.

Some verb names are structured, that is, they have the verb "category" as part of the name. Figure 2-9 presents an example of such a verb. The name of the verb is string.upper. This name tells Frontier to look in the Object Database in a table named "string", for a verb named "upper".

As you can see, string.upper takes a string as a parameter, and returns the same string converted to uppercase. While the "category.name" format may take some getting used to, the organization it offers is important for managing the wealth of verbs built into Frontier.

Figure 2-9. Frontier Verb With Structured Name

The Object Database

All the examples so far have simply carried out computations and displayed their values in the Quick Script window. You can also store values in variables so they can be used later. Figure 2-10 shows an example of a script that places a string into a variable named examples.greeting.

Figure 2-10. Sample Variable Assignment

We can then use the new variable in another Frontier script, as you can see from Figure 2-11.

Figure 2-11. Use of a Sample Variable

That's how you store values in variables. Notice that the "category.name" format can be used for variables as well as verbs.

Variable values are stored permanently in Frontier's Object Database. In this case, Frontier created (or updated) a variable named "greeting" in a table named "examples". Next time you start Frontier there will be a variable named examples.greeting and its value will be "Hello World!" (You can also create temporary variables that will not be stored; that's covered in Chapter 3.)

You can easily browse through all the stored values and change them interactively by opening the Object Database. Here's how to do this: open the Main Window, make sure the buttons are showing, and click on the "Object DB" button. You will see the Object Database table open into a window that looks something like Figure 2-12.

Figure 2-12. Top Level of Object Database

This table is the place where all variables and values are stored. You may think "Object Database" is too-fancy a name for what's going on here. But stay with it; you'll see soon why it's a database that stores objects.

Click on the triangle to the left of "examples" so that it is highlighted as shown in the figure. Click the Zoom button on the right side of the window; it will zoom open the examples table. The window that opens should look something like Figure 2-13, although it may be a different size and may be scrolled to a different position. If it helps, resize the window using the standard Macintosh resize box in the lower right corner.

Figure 2-13. Inside the Examples Table

This is where examples.greeting is stored. The table is named examples and the entry is called greeting. To prove this, change the value in the Quick Script window by typing the script shown in Figure 2-14 and executing it.

Figure 2-14. A New Value for examples.greeting

As you can see (Figure 2-15), the value of the variable examples.greeting was changed by the script you just ran from the Quick Script window.

Figure 2-15. Variable Value Modified

There are a number of ways you can create variables. You will probably create them most often either from a script or interactively in a table editor.

Try typing "examples.x = 12" (without the quotation marks, of course) in the Quick Script window. Note that there's a new value in the examples table called "x" and that it has a value of 12.

Creating a new variable interactively is a lot like adding information to a spreadsheet. Position the cursor anywhere in the table where you wish to store the new variable. Hold down the Command key and press Return. This opens a new entry in the table. Type the variable's name (e.g. "y") in the Name column. Tab to the Value column and enter a value (e.g. "27") for the variable, then hit the Enter key. You've created a new entry in the table.

There are other ways of creating new table entries and assigning them both a kind and a value. We'll discuss this subject in more detail in Chapter 4 and Chapter 5.

Frontier offers two different ways of editing the contents of objects in the Object Database. Some objects are edited "in place" in the table. You can tell these items because the item marker before their name is gray rather than a continuously outlined triangular shape. If the mouse cursor becomes an I-beam when you move it over the Value column of a variable, this is another indication you are dealing with a variable that can be edited directly in the table window. Only the simplest types of information (such as numbers and strings) can be edited in the table directly.

All other objects can only be edited in their own windows. Clicking the Zoom button or double-clicking on the item marker to the left of the entry's name in the table will open its editing window.

The Object Database can store many different types of data. To see all the different types supported by Frontier, press and hold the mouse on the "Kind" popup in the lower left corner of a table-editing window. An object can be as small as a number or a string, or as large as a script, word processing document or outline.

Some types can be converted to other types. In the examples table, look at the value of a variable called "green." Note that it is a number. Click on the item marker next to green and select "String" from the "Kind" popup. Notice that green is now a string of length 2 (that's what string [2] means). Convert it back to a number by selecting "Number" from the "Kind" popup.

You can resize the window the usual way. Frontier remembers the size and positions of all its windows from one session to the next (assuming that you save the root file).

You can change the widths of columns in a table editor. Carefully move the mouse over the border lines between columns. When the cursor changes to a pair of vertical "rails" with small left & right arrows, press the mouse button down and drag the border line. Let up on the mouse whenever you like. The other two columns automatically resize to fill the remaining space.

Tables can contain sub-tables, and sub-sub-tables and so on, up to 25 levels deep. To refer to something that's nested in a table, put a dot between the name and its table's name, as in examples.greeting. The name examples.subTable1.message refers to an object named "message" in the sub-table called subTable1, which in turn is stored in the examples table.

Note, too, that when a table is open as the frontmost window in Frontier, a special menu called (logically enough) "Table" appears on the menubar. This menu contains many commands that you'll find useful in working with tables. Its commands are actually scripts, so you can modify its behavior if you're adventuresome. The menu's basic usage is discussed in Chapter 7; we'll talk about menubars and their scripts later in this chapter.

The Word Processor

Frontier includes a built-in scriptable word processor for editing text objects stored in the Object Database. You can use this capability to create documents in Frontier and to format text documents you bring into Frontier from outside the Frontier environment.

Open the word processing object called examples.letter by double-clicking on the item marker next to its name in the examples table. You should see something like Figure 2-16. The content, scrolled position of the document and window size might be different on your system.

Figure 2-16. Sample Word Processing Text Window

You will also notice that a new menu appears in the menubar. It's called "WP" and it appears whenever a word processing text object's editing window is frontmost in Frontier.

The WP menu lets you toggle the ruler on and off. With the ruler symbols, you can set and clear tabs and select text justification. With commands on the Edit menu or their keyboard equivalents, you can change fonts and styles of some or all of the text in a word processing text object.

If you've used any popular Macintosh word processor, using a word processing editing window will be comfortable and familiar. The crucial difference is that the Frontier word processor is fully scriptable, supported by more than three dozen verbs that operate on word-processed text.

Outline Windows

One of the most important aspects of Frontier is its use of outlines. As you'll see, almost all scripting is done in an outline form. Menubars are also maintained and edited as outlines, as we'll see in the next section.

You can also use Frontier outlines for storing and clearly organizing information of any type. To see a typical outline-editing window, locate an entry in the examples table called Universe and open it in the usual way. Notice that The WP Menu is gone and The Outline Menu has taken its place (just before the Window menu). Each Frontier object that has its own editor also has its own menu. We'll use the menu in a minute. Meanwhile, Figure 2-17 shows you approximately what this window should look like.

Figure 2-17. Typical Frontier Outline

As you can see, this is a fairly typical outline format (though its contents are admittedly something less than gripping). It is shown in its "fully expanded" mode. Each line in an outline is referred to as a heading or sub-heading. The headings at the highest level of the outline are referred to as "summits." (Unlike some other commercial outliners, Frontier's built-in outliner permits you to have more than one summit, i.e. more than one heading at the leftmost position in the outline.)

In the sample outline, double-click on the item marker next to the label "North America." The outline now looks like Figure 2-18.

Figure 2-18. Partially Collapsed Sample Outline

You have now collapsed all of the sub-headings under the one on which you double-clicked. Notice that its item marker is solidly black. (You may have to move the bar cursor that is highlighting the line to see this clearly.)

Select the "Full Expand" option from the "Outline" menu and your outline returns to its previous state. Close the outline window.

Of course, Frontier's outliner is fully scriptable. We will have much more to say about using outlines in Frontier throughout this manual.

Menu Bar Windows

Frontier's menubar has four permanent menus: Apple, File, Edit, and Window. The rest of the menus are open for you to create, delete, reorganize, or modify. All editing of the menubar is done through the menubar window.

There are several ways to open that window:

• click on the Menubar button in the Main Window

• select "Menubar" from the Open menu

• type Command-M for the keyboard equivalent of the menu selection

• hold down the Option key while choosing any menu item other than one of the four permanent ones defined above

When you open this window, it will look something like Figure 2-19 (again, allowing for the possibility that it may appear different on your screen for any of a number of reasons).

Just as spreadsheets allow you to work with rows and columns of numbers, and word processors are good at editing and revising letters and reports, the menu editor in Frontier lets you edit the menubar as if it were a document.

The menu editor works just like an outline. Double-click on the item marker to the left of each line to expand and collapse sub-heads. Switch in and out of text mode (so you can edit individual menu entries) by pressing the Enter key. The arrow keys move the cursor.

Any changes you make in the outline are automatically and immediately reflected in the menubar.

Figure 2-19. The Menubar Editing Window

Any menu item can have a script linked to it. To create, edit, or examine the script activated by a menu item, select the item and then click on the "Script" button in the upper right corner of the menubar editor's window.

For example, let's find "Hello World." If the Main Menu isn't fully expanded and visible, scroll to it in the menubar editor and then double-click on the item marker immediately to the left of the headline "Main." Locate the submenu called "Misc". If it isn't expanded to show the items it contains, double-click on the item marker immediately to its left. Figure 2-20 shows what this part of the menubar outline should look like.

Figure 2-20. Partial Main Menu Outline

Pull down the Main menu and have a look at the "Misc" menu. There should be a one-to-one correspondence between what you see in the menubar and what you see in this window. Put the cursor on "Hello World" in the menubar editing window and click on the Script button in the upper right corner. This zooms out the script window linked to the "Hello World" entry in the menu, as shown in Figure 2-21.

Figure 2-21. Script Associated with Menu Entry

You can run the script by clicking on the "Run" button, or by selecting the item from the menu. Clicking on the "Run" button executes the script to completion. Clicking on the "Debug" button gives you a wide choice of debugging options (see Figure 2-22).

Figure 2-22. Script-Editing Window in Debug Mode

Click on the "Go" button to run the program. It will come as no surprise, given our earlier experiment in the Quick Script window, that the Main Window now has a message in it saying "Hello World."

Bring the menubar window to the front, move the cursor to "Count to 10" and click on the Script button. This is a simple loop that counts to 10 in the Main Window (see Listing 2-1).

Listing 2-1

First, the script initializes a temporary variable, named counter, to 0. Then it loops, adding one to counter until it's greater than 10. Every time through the loop it uses the msg verb to display the value of counter in the Main Window.

Click on "Run" and watch it work. Notice that the numbers one through ten appear in the Main Window. (On fast machines, Frontier will count so quickly that it will be difficult to see each number.) Now choose "Count to 10" from The Main Menu's Misc sub-menu; naturally, you see the same result.

Note that the script could be simplified; see Listing 2-2.

Listing 2-2

A Realistic Scenario

Let's take a few moments to walk through an abbreviated but realistic scripting session with Frontier. Don't worry if, along the way, some of the concepts seem a little fuzzy; later chapters will clarify the ideas that we will only have time to touch on here.

Most Macintosh owners we know suffer from hard disk clutter. They accumulate multiple copies of files they use frequently, temporary files that never seem to go away, unintentional backups of various kinds, and the kind of digital clutter that turns a pristine hard disk into someone's attic. Often, they don't realize the problem they've created until they save a document they've been working on for the past two hours without saving it and get the dreaded "disk full" message.

A script that would let you know what percentage of your disk is still available would help you avoid such situations. Let's build one. Fortunately, Frontier includes a couple of verbs that are going to make this script quite easy to write.

In true Frontier fashion, we'll let the user decide what kind of safety margin is appropriate for disk-full situations. We can store this information in the Object Database so it's easy to view and change.

Frontier provides a special place for you to add your own data (and scripts!), the "Workspace" table.

Creating a Safety Margin Entry

Open the Workspace table by choosing "Workspace" from the Open menu. Assuming this is your first time to open this table, it should look like Figure 2-23.

Figure 2-23. Newly Initialized Workspace Table

Press Command-Return to create a new table entry. Frontier leaves you in a position to name the newly created object. Call it "diskSafetyMargin."

Tab to the "Value" column and type the number 10. Press the Tab key or simply click in another part of the table to complete your entry. Notice that Frontier looks at the value you entered and determines that you want to store a number in this cell, so it provides the word "Number" in the "Kind" column of your new entry.

Now press Enter to leave text editing mode and return to table mode. The entire row where your new variable is stored will be selected, as in Figure 2-24.

Click in the zoom box of the window to make all its information visible.

Figure 2-24. Completed Variable Entry

Writing the Script, Step 1

Now we have a variable against which to compare our disk's percentage of free space, so let's write the script that will do the comparison.

To create a new script, choose New Script... from the Main menu. A dialog appears:

Figure 2-25. New Script Dialog

Choose "Workspace script" from the Kind popup, and enter the name of the script in the text entry box. Click on OK.

A new script window opens:

Figure 2-26. The new script

The first thing we have to do is help Frontier identify the disk we want it to examine. The file.getSystemDisk verb will tell Frontier the name of the disk from which we boot our Macintosh. Type the following line exactly as it appears here:

local (f = file.getSystemDisk ())

Writing the Script, Step 2

Now we want our script to calculate the percentage of free space on this hard disk. Press Return. Frontier gives you another item marker in the script-editing window. Type the following line into the script-editing window, exactly as it appears here:

local (pctFree = (double (file.freeSpaceOnVolume (f)) / file.volumeSize (f)) * 100)

This statement uses three Frontier verbs, which are, briefly:

• double, which simply makes sure that the value returned by the next verb is in a format we can use to calculate a decimal value ("double" stands for double-precision floating point)

• file.freeSpaceOnVolume, which produces a number indicating the number of bytes of free space on the volume called "f" (which, of course, we've just defined as our system volume)

• file.volumeSize, which produces a number indicating the total capacity of the volume in bytes

By dividing these two numbers, we get a result like ".2187." So we multiply the result by 100 to get it into a format like "21.87." This is the percentage of free space on the disk. Note that UserTalk lets you "nest" any verb (function) inside any other verb. The return value of the innermost verb is used as the parameter to the outer verb.

Writing the Script, Step 3

Next, we compare the value of this calculation against the safety margin value we set earlier. If the disk's free space is within limits, we display one message; if not, we display another. Here are the rest of the lines in the script:

Notice the indentation of the second and fourth lines. This structure is important. After you type the first of the above lines (which will become the third line in your script), press Return and then the Tab key to indent one level. When you enter that line and press Return, be sure to press Shift-Tab to return to the top level of the outline again. The same process will format the third and fourth lines correctly, as shown.

Compiling and Error-Checking the Script

Click on the "Compile" button in the script-editing window. If any errors result, click on the "Go To" button in the error window (see Figure 2-27). Frontier will take you to the point where the error occurred. Check your script to make sure it exactly matches what we have shown you.

Figure 2-27. Error Information Window and "Go To" Button

Here's the entire script for reference purposes:

local (f = file.getSystemDisk ())
local (pctFree = (double (file.freeSpaceOnVolume (f)) / file.volumeSize (f)) * 100)
if pctFree < workspace.diskSafetyMargin
	msg ("Time to clean house on your disk!")
else
	msg ("There's enough room on your disk!")

Once you've successfully compiled your script, click on the "Run" button. One of the two messages should appear in your Main Window.

Congratulations! You've written your first Frontier script and it's a pretty useful little critter besides!

Connecting to a Menu

This new script seems somewhat inconvenient to use because you have to open your workspace table, find the script, open it, and click on "Run." Actually, there are two other, somewhat faster ways to run the script.

You can type the script name into the Quick Script window, followed by a pair of parentheses, and it will run. (Remember that all verbs require parentheses, even if they don't have any parameters.) Open the Quick Script window with Cmd-semicolon and enter, the following and press Enter:

workspace.diskPctFree ()

You can also position the cursor anywhere in the line where the script is stored in the workspace table and press Command-slash to run the script.

Both of these methods, while more convenient than opening the script itself, still require you to do more work than you should have to. After all, it's your script, right? So let's attach it to a new item in the menu named with your initials.

Hold down the Option key and pull down the menu. With the Option key still held down, select "About this Menu" and release the mouse button. When the menubar editor opens, the bar cursor (highlight) should be on "About this Menu." Press Return. Frontier gives you a new menu entry with an item marker. Type the new command's name. We'll use "Check My Disk" but you can call it anything you want.

Once you've named the menu entry, click on the "Script" button to open an empty script-editing window. Type the following line of UserTalk code exactly as it appears here:

workspace.diskPctFree ()

Close the script-editing window and the menubar editor window. (This might be a good time to save your root file if you want to keep this menu item around. Press Command-S or choose the "Save" option from the File menu.) Click on the Main Window to remove any message that may be lingering from previous work we've done; it will then contain the usual status information.

Now choose "Check My Disk" from the Custom menu. In a moment, the appropriate message will appear in Frontier's Main Window.

Congratulations! You have successfully created a variable in the Object Database, written a useful script that refers to the variable, and customized Frontier's menubar to put the script at your fingertips. No matter how complex your scripts get -- and Frontier will let you write some extremely complex and powerful applications -- this process is almost identical.

---

© Copyright 1996-97 UserLand Software. This page was last built on 6/6/97; 5:57:00 PM. It was originally posted on 9/24/96; 9:36:01 AM. Internet service provided by Conxion.