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 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 About 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. There have several different file types and associated icons.
Desktop scripts end with with an .ftds file extension -- or on Macs have the file type code of 'FTds.' The icon is a cowboy riding a horse:
A desktop script file is similar to a stand-alone application except that it can't run without Frontier. See Desktop Scripts for more information.
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.
Import/export files have different icons, depending on the type of object contained. These icons are variations on a theme, and all look something like this:
For a more comprehensive reference to Frontier's file types and associated icons, see the Icons page.
The About Window
You can open Frontier's About Window from the Help Menu (or, on Macs, the Apple menu).
Figure 2-1. Frontier's About Window
This window is called the About Window. When you click on the window's maximize button, the window collapses or expands, depending on its current state. 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. About Window Collapsed
Normally, the About 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 About Window may get hidden. To bring it to the front, select "About Frontier" from the Window 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.
The Quick Script Window
To open the Quick Scripting window, choose Quick Script from the Main menu, or type control-; (on Macs: command-;). The Quick Script window appears, as show in 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 keypad Enter 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 About Window. As you can see (Figure 2-8), the text in parentheses in the small script you just typed appears in the About Window in place of the status information that was there originally. (You can return the About 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 About 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 Frontier verbs can be found in DocServer.)
The material stored in DocServer is 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: go to the Window menu and choose "Frontier.root."
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.
Double-click on the triangle to the left of "examples" so that the examples table expands, as shown in Figure 2-13. (The window 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 resize controls.)
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. Press the Enter key that's next to the ' key. (On Macs that's the Return key.) This creates 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 keypad 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. If the mouse cursor becomes an I-beam when you move it over the Value column of a variable, this is an 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. 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. 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, if you're adventuresome you might want to check it out. 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.lunchReminder 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.
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 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. The object database is browsed as an outline. Menubars are also maintained and edited as outlines, as we'll see in the next section.
Outlines are so important to Frontier that the Outliner menu is always present in the menubar -- so many of Frontier's objects are actually types of outlines that it makes sense to make this menu available all the time.
You can 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. 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 "Expand Everything" option from the Outliner 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 9 permanent menus: File, Edit, Main, Outliner, Web, HTML, Boomkarks, Window, and Help. Frontier also has several "modal" menus -- menus that appear when certain types of objects are in Frontier. Your custom menu is the one with your initials. You can add additional menus by adding to this, your custom menu.
You can open your custom menu by choosing Edit Menu, the last item in your custom menu.
You can also hold down the Alt key (option key on Macs) while choosing a menu item.
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 keypad 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, double-click on the item marker to the left of the menu item.
For example, let's find "Hello World." Open your custom menu for editing by choosing Edit Menu.
If your custom menu isn't fully expanded and visible, double-click on the item marker immediately to the left of the headline "=user.prefs.initials." (That headline is actually a small script -- it uses your initials, which are stored at user.prefs.initials, as the name of the menu. Most menus do not have a script at their first summit, but this menu's special.)
Double-click on the item marker next to the "Hello World" menu item. This zooms out the script window linked to the "Hello World" entry in the menu, as shown in Figure 2-21.
Figure 2-20. 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-21).
Figure 2-21. 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 About 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 About 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 About Window.
Click on "Run" and watch it work. Notice that the numbers one through ten appear in the About Window, one number per second. Now choose "Count to 10" from your custom 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 computer 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 Main menu. Assuming this is your first time to open this table, it should look like Figure 2-23.
Figure 2-22. Newly Initialized Workspace Table
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 the keypad Enter key (or F2) 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-23.
Click in the zoom box of the window to make all its information visible.
Figure 2-23. 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 in the Object Database, choose New Script from the Table menu. A dialog appears, asking for the name. Type "diskPctFree." Click on OK.
A new script window opens:
Figure 2-24. 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 computer. 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 (or, the Enter key next to the ' character, not on the keypad). 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 Frontier 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:
Listing 2-3
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 (or, the Enter key next to the ' character) 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-25. 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 About 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 control-; (command-; on Macs) and enter, the following and press the keypad Enter key:
workspace.diskPctFree ()
You can also position the cursor anywhere in the line where the script is stored in the workspace table and press control-slash (command-slash on Macs) 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 Alt key (option key on Macs) and pull down your custom menu. With the Alt key still held down, select "Hello World" and release the mouse button. When the menubar editor opens, the bar cursor (highlight) should be on "Hello World." Press Return to create a new entry. 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, double-click on item marker to open an empty script-editing window. Type the following script 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 control-S -- command-S on Macs -- or choose Save from the File menu.) Click on the About 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 About 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.