|
Quick Start for Experienced ScriptersThis introduction is for Frontier 4 users getting started with Frontier 5.It was written by Matt Neuburg, matt@tidbits.com; reviewed and lightly edited Sat, Sep 27, 1997 at 8:09:56 AM by DW. (Updated: Tue, Oct 7, 1997 by Matt and PBS) Thanks Matt! Where Did the Menus and Main Window Go? All the menus are still there, but they are not revealed until you choose Expert Mode from the File menu so that it is checked. Otherwise, you are in beginner mode. (Note: if you're upgrading from Frontier 4.2.3, you're automatically in Expert Mode.) Beginner menus are the File, Edit, and Window menus, plus any modal menu (WP, Outline, etc.), plus any menus in the menubar at user.menus.customMenu (see below, "Menu Organization"). We will probably also add a menu similar to the BBEdit shared Site menu. The idea is that beginners could start making file-based Web sites right away, without encountering the database directly (see below, File-based Objects). In beginner mode, one cannot see the database, and it is saved automatically at quitting time. Messages posted with msg() now appear in the About window. Choose About UserLand Frontier from the Apple menu to see it. You can zoom it so that all you see is the message part. You can resize it. You can set the font and size. You can open it from UserTalk with window.about(). The database is represented by its root window (the table edit window showing the root level of the database). Choose from the Window menu in expert mode to show it. Closing the root window closes the database, just as closing the Main Window used to do. If you feel the root window is in your way, hide it with the new Hide Window item of the Window menu. The root window can be called "root" in a script. A new verb, window.getFile("root"), tells the pathname of the database file it represents. If you used to press the buttons in the Main Window, you may not realize that there have always been command-key equivalents: see the Open menu. Table Edit Windows The three-column structure of table edit windows has been combined with the outline structure of outline edit windows: the first column is now an outline. When you double-click a triangle, you stay in the same window: the outline just expands. In this way, you can see as far as you like down the hierarchy without leaving the table edit window you're in. It is hoped that this will make database navigation more convenient, and reduce the number of open windows. Debugging is also made easier because system.compiler.stack is an outline, with local variables at all levels visible within it. To make Frontier behave in the old way, command-double-click a triangle, or hit the zoom button, or press command-enter: a separate table edit window will open. Of course, double-clicking a table edit window's titlebar to open its parent table's window still works. Adding the option-key hides the original window as the new window opens. And so forth. Every table object in the database has its own edit window, just like the old days. The expansion state of the outline is part of the window, so it is remembered between closings of that window. But of course the expansion state within one window is not going to magically communicate itself to a different window. Note the following keyboard shortcuts (borrowed from the world of outlines):
Also, keyboard navigation works basically as in outlines. Most important are these:
Plus, type the start of a sibling's name to move to it. Fat Pages Frontier 5 can read old double-clickable exported objects, but it creates files in a new format called Fat Pages. Why? The old double-clickables were resource-based, a Mac-only format; a fatPage is pure text. That means it's cross-platform, it can be included in a Web page, it can be sent over a network, and so on. When you export as a packed object, you now get a fatPage. Double-clicking the fatPage file imports back into the database. It's just as it used to be, but the file format has changed. When you export as a desktop script, you now get a fatPage. Double-clicking the fatPage file in the Finder runs the script. This magic is performed by adding a field, #runnable, to the fatPage format. To import the file instead (for editing, maybe), hold down the command-key as you double-click the file, just as in the old days. The fatPages suite is beefed up to handle all of this. Study it at your leisure. File-based Objects You can make a new non-scalar object that doesn't live in the database: it's a file all to itself. (You can still store objects in the object database, of course.) For example, suppose you just wanted to use the outliner to take some notes. Why should your outline live in the database? This way, it can be a file, just as if you were using MORE, Inspiration, Ecco or some other outlining program. This is expected to make Frontier easier for beginners; at first they'll make file-based objects, without encountering the database. To make a new file-based object, choose an item from the New submenu of the File menu. The new object opens in an untitled window. Choose Save from the File menu to save it to disk. You can Save As. You can Open a file-based object from disk; it remains file-based. Frontier is behaving just like most applications with respect to their files. (If a file-based object edit window is frontmost, Save saves it; otherwise, Save saves the database.) The name of a file-based object's edit window is the pathname of the file on disk that it represents. So you can say
window.bringToFront("myHardDisk:theScript") << or...
window.bringToFront("theScript")
This magic works because the edit window is actually editing the file's avatar in system.compiler.files, whose name is the pathname, and there is a search path to system.compiler.files. But you won't have to deal with system.compiler.files directly.To find out if a window is file-based, call window.getFile() on it and see if this returns a non-empty string. (This works on the root window too, remember.) That's a useful trick for preventing your scripts from closing a file-based window (or the root!) accidentally. The file that a file-based object is based on is a fatPage, of the same format as the file you get when you export a database object as a packed file. The only difference is that it lacks an #adrPageData field. You can save a file-based script as a Runnable with the Save As Runnable command in the File menu; that makes it a file-based desktop script which runs when opened from the Finder. There is no interface item for importing a file-based object into the database. But since it's a fatPage, it's easy to do; for example:
fatpages.getFileData ("Power:Desktop Folder:testoutline")
You'll be asked where you want to put the imported object.A file-based script has no Compile button. That's for the same reason that a menu item script has no Compile button: it's not meant to be called by other scripts, so we don't have to worry about an agent calling it while we're editing it. So we don't need to maintain two compiled versions. Dimmed Compile Button In a script edit window, the Compile button is now dimmed and unclickable if the compiled version of the script in memory is up-to-date. When you change what's in the window, the Compile button becomes clickable; that way you know it needs compiling. WPText Rulers Gone A wptext edit window no longer has the option of showing a ruler at the top. This means that tabs, justification, and margins can no longer be set manually. They can still be set by way of UserTalk. [DW note: we should update modes.menus.wptx with commands to set margins. I need it for work on Scripting News.] Menu Reorganization As part of the ongoing logical reorganization of the database, the menubar is to be logically separated into parts belonging to UserLand (in the system table) and parts belonging to the user (in the user table). This makes it easier for the user to identify and customize user-owned parts without contacting the rest of the menubar. Examine user.menus as these changes proceed. Here's what we've done so far. In user.menus.customMenu goes the =user.initials menu. If you upgraded your 4.2.3 root for this alpha-testing phase, you may wish to cut yours from system.misc.menubar and paste it into user.menus.customMenu. In system.misc.suitesMenu goes the Suites menu. So, system.misc.menubar just contains Open, Main, and Web. Users who wish to override the entire system.misc.menubar menubar can do so by creating a menubar at user.menus.menubar. Our ultimate object is that there should be no need for any user to edit system.misc.menubar. Callbacks Another part of the logical reorganization of the database involves callbacks. (Some of these were formerly known as hooks.) A number of database scripts are triggered by external actions (the database opens, the user closes a window, an Apple event arrives, etc. -- the Frontier equivalent of HyperCard's "system messages"). User scripts to be run when such events occur will be brought together into user.callbacks. The following have now appeared (some of these are new hooks):
user.callbacks.startup
user.callbacks.shutdown
user.callbacks.suspend
user.callbacks.resume
user.callbacks.openWindow
user.callbacks.closeWindow
user.callbacks.saveWindow
user.callbacks.option2Click
user.callbacks.cmd2Click
user.callbacks.control2Click
user.callbacks.compileChangedScript
user.callbacks.setExpertMode
Each entry in user.callbacks is a table of scripts to be run in turn. All of the above are working in 5.0a3 except for the openWindow callbacks. (Soon.) I think eventually there may also be user.callbacks.appleEvent. It will work differently, namely just like the traps table. DLLS The Windows equivalent of Mac UCMDs is DLLs. If you want to port your UCMD to Windows, you'll need to rewrite it as an external DLL file. Then it can be called from Frontier with a new verb, callDLL (). All of this is explained technically in a note on the Gimme 5 site. New Context Verbs Some new verbs are required because we need to be able to test what platform we're on.
You don't have to know the strings; you can check them against new compiler constants osMacOS, osWin95, osWinNT, machineX86, machinePPC, machine68K. New Strictness With Addresses After some debate, we have decided to remove the "slush" factor for address operations and verbs that expect addresses as a parameter. If you have been programming in sloppy style, some of your old scripts may break. This is the only place where we have deliberately risked breaking existing scripts. Here's the scoop. As you know, some verbs require addresses as a parameter. For example, take edit(). To open the root table for editing, you say edit(@root). In the past, if you said edit(root) instead, Frontier would reason as follows: "This poor deluded user has handed me a table thinking I can coerce a table to an address. That's ridiculous. But perhaps what's intended is the address of that table? I'll pretend that's what the user said." This is not going to happen any more. From now on, if a verb expects an address, the parameter must be an address. If it's a name, it had better be the name of something whose value is an address -- or coercible to an address, like a string. Otherwise, Frontier will complain that it cannot coerce the value to an address. We found some places in the database where scripts broke after we removed the "slush," and there may be more. There may be some in your existing scripts too. We're sorry, but this is a better way. Look at it like this: If you get into the habit of handing delete() a name instead of an address, one day when you want to delete workspace.myString you're going to say delete(workspace.myString), and workspace.myString is going to be "system", and presto, you've just deleted the whole inner workings of Frontier. This move won't save you from that sort of error, but at least it will help you stay very clear on the difference between a name and an address, so you're more likely to say delete(@workspace.myString) when that's what you mean. Remember, names are evaluated before use. A name means: the value of the object I am naming. To turn an address into a name, dereference it. Bug Fixes and Interface Tweaks Though you will probably find new bugs, you'll notice that some old bugs have been fixed. The problem with thread.evaluate() in a shared menu script has been solved. Operations like parentof(root) and sizeOf(parentof(root)) now return the correct values. The recursion limit is raised to 50 levels. The menu limit is raised, which should squash the "disappearing menus" bug. There are many interface tweaks. It is now possible to select and copy the contents of the result area in the Quick Script window. String matching of window titles is no longer case-sensitive. There is a Web submenu at the bottom of the Outline menu; you can render the current outline, you can erase it and get an outline showing all folders and HTML files in a chosen folder. The Window menu listing of open edit windows no longer separates them by type. Making a new non-scalar with the Table menu now opens the new object. fileMenu.close() closes the target, not necessarily the front window. A new renderer, Cadillac, makes tables that look like outlines. ImageRef() no longer writes out the same image file over and over if there are multiple references to it in your site. There is a new root.readme, and we will probably abolish root.examples.
|