CHAPTER 14 KEYSTROKES, FONTS, AND SCRIPTS On the surface, the design of Sculpt Animate is such as to require the minimum of rote learning. Once you have grasped a few underlying concepts the rest should follow naturally. Likewise, if you do not use the program for a while, it should not take you long to get back up to speed. The drawback of this approach, with its extensive use of menus, is that the program cannot be operated as quickly as a keyboard based program could, in the hands of an experienced user. It is quicker to press a key on the keyboard than it is to make a menu selection, provided that you are able to remember which key to press to produce the effect of a specific menu command. To address this need, Sculpt Animate makes use of the keyboard in a number of ways. There are menu-defined keyboard equivalents, 'on-the-fly' user definable hot keys, keyboard-automated text font loading, and a scripting facility that allows Sculpt Animate to be 'programmed' to perform automated routines. Script routine 'macros' can even be attached to hot keys. These are all rather advanced features, so much so that it's unlikely that any one user will make full use of all of them. Each of them addresses a specific need, however, and they are here if you need them. Keyboard menu equivalents ----------------------------- As with most Amiga programs there are a series of keyboard equivalents associated with the menus. When you scan through the menus you will notice that some commands have a notation like F1 to the right. This means that the command can also be executed by means of a keystroke, in this case the 'function key' marked 'F1'. Other commands are marked with the letter 'A' in reverse video followed by a letter. This means that the command can be accessed by holding down the right Amiga key while pressing the indicated letter key. The keyboard equivalent for a menu command will have precisely the same effect as the menu command itself would. Since the menu commands are all right there in the menus, it is easy to refresh your memory if you forget one. There is one 'universal' keyboard equivalent. Pressing the escape key (marked ESC) will cause the last menu command to be repeated. This is particularly useful if you need to perform the same command many times in a row. For example, if you need to erase a dozen edges, point the cursor to the first edge and execute the command EDIT ERASE INDICATED EDGE. Then point the cursor at the second edge and press the escape key. Continue this sequence and you will find that it is much quicker than using the menu. User settable hot keys ----------------------- The trouble with using the escape key as a short cut for a menu command is that it can only represent one command at a time. There is a way that each of the alphabetic keys, A through Z, can be assigned to a menu command, so you can set up as many as 26 single-stroke commands. If you press one of these while holding down the ALT key, then the alphabetic key becomes equivalent to the last menu command that was executed. This assignment will remain in effect until you quit the program or use the ALT key to set the key as a different equivalent. The problem with hot keys is that they require you to remember what is defined. Try to choose a letter that is reminiscent of the command you are defining, such as 'C' for SELECT CONNECTED VERTICES. The relationship needn't be alphabetic, either, for instance, 'X' could be a hot key for SNAP CURSOR TO CENTER. There are fewer keys than commands, but you will find that certain commands are used together while you are doing certain types of editing. Because the keys can be freely redefined, you may find it useful to change your definitions as a project proceeds from one stage to another. This is a 'power user' technique, though, and not recommended unless you feel comfortable with it. Fonts ----- There are still more ways in which the keyboard can be used to save time. 3D Font object library disks designed for Sculpt Animate can be purchased separately, but it can be difficult and tedious to place these font character objects in the scene using the PROJECT LOAD OBJECT command. To ease the burden, Sculpt Animate has a keyboard-driven automated font loading mechanism which can be used with font disks laid out in a particular fashion. For Sculpt Animate's purposes, a font is a set of scene files containing three dimensional models of solid characters. Individual fonts will differ in which characters they contain, but most will contain the upper case characters, and some will contain other characters as well. To activate the type-in font feature, execute the command PROJECT LOAD FONT. A standard file requester will pop up to allow you to choose the directory in which the font's scene files reside. This time it is not necessary to select a particular file, just specify the correct volume and drawer, then click OK. The 'files' portion of the requester will be ghosted whenever the PROJECT LOAD FONT command is executed. The files box of the requester should be ghosted. An additional flag will have to be allocated in the file requester call to indicate this is desired, Ken thinks (offhand) that it should fit in OK. Once a font is loaded, pressing any key that has a graphic symbol will cause the program to search the font directory. If the character is found, it will be loaded into the current window at the position of the cursor, and the cursor will be advanced to the right by the size of the character. If the character cannot be found, the screen will flash and program will begin searching for the next character. The first character you type will be scaled so that its height is the same as the height of the current window. The first character will also be loaded with the baseline aligned with the center of the active Tri-View window. To avoid a placement error, you should click the Center Tri-View gadget before typing that first character. Subsequent characters will be scaled by the same proportion and be positioned relative to the cursor until the next time you execute LOAD FONT. So long as a font is loaded, all the keys, whether or not their corresponding font objects are actually available, will be assumed to be connected to the font. User definable hot keys will not operate, nor will the script based keystroke macros that will be defined in the next section. To re-enable the other uses of the keyboard, you must execute the command PROJECT UNLOAD FONT We mentioned that fonts must be laid out in a particular fashion. For one thing, it will be assumed that characters were originally constructed in the North view, although they can be loaded into any view. The characters should be saved with PROJECT SAVE OBJECT, with the cursor placed on the character's baseline and offset some distance west (left) of the westmost vertex. The cursor's left offset will be used to space each character from the previous one. The cursor's position in the other two dimensions will be used to align the characters in a row as they are loaded. By carefully placing the cursor when each character is saved, both proportional spacing and correct handling of descenders can be provided for. Free, unconnected vertices may be placed in a character's scene file to define the character's dimensions in the scene. These vertices will not be loaded in when the character is typed. If, upon saving, the cursor was not placed to the left of the character's leftmost vertex, Sculpt Animate will attempt to estimate an appropriate spacing, say, 1/16th of the first character's width. The cursor will determine the character's baseline and depth alignment in any case. It is assumed that all a font's character scene files will be stored in a single directory, and that scenes for different fonts will be placed in separate directories. Also, each character scene must be named correctly in order for Sculpt Animate to find it. The program will use these rules when looking for a character's scene: 1) If a lowercase alphabetic character is pressed--'a', for example--then Sculpt Animate will look in the selected font directory for files named like these two, in this order: 'a.scene', and 'a_3D.scene'. 2) If an uppercase alphabetic character is pressed--'A', for example--then Sculpt Animate will look for files named like 'ua.scene' and 'acap_3D.scene'. 3) If a numeric key is pressed--'9' for example--then Sculpt Animate will look for '9.scene' and '9_3D.scene'. 4) If a slash (/) or colon (:) is pressed, Sculpt Animate will look for 'slash.scene' or 'colon.scene', respectively. 5) If any other printable character is pressed, including the ALT modified characters listed in the AmigaDOS manual, Sculpt Animate will first append '.scene' to that character, then '_3D.scene', and try to open files with these names. Examples: '&.scene', '&_3D.scene'. 6) If the character scene file still hasn't been found after the preceding rules have been applied, the '.scene' suffix will be affixed to the two-character hexadecimal equivalent of the desired character's ASCII code (for example, '3F.scene' if you pressed '?'), and one last attempt will be made to open the file. The last rule provides for characters which can be awkward to use in AmigaDOS file names. Some of these are: asterisk (*, hex equivalent 2A), space ( ,20), equals (=,3D), plus (+,2B), single quote (',27), double quote (",22), question mark (?,3F), percent (%,25), sharp (#,23), vertical bar (|,7C), semicolon (;,3B), and parentheses (28 and 29). Scripts ------- Although most people will want to operate Sculpt Animate in an interactive mode, it may also be controlled from a script command file. Script files are definitely an advanced tool, and will probably be of most interest to those with some knowledge of computer programming or traditional computer animating. A script file is a plain text file that has been typed in and saved with a text editor, such as the Amiga CLI's 'ED' command. All script file names must end with the extension '.script'. Once you have created and saved your script file, you can load and start its execution with the command PROJECT LOAD SCRIPT. This will invoke a standard file requester, which you can use to pick which script to load. When you click OK, Sculpt Animate will go through the script interpreting the commands in sequence. For instance, the following script will erase the objects in the Tri-View, load in a scene, render it, and save the resulting image. erase all load scene "test.scene" start save image "test.image" As the ultimate step in using scripts, people with programming skills can write script-generating programs to create very sophisticated, special purpose scenes. A typical application of this technique would be to create specialized objects that lend themselves to mathematical techniques. Script writing programs would make extensive use of the cursor placement and edge creation commands described in the next section. These commands operate on the principle that (East, North, Up) would be equivalent to the coordinates (X, Y, Z) in traditional mathematics. Some example script-generating programs may be found on your Sculpt Animate distribution disks. Script language ---------------- Conventions The scripting language of Sculpt Animate is based strongly on the menu structure of the program. Equivalent command exist for most of the possible actions of the mouse and each menu selection. Like most computer languages, it is very unforgiving of grammarical errors. Fortunately however, the rules are very concise and few in number. The following are the standard conventions. Commands have two basic parts: the command phrase and the parameter set. The command phrase is further broken into key words. The phrase has been reduced to the fewest key words that still convey the intent of the command. Where possible, these key words have been abbreviated to the first three or four characters of each word. For instance, the command 'SELECT CONNECTED VERTICES' would be abbreviated 'SEL CON'. When part of the command is shown in lower case in the following reference section, that part is optional and may be omitted. If the full key word is typed instead of the just the abbreviation, the rest of the word is ignored. However, if an entire additional word is entered, the word will not be ignored and an error message will appear. For the command above, the reference section would show: 'SELect CONnected vertices'. It is a good idea to place each script command on a separate line. The next group of script commands correspond to menu commands, but additional data must be supplied, usually that which is given to a requester. Items shown in angle brackets stands for this data as follows. "filename" A complete file name, including the extension, enclosed in quotes. For example "littlehouse.scene". "name" A hierarchy name, enclosed in quotes. Parents and offspring are separated by plus signs. If the hierarchy does not exist, it is created. For example "bill+leftarm" Three numbers in the range 0 to 15 to represent standard Amiga red, green, and blue values. For example 15 15 15 would represent white. Three numbers in the range 0.0 to 1.0 to represent percentile red, green, and blue values. For example 1.0 1.0 1.0 would represent white. A numeric value. One of the following: DULl SHIny MIRror LUMinous GLAss GLASS2 METal One of the following: INWard OUTward One of the following: CALculated SPEcified One of the following: REGular CUSp Three numbers representing a direction. The first number is an eastward offset, the second northward and the third upward. any keyboard character that produced something on the screen except white space when it is typed. For example an alphabetic character, a digit or a special character. Not a space, tab, return, ALT etc.