The Business Master (3rd Edition)

home *** CD-ROM | disk | FTP | other *** search

/ The Business Master (3rd Edition) / The Business Master (3rd Edition).iso / files / wordmisc / orphes3 / manual2.doc < prev next >

Wrap

Text File | 1993-02-09 | 67.3 KB | 1,921 lines

Orpheus User's Guide * Part II * THE ORPHEUS COMMAND LANGUAGE Copyright 1992 Hyperion Softword 1 --------------------------------------------------------------------------- T A B L E O F C O N T E N T S --------------------------------------------------------------------------- Chapter 1 - Programming Hypertext ................................... 3 Init Cards ......................................................... 3 Action Cards ....................................................... 4 Graphic Cards ...................................................... 4 Orpheus Command Language ........................................... 5 Syntax ......................................................... 5 Flow Control ................................................... 6 Parameters ..................................................... 6 Variables ...................................................... 7 Testing Commands & Scripts ......................................... 7 Chapter 2 - Converting Pre-1.30 Commands ............................ 8 Graphic Commands ................................................... 8 Run Commands ....................................................... 10 Random Commands .................................................... 10 Chapter 3 - Programming Command Reference ........................... 11 :[label] ........................................................... 11 Ansi ............................................................... 12 Goto ............................................................... 12 Graphic ............................................................ 13 Hide ............................................................... 15 Hotspot ............................................................ 16 If ................................................................. 18 Jump ............................................................... 19 Jumplist ........................................................... 20 Message ............................................................ 22 Netwk .............................................................. 22 Play ............................................................... 23 Quit ............................................................... 25 Run ................................................................ 26 Runbat ............................................................. 26 Set ................................................................ 27 Trymode ............................................................ 30 Waitfor ............................................................ 31 Table 1 - Modes and Resolutions ..................................... 32 2 --------------------------------------------------------------------------- CHAPTER 1 - PROGRAMMING HYPERTEXT --------------------------------------------------------------------------- Topics in this chapter: Init Cards Action Cards Graphic Cards Orpheus Command Language Syntax Flow Control Parameters Variables Testing Commands & Scripts NOTE: Users who are upgrading from a version of Orpheus prior to 1.30, and who have used the earlier commands to display graphics or play music, will need to update their work to the new language standard. Please see Chapter 2, "Converting Pre-1.30 Commands". If you wish to display graphics, play music, or launch external programs, you will appreciate the power and flexibility of the Orpheus Command Language. First released with Version 1.30 of Orpheus, OCL provides the ability to write anything from a one-line jump command to a miniature program complete with hardware tests, multiple branches, timed pauses, even a slide show. Future releases will add more commands, with the emphasis on multimedia and user interaction. There are three types of link that lead to programmable cards: Init, Action, and Graphic links. Only these cards are programmable, and whatever you write on them will be *performed* rather than being displayed as text when your work is viewed with the Orpheus Reader. Unlike normal text cards, where only the top 24 or 25 lines will be seen in the Reader, with programmable cards you can you use the entire workspace and be sure that every line will be compiled into your finished work. In this chapter we will explore the uses, syntax, and vocabulary of the Orpheus Command Language. In the next chapter you will find a thorough presentation of every command, together with extensive examples. Init Cards Inits are created by opening the Link Menu while in any text card and selecting "Init". Only text cards can have Inits, and they may have only one each. (Text cards include the Homecard and all cards attached to Door, Note, or More links.) When you are in a card that has an Init, you can jump to it (in OH.EXE) either by pressing <Alt-I> or by opening the Link Menu and selecting "Edit Init". 3 When the Orpheus Reader loads a card that has an Init, it loads the Init in the background and performs its commands before displaying the Init's parent. For example, an Init off the Homecard might contain a graphical book-cover: commands to display one or more graphics, or even a choice of graphics or ansi graphics depending on the user's hardware. Inits are processed every time the user enters a card that has one -- with the sole exception of the Homecard, whose Init (if any) is only processed once. After the last command in an Init, control returns to its parent; normally this means that the text card is displayed and the user regains the ability to navigate. The exception is when the last command processed is a jump() command, i.e. an instruction to go to a different card. In that case the Reader loads the new card and displays that, unless it too has an Init that must be processed first. Aside from enabling you to do opening sequences, Inits are good places to set variables and declare data automatically. (These aspects will expand considerably as the language evolves.) Inits cannot contain links to other cards, nor can a graphic displayed from an Init contain hotspots. Action Cards Action cards are created by opening an Action link on a word or phrase in any text card. In OH.EXE you can jump to an Action card the same as you would to any card that is accessed through a linkword. In the Orpheus Reader, when the user clicks on an Action linkword the Action card is loaded in the background and its commands are processed. After the last command, control returns immediately to the parent card. If a graphic or ansi graphic was displayed, or if an external program was launched, the parent card is displayed afresh. The exception is if the last command processed is a jump() command, i.e. an instruction to go to a different card. In that case the Reader loads and displays the new card. Action cards cannot contain links to other cards, nor can a graphic displayed from an Action card contain hotspots. Graphic Cards Graphic cards are created by opening a Graphic link on a word or phrase in any text card. You can jump to a Graphic card the same as you would to any card that is accessed through a linkword. When you do so in OH.EXE you go to the Graphic card itself, not to whatever you intend to display with it. But when you jump to a Graphic in the Orpheus Reader you really do jump to what is intended for display. Like an Init or Action card, a Graphic card may contain anything from a single command to a script of tests and branches that display a suitable graphic or ansi graphic depending on the capabilities of the user's 4 hardware. A Graphic card may even contain a sequence of multiple graphics separated by timed delays. Unlike Init and Action cards, when the last command on a Graphic card is processed in the Reader, assuming that a graphic or ansi graphic is onscreen, control remains in the Graphic card the same as it would in a text card. That is, the mouse pointer appears, the user can open the menu or use the titlebar, and if the graphic has hotspots he can navigate through them. If you have selected "Graphic Titlebar" on the Project Menu, the Orpheus Reader's titlebar will appear automatically atop the last graphic or ansi graphic displayed from a Graphic card. If this option was not selected, the titlebar only appears when the user moves the mouse pointer to the top of the screen. Graphic cards may contain hotspots with links to other graphics or to text cards, with the following restrictions: (1) hotspots can only be made for real graphics, not for ansi graphics; (2) the linkword in a hotspot() command may receive a Door link or a Graphic link, but no other kind. Graphic cards may not have Inits or More links. A jump() command in a Graphic card will either be rejected by the compiler or ignored by the Reader. If by the last command in a Graphic card a graphic or ansi graphic is NOT onscreen, the Orpheus Reader assumes that an error has occurred and returns automatically to the parent card. Orpheus Command Language If you have ever written a batch file or used any other programming language, you will soon recognize how to get things done in Orpheus Command Language. Even if you have never programmed at all, you will find it easy to accomplish what you need by using the examples given in the next chapter. SYNTAX Here are the basic rules of OCL: * Command lines: commands must begin at the leftmost column. The examples in this manual are indented to enhance readability; in Orpheus they would be ignored unless shifted to the left of the screen. * Comment lines: lines beginning with a "/" or ";" are considered to be comment lines and are ignored by the command processor (and the compiler). Additionally, lines beginning with a space are ignored unless they are carried-over data from a preceding command. * Commands may be entered in any combination of upper and lower case. To enhance readability, the examples in this manual use lowercase for commands and uppercase for labels, but you do not have to do the same. (Music strings however must be in uppercase.) 5 * Within a command line, spaces may be used for readability, but are not required. The two examples below are equally valid: set(fadein=tunnelin,fadeout=venetian,delay=1) set ( fadein = tunnelin, fadeout = venetian, delay = 1 ) FLOW CONTROL The sum of the commands in a programmable card is called a "script". Sometimes a script may consist of a single command, such as "jump (retrace)" in an Action card to return the reader to wherever he came from. More often however you will write a sequence of commands that may include various possible things that you would like to happen depending on circumstances. The following example displays one of 3 possible screens in a Graphic card; which screen is chosen depends on whether the user has a VGA display, an EGA display, or neither. trymode (19) // 1: Can we do VGA mode 19? if (failed) goto NEXT // 2: If not go to line 5. graphic (vga_pic.pcx, 19, full) // 3: Show fullscreen VGA graphic. goto END // 4: Go to line 12. :NEXT // 5: Label for goto command. trymode (16) // 6: Can we do EGA mode 16? if (failed) goto TEXT // 7: If not go to line 10. graphic (ega_pic.pcx, 16, full) // 8: Show fullscreen EGA graphic. goto END // 9: Go to line 12. :TEXT // 10: Label for goto command. ansi (ansi_pic.ans) // 11: Show an ansi graphic. :END // 12: Label for goto command This script uses two "if()" tests, three labels (":NEXT", ":TEXT", and ":END"), and four "goto" commands. Processing flows along one of three possible paths depending on the user's hardware, with the result that in just 12 simple lines we can ensure that if the user clicks on a certain Graphic linkword he will actually see something. The next chapter tells about other conditions you can test, and gives a full explanation of how to use each of the commands illustrated here. PARAMETERS With the sole exception of "goto", all OCL commands must be followed by parentheses, which usually enclose one or more parameters. The number and order of parameters are specific to each command, so before you use a command for the first time you should read its entry in the Programming Command Reference (Chapter 3). In the following example, trymode() takes a numeric parameter, if() takes a symbolic parameter (a keyword), message() takes a text parameter, and quit() takes no parameter. trymode (16) // 1: Can we do EGA mode 16? if (okay) goto END // 2: If so, go to line 5. message (This book requires EGA graphics) // 3: Message box. quit () // 4: Exit the Orpheus Reader. :END // 5: Label for goto. 6 (This script is one that would go in an Init off the Homecard, in a book with a large number of EGA graphics at critical locations. If the user has an EGA-capable display he will proceed without even knowing that this script was processed. If he has a CGA or monochrome display, he will see a message box with the message in it, and when he presses a key the program will harmlessly exit.) VARIABLES Variables are objects in memory that can hold values or other data. Sometimes values are indicated with numbers, and sometimes they are indicated symbolically using keywords. The trymode() command sets an internal variable to either "failed" or "okay" depending on whether the user's display can or cannot switch to the specified video mode. These are symbolic values; in this case, the variable is unnamed. Most variables however do have names, and the set() command lets us assign values to them, either with a number of with a keyword. set (fadein=venetian, fadeout=venetian, delay=1) In this example, the first two variables are assigned the same symbolic value, "venetian", which refers to a style of fading a graphic on or off the screen. The third variable is assigned a number representing the delay factor for this effect; if delay=0 the fade is rather fast, while if delay=3 the fade is rather slow. Testing Commands & Scripts Most commands can be performed within OH.EXE as they would be in the Orpheus Reader. Those that cannot are at least checked for errors, and a report given accordingly. To test an individual command line, place the cursor on that line and press <Alt-G>. This is an easy way to see if you are specifying the right video mode for a graphic() command, or to hear a performance of a music string. In the case of a graphic() or ansi() command, once the image is displayed you need only press a key to return to editing. To test a complete script -- the entire sequence of commands in a programmable card -- press <Alt-C> while in that card. This is the "Check Card" command, which works quite differently when given from a normal text card. If you use <Alt-C> from an Action or Init card, and if your script includes a command to display a graphic or ansi graphic, you will notice that without a waitfor() command at the end your graphic merely flashes onscreen and then disappears as the Edit window returns. This is because, as I explained above, when the last command is processed in an Action or Init card control returns immediately to the parent card. In a Graphic card (which does NOT require a waitfor() line at the end), pressing <Alt-C> gives you the additional ability to create hotspots. This is explained under the hotspot() entry in the next chapter. 7 --------------------------------------------------------------------------- CHAPTER 2 - CONVERTING PRE-1.30 COMMANDS --------------------------------------------------------------------------- Commands to be converted: Graphic Commands Run Commands Random Commands All programming commands from versions prior to 1.30 must be converted to the new standard, which is described in Chapter 1 and in the Command Reference (Chapter 3). Note that commands no longer have to be entered in capital letters. The principal conversions have to do with commands that would have been in Graphic cards. Graphic Commands The commands FILEPATH=, RESOLUTION=, and MODE= are now combined into the graphic() command, which takes from 3 to 5 parameters separated by commas. The following data in the old version: FILEPATH=c:\art\bkcover.pcx RESOLUTION=640x200 MODE=14 becomes this in the new version: graphic(bkcover.pcx, 14, full) There are three points to notice here. (1) Instead of specifying the complete filepath you should give only the filename. Although you _can_ give a complete filepath, this would be compiled into the finished version of your work and would be of no use to your readers. A better technique is to store your graphics in a single directory, and tell Orpheus to look there using the ORPHEUS environment variable. (See Appendix C.) (2) Instead of telling Orpheus what screen resolution to use for your graphic, with the video mode being an optional detail for PCX files, you now specify only the video mode. The table of Modes and Resolutions in online Help makes it easy to find an appropriate mode, and you can test the results instantly by placing the cursor on the line with the command and pressing <Alt-G>. (3) Until Version 1.30 you could ONLY display full-screen graphics. Now you can display graphics that are smaller than the screen and place them anywhere you want using parameters 3 to 5. To display a full-screen graphic, just use the word "full" as in the example above. Read Appendix F to learn about displaying smaller graphics. 8 The commands HOTSPOT= and LINKWORD= are now combined into the hotspot() command. This command takes the linkword as the first parameter, with the hotspot data string as the second parameter. Note that when you draw a hotspot on a graphic, Orpheus enters the hotspot() command for you automatically along with the hotspot data, the same as it did in previous versions. But if you have existing hotspots and want to convert them to the new standard instead of deleting them, you will need to read the following. Suppose you have a graphic of a Mississippi riverboat, showing a gambler on whom you've made a hotspot. In the old commands you would have something like: HOTSPOT=5Q&6Q(7P*8P+9P+9[":O/;O0<N2=N2>U,?U#?Y(@[&■ LINKWORD=gambler In the new version this must become: hotspot( gambler, ■5Q&6Q(7P*8P+9P+9[":O/;O0<N2=N2>U,?U#?Y(@[&■) To convert old data to new, begin by typing the following (not indented as shown here, but starting at the far left on your screen): hotspot( , ■■) (If you are reading this onscreen you'll see what is intended, but if you have printed this out you may not see the real characters that are intended to go before the closing parenthesis. These are two little square boxes, which are ascii character 254. You can enter them at the keyboard by holding down the Alt key, typing 254 on the Number Keypad, then releasing the Alt key. Or you can enter them in Orpheus by using the Ascii Table, Alt-A.) Now mark your existing hotspot data -- everything between the "=" sign and the little square box at the end -- and move it to go between the two boxes in your new hotspot command. (If your data carried over onto a second line, the second line would have been padded with several "=" characters at the left margin. Be sure to delete these and replace them with spaces.) After you moved the hotspot data, mark your linkword and move it into the space between "hotspot(" and the comma. Now erase the old commands and you should be done. NOTE: previous versions of Orpheus simply ignored hotspot commands for which the linkword command did not actually have a linkword with a completed link on it. As of Version 1.30, Orpheus considers this an incomplete command and will not let you use the Alt-C command to perform the script and create new hotspots. To bypass this without deleting the command, comment it out by placing a ";" or "/" at the beginning of the line. 9 Finally, the DRAW= and ERASE= commands (for adjusting the colors used while drawing hotspots) have been changed into optional parameters of the new set() command. Thus, if you used the following before: DRAW=14 // draw in yellow ERASE=1 // erase in blue you would now use the following: set(draw=14, erase=1) Run Commands The RUN= and RUNBAT= commands now use parentheses in place of the "=" sign. If you have a line like: RUN=print file.doc you would convert it to: run(print file.doc) Random Commands The RANDOM= commands have been replaced by the more capable jump() and jumplist() commands. RANDOM=ALL becomes: jumplist(random, all) RANDOM=INCLUDE,00B,01A,... becomes: jumplist(random, include=00B,01A,...) RANDOM=EXCLUDE,02Z,03G,... becomes: jumplist(random, exclude=02Z,03G,...) RANDOM=JUMP becomes: jump(random) The jump() command in particular has far more useful purposes than the above, as you can see in the discussion of it in Chapter 3, the Programming Command Reference. 10 --------------------------------------------------------------------------- CHAPTER 3 - PROGRAMMING COMMAND REFERENCE --------------------------------------------------------------------------- Commands in this reference: :[label] message ansi netwk goto play graphic quit hide run hotspot runbat if set jump trymode jumplist waitfor This chapter provides extensive discussion of every command in the Orpheus Command Language. For a general introduction to programming in Orpheus, see Chapter 1. :[label] Lines beginning with ":" are considered label lines, with the word immediately following being a label for use in flow control. As in DOS batch files, labels are used with the goto command to control the flow of processing. The following example checks for a monochrome display, and if one is detected directs processing to the ":END" label, which in this case is the end of the script. If a mono display is not detected, processing continues to the next lines, which display a graphic and then wait for the user to press a key. if (mono) goto END graphic(mypic.pcx, 5, full) waitfor() :END Labels can be whatever you wish, but to avoid confusion you should avoid using commands or keywords belonging to Orpheus Command Language. A label is a single word, or multiple words joined by hyphen or underscore, such as "first-part" or "has_vga". 11 Ansi() Display a text file containing ANSI escape sequences for color effects. Parameters: 1 (the filename). ansi(ansi_pic.ans) Ansi files may be located in either of two locations, depending on whether OH.EXE or the Orpheus Reader is looking for them. OH.EXE looks first in the current directory, the one containing the Homecard. The Reader looks first in whichever directory contains the rest of the book files (normally the current directory unless specified on the command line). If the ansi file is not found there, Orpheus then checks for an ORPHEUS environment variable, and if one exists uses the directory specified there. (See Appendix C, "Using the ORPHEUS Environment Variable".) Goto Direct command processing to the label following the goto command. Goto may be used in two circumstances: on the same line as an if() test, and on a line of its own. trymode(18) if (failed) goto DO_ANSI graphic(big_pic.pcx, 18, full) goto END :DO_ANSI ansi(ansipic.ans) :END This example checks whether the user's display can switch to mode 18, a VGA mode. If it can't, the first goto directs the flow to the :DO_ANSI label. If it can, a graphic is displayed and then the second goto directs the flow to the :END label. Note that goto can direct the flow to *any* label in the script, regardless of whether the line is above or below the goto. 12 Graphic() Display a graphic in one of the image file formats permitted in Orpheus. Parameters: three for a full-screen graphic, otherwise from three to five. The first parameter is the filename, the second is the video mode in which to display it. If the third parameter is the keyword "full", no further parameters are required. If the third parameter is not "full", the third and fourth parameters give the x-y coordinates (column- row in pixels) of the origin of the image, while the fifth (required for SPR/PPR files only) gives the image width in pixels. In the following examples, an identical full-screen graphic is shown in both PCX and SPR image file formats, using mode 13, which has a resolution of 320 columns by 200 rows: graphic(example1.pcx, 13, full) graphic(example2.pcx, 13, 0, 0) graphic(example3.spr, 13, full) graphic(example4.spr, 13, 0, 199, 320) PCX FILES With PCX files an image is considered to originate at the upper left corner. With a full-screen graphic this would be column 0, row 0, as shown in example 2 above. We do not require the image width of a PCX file, so there is no fifth parameter. Let's suppose we have a PCX graphic that is half the size of the screen in each dimension. Since our examples use mode 13 with a resolution of 320 x 200, we'll say that our image is 160 pixels across by 100 pixels down. To center this image we would use the following: graphic(example5.pcx, 79, 49) Where did these numbers come from? We take the horizontal resolution, subtract the width of the image, divide by two, then subtract one: 320-160=160; 160/2=80; 80-1=79. We subtract 1 because screen coordinates are always counted from 0; thus the leftmost pixel coordinate is 0 and the rightmost pixel coordinate (in mode 13) is 319. The same procedure works for the vertical dimension. Take the vertical resolution, subtract the height of the image, divide by two, subtract one: 200-100=100; 100/2=50; 50-1=49. You won't always know the dimensions of an image nor where you want to show it onscreen. The best way to proceed is to try out different numbers and use the <Alt-G> Go Command to view the results. SPR/PPR FILES SPR files are captured using the SNAPSHOT utility, which comes with the registered version of Orpheus. PPR files are generated from SPR 13 files using a Fastgraph utility that compresses them. With SPR and PPR files, an image is considered to originate at the LOWER left corner, whereas with PCX files it originates at the upper left. In addition, SPR/PPR files require that we give the image width. This accounts for the numbers in example 4: graphic(example4.spr, 13, 0, 199, 320) Since this a full-screen graphic and the resolution is 320 x 200, the horizontal component of the lower left corner is pixel column 0, but the vertical component is 199 -- 1 less than the vertical resolution. The width of the image is of course 320 pixels. Let's suppose we have an SPR graphic that is half the size of the screen in both dimensions, in other words 160 pixels across by 100 pixels down. We'll center it just like we did with the half-size PCX graphic above. To calculate the column coordinate we follow the same procedure: horizontal resolution - width, divided by 2, minus 1, or: 320-160=160; 160/2=80; 80-1=79. For the row coordinate however we must proceed differently because we're calculating the lower left corner rather than the upper left corner. The procedure is: vertical resolution - height, divided by 2, subtract that from the vertical resolution, minus 1, or: 200-100=100; 100/2=50; 200-50=150; 150-1=149. Our command to center the image would thus be: graphic(example6.spr, 13, 79, 149, 160) Unless you stick to a single file type and a single video mode, you will find it useful to consult a chart of the video modes and their screen resolutions. You can find such a chart in online help, under Programming Hypertext->Graphics->Modes & Resolutions. 14 Hide() The hide() command is for use in an Init card when you wish to conceal links in its parent card. The command can be given either with no parameters or with an indeterminate sequence of numeric parameters. hide() hide(0, 2, 5) In the first example, ALL links in the parent card are concealed: if it has a More link this fact will not be known by the reader, and if it has any linkwords they will look like ordinary text -- and clicking on them will have no effect. In the second example, the More link and the second and fifth linkwords are concealed. To sum up: using hide() with no parameters hides all links in the parent. Using "0" as a parameter hides the More link; other numbers hide the equivalent linkwords as numbered sequentially from top to bottom and from left to right down the screen. The hide() command could be used in a network environment where not all readers should have access to branches with sensitive material. In a work with illustrations in VGA color, it could be used to prevent users with mono displays from experiencing the frustration of clicking on Graphic links and getting no response. Hide() will also add to the repertoire of effects when the Orpheus Command Language extends to interactive dialogs and author-created variables. 15 Hotspot() The hotspot() command defines an area of a graphic that is linked to another graphic or text card, much like a linkword in a text card. Hotspots may only be created in Graphic cards and with images that are displayed in a graphic video mode; they cannot be associated with graphics in Action or Init cards, nor can they be made for ansi screens. There are two parameters: a linkword, and a coded data string beginning and ending with a character having an ascii value of 254. (Ascii 254 is a square box-shaped character; if your printer does not support high-ascii characters it will print out in this manual as a tilde, the ~ character.) hotspot( linkword , ■5Q&6Q(7P*8P+9[":O/;O0>U,?U#?Y(@[&!■) The hotspot() command, including the coded data string, is entered by Orpheus rather than being typed in by you. The procedure is as follows: assuming you are in a Graphic card with a valid graphic() command, place the cursor on an empty line. Press <Alt-C> to perform the entire script, even if it consists only of one graphic() command. Orpheus displays the graphic and waits for your input. Press <H> to indicate that you wish to make a hotspot; Orpheus will beep twice in acknowledgement. You can now draw the hotspot by pressing or clicking the left mouse button. To erase an area, press or click the right mouse button. (Neither drawing nor erasing actually alters your original hotspot.) To cancel a partially-drawn hotspot and refresh the screen, press <Esc>. To signal that you have finished the hotspot, press <Enter>. When you press <Enter> to finish a hotspot, Orpheus returns you to the Graphic card where you will now see the new hotspot() command, something like this: hotspot( linkword , ■........data string.........■) One final step is required to make the command complete: using either the word "linkword" or a word of your own to replace it, open a link on that word (the first parameter in the hotspot() command) to create a new linked card. Two link types are permitted: Door links and Graphic links. Until this step is done the command is not considered complete and Orpheus will not carry out an <Alt-C> command in that card. When it is complete, press <Alt-C> and move the mouse pointer over the area where you drew the hotspot; notice that the mouse pointer changes shape. A hotspot can be small and simple, or large and complex; it can even be scattered in several unconnected locations. The size and complexity of the hotspot determines the length of the data string forming the second parameter. If the data string is too long to fit on one line, Orpheus will carry it over onto one or more subsequent lines. As in all cases where data is carried over, each additional line must be padded with one or more leading spaces. (Orpheus does this automatically, but you should know the rule in case you rearrange things manually.) 16 A graphic may have as many hotspots as you can define within the 50-line workspace of a card. Additionally, just as you can use flow control to provide alternate graphics for different hardware, you can provide a different set of hotspots for each graphic -- or use the same hotspots for all of them. In the first example below, we put up either a VGA or an EGA graphic, using modes that have a resolution of 320 x 200. We then install 2 hotspots which are applicable to both. trymode(19) if (failed) goto HAS_EGA graphic(vga_pic.pcx, 19, full) goto ADD_HOTSPOTS :HAS_EGA graphic(ega_pic.pcx, 13, full) :ADD_HOTSPOTS hotspot( link1 , ■.........data string.........■) hotspot( link2 , ■.........data string.........■) In the next example we will again use a VGA and an EGA graphic, but one will use a resolution of 320 x 400 (mode 23), while the other will use a resolution of 640 x 350 (mode 16). We'll suppose that the pictures are sufficiently different that each requires its own set of hotspots. In order to create the hotspots we must of course press <Alt-C> to perform the entire script; this means that at some point we must comment out all command lines that do not pertain to the graphic for which we wish to create a hotspot. /trymode(23) /if (failed) goto HAS_EGA /graphic(vga_pic.pcx, 23, full) /hotspot( link1 , ■.........data string.........■) /hotspot( link2 , ■.........data string.........■) /goto END /:HAS_EGA graphic(ega_pic.pcx, 16, full) hotspot( link1 , ■.........data string.........■) :END In this example we have already completed our work for the VGA graphic, and have temporarily commented out that section of the script using a "/" character at the beginning of each line. This ensures that <Alt-C> will perform only the display of the EGA graphic. The example shows one hotspot completed, with an empty line left where we can create another. When work is completed for both graphics we simply remove the comment characters to return the commented-out lines to the script. MULTIPLE COPIES OF LINKWORDS If you use multiple sets of hotspots for alternate graphics, you will probably want each set of hotspots to use the same links. Normally in 17 Orpheus it is not permitted to have more than one copy of a linkword; in other words, you can copy the text as often as you like, but only one instance of it can bear the embedded linking codes. This rule is ignored for Graphic cards in order to allow multiple sets of hotspots to share links. Note that to delete a linkword copy you must still use the Unlink command on the Link Menu; if a copy is detected, the unlinking procedure will only remove the linking codes from the linkword at the cursor, and will not affect the linked card. If() The if() command lets you test a condition, and either direct control to a specified label if the condition is true, or fall through to the next line if the condition is false. If() commands must be followed on the same line by a goto with a label. if (okay) goto ALRIGHT Only one parameter is permitted, from the following list: okay failed mono color "Okay" and "failed" test an internal flag that is set by the trymode() command (and in future by others). "Mono" tests whether the user has a monochrome display running in mode 7. (A monochrome display refers to one on which besides normal and blinking text we can use underline, bright, and reverse video, but not shades.) "Color" tests whether the user has a true color display, as distinct from a 1-color display capable of showing 16 shades. Other tests will be added in future. 18 Jump() The jump() command tells the Orpheus Reader to navigate directly to another card, which may be determined at random, by number, or by circumstance. Jumping automatically terminates processing of the current script; in other words, you cannot jump to another card and then carry on to the next line of the script with the jump() command. A single parameter is permitted, from the following list: :[card number] home random retrace To force a jump to a particular card, navigate to that card in another window and open the File Menu to view the card's filename. (This is displayed under the "Save As..." menu item.) Take the last three characters of that name -- in other words, the file extension, which represents the _number_ of that card -- and use it as the jump() parameter preceded by a colon. If the destination card's file extension were "00W" this would become: jump(:00W) Such a command could theoretically be given in any programmable card, but the logical place would be in an Action card, as a replacement for a Crosslink. Whereas a Crosslink can have only one destination, an Action card can contain a script that tests various things and conditionally jumps to a choice of multiple destinations. (In future releases the number of conditions to test will increase to give you considerable power and flexibility in this regard.) Note that you should NEVER force a jump to either an Init or an Action card. To force a jump to the Homecard, use: jump(home) Random jumps are permitted if you have previously initialized random jumps by using a jumplist() command together with the "random" parameter. To force a jump to a card selected at random, use: jump(random) Finally, you can force a jump to the PREVIOUS card the reader visited: jump(retrace) This last is probably the most useful variation of the jump() command. Suppose there are several cards with Crosslinks to the same card. It would be impractical for that card to contain separate Crosslinks back to each one of them. Although the user CAN retrace his path by clicking 19 on the Retrace symbol (or by pressing <Backspace> in the Reader or <Left Arrow> in OH.EXE), some users will not know this or will become frustrated by the need to think about whether they have or have not just come through a Crosslink. The user-friendly solution is to give such a card an Action link using a phrase such as "Go Back" for the linkword; then use the command "jump(retrace)" in the Action card. Jump() commands cannot be simulated in OH.EXE. Jumplist() The jumplist() command sets up a list of cards to which the Orpheus Reader can or cannot jump when given an appropriate jump() command as described in the previous section. Currently such a list can only be set up for the purpose of making random jumps; a future release will add the ability to set up a list for a guided tour. Two parameters are required, of which the first must for now be the keyword "random". The second parameter may be "all", or either "include" or "exclude" followed by a list of card numbers represented by their file extensions. The example below initializes a random jumplist and tells the Orpheus Reader that choices may be made from all of the cards in the book. Note that this automatically excludes Init and Action cards. jumplist(random, all) The next example initializes a random jumplist that includes only the cards specified in the list following the "=" sign. When the Reader encounters a jump(random) command, it will select at random from that list. Note that the list must not include Init or Action cards. jumplist(random, include=00A,00B,0GW,.........) The final examples initializes a random jumplist that includes all cards EXCEPT those specified in the list following the "=" sign. When the Reader encounters a jump(random) command, it will select at random from all cards, rejecting any choice that is on the exclude list; it will also reject any choice that is an Init or Action card. jumplist(random, exclude=00A,00B,0GW,.........) The string of file extensions, which represent card numbers, must be constructed as shown, with each 3-letter extension separated from the others by a comma, and with the list terminated by a closing parenthesis. If the list carries over to one or more additional lines, each broken line must end with a comma, and each additional line must begin with at least one leading space. The normal place to declare a jumplist is in an Init card. You can build the list either manually or automatically. Both procedures require you to start with the Init card with the uncompleted jumplist() command 20 in one window, and then switch to another window to navigate to the various cards that you intend to add to the jumplist. To do this manually, open the File Menu when in such a card, get the file extension as shown in the "Save As..." field, then switch to the window with your Init card and add the extension to the list. The semi-automatic way to accomplish the same thing requires a couple of setup steps but is then much faster. First, leave the Init card with the uncompleted jumplist() command in one window, making sure that the cursor is at the end of the line and in the position where the next file extension is to be inserted. The example below shows this with an underscore representing the position of the cursor: jumplist(random, include=_ Open the Tools Menu and select "Jumplist", then select "List Window" and tell Orpheus which window contains the Init card with the jumplist. Now switch to another window and navigate to whichever cards you wish to add to the list. At each such card, press <Alt-F3>. If the procedure is successful Orpheus will post a message saying "Added to list". Let us suppose that the first card you add has the extension "0A1". The example below shows the growing jumplist with the underscore representing the new position of the cursor, which Orpheus has advanced in preparation to receive the next extension. Of course you will only see this if you switch back to the window with the Init card. jumplist(random, include=0A1,_ Remember that to terminate the list and make the command complete, you must remove the last comma if there is one, and add a closing parenthesis as in the final example. jumplist(random, include=0A1,0A2,0AT,0B3,0G7,005,00Y) 21 Message() The message() command lets you display a 1-line message in a standard "Okay" box. There is 1 parameter, the message to be displayed, which must not exceed 60 characters in length. message(This book requires a VGA display) The message is posted in a box with the word "Okay" hilited in the lower right corner, and remains until the user presses a key or clicks the mouse. The message is automatically centered in the box. Since a ")" character is considered to terminate the command, the message may not include parentheses. Netwk() The netwk() command is for use with specially customized versions of the Orpheus Reader. It takes an indeterminate number of parameters on a single line, which are passed as a sequence of null-terminated strings preceded by a 1-byte counter giving the number of strings in the sequence. Parameters are comma-delimited. 22 Play() The play() command performs 1-voice music on the PC's internal speaker, temporarily suspending other processing until the music is finished. There is 1 parameter, a music string composed of a sequence of letters and numbers according to the convention described below. Letters in the music string must be capitalized as shown in the examples. The music string may include spaces for readability. A music string may carry over onto one or more additional lines, provided that each broken line ends with a comma and each additional line begins with one or more leading spaces. The music string must be terminated by a closing parenthesis. MUSIC SYNTAX A to G Play the specified note in the current octave. # Append to a note character (A to G) to make that note sharp. . Append to a note character or to a sharp (#) to extend that note by half its length. Multiple dots can be used, and each extends the note by half as much as the previous dot. Ln Set the length of notes and pauses. The value of "n" is a number between 1 and 64, where 1 indicates a whole note, 2 a half note, 4 a quarter note, and so on. The default is L4. On Set the octave for subsequent notes. The value of "n" may be a number from 0 to 6 to specify the octave, or it can be a "+" or "-" character to increment or decrement the current octave number. The default is O4, which contains middle C. P Pause (rest) for the duration specified by the previous L command. Sn Set the amount of silence between notes. The value of "n" is a number from 0 to 2. If 0, each note plays for the full period set by the previous L command. If 1, each note plays for 7/8 of that period. If 2, each note plays for 3/4 of that period. These effects correspond to legato, normal, and staccato playing styles. The default is S1. Tn Set the tempo of the music (the number of quarter notes per minute). The value of "n" is a number from 32 to 255. The default is T120. 23 Here are a few examples: / "Mary Had a Little Lamb" play(T150 L8 EDCDEEE P DDD P EGG P EDCDEEE L16 P L8 EDDEDC) / Beethoven's Fifth: play(T180 O2 L2 P L8 P GGG L2 D# L24 P L8 P FFF L2 D) / Simple scale up and down: play(L4 C L8S2 DEFGAB S1L4 O+C O-L8S2 BAGFED L2 C) / Chromatic scale over two octaves, with the string carried / over onto a second line play(L16 CC#DD#EFF#GG#AA#B O+ CC#DD#EFF#GG#AA#B O+ L4 C P, L16 C O- BA#AG#GF#FED#DC#C O- BA#AG#GF#FED#DC# L4 C) 24 Quit() The quit() command tells the Orpheus Reader to exit, the same as if the user had pressed <Alt-X> except that no attempt is made to save configuration, bookmark, or notepad files. There are no parameters. An obvious use for quit() would be to prevent access to a work in which high-quality graphics were REQUIRED, if the user's display was not capable of displaying those graphics. For example, the following script would go into an Init off the Homecard; after checking to see whether the user has at least a VGA color display, it either flows through to the rest of the book or displays a message and exits the program. trymode(18) if (okay) goto HAS_VGA :EXIT message(This book requires a VGA color display) quit() :HAS_VGA if (color) goto READY goto EXIT :READY Note how this script uses two different tests, either of which can branch to the exit sequence. If the user does not have VGA, the script flows through to the quit() command and we exit the program; if the user has VGA but does not have color, the script backs up so that again we flow into the quit() command and exit. The actual words used for the labels can be anything you like, and do not have to capitalized; I use uppercase labels for readability. 25 Run() The run() command launches an external program having an extension of either EXE or COM. There is a single parameter consisting of a command line reproduced exactly as you would enter it at the DOS prompt. The command line may include space-delimited parameters as you would enter them at the DOS prompt. Since a ")" character is considered to terminate the command line, the latter may not include parentheses. The run() command must not be used to launch batch files, nor can it be used to run an internal DOS command such as TYPE or COPY. (See runbat() below.) / launch LIST.COM to display README run(list readme) / launch GIFSHOW.EXE to display a sequence of 3 pictures run(gifshow jupiter.gif saturn.gif neptune.gif) / launch EDIT.EXE with no file specified run(edit) Runbat() The runbat() command launches a batch file or runs an internal DOS command such as TYPE or COPY. (Internal DOS commands are those for which there is no separate program of the same name and with a COM or EXE extension. External DOS commands are those which do refer to a separate program, such as MORE.EXE.) There is a single parameter consisting of a command line reproduced exactly as you would enter it at the DOS prompt. Since a ")" character is considered to terminate the command line, the latter may not include parentheses. If using runbat() to launch a batch file, the batch file may include calls to internal and external DOS commands as well as to other programs. Runbat() can also launch programs having a COM or EXE extension, but it takes a little more memory than run(), so it is better to use run() for such programs. / launch ORDER.BAT and specify a certain order form runbat(order book1.frm) / tell DOS to print REGISTER.DOC on the printer (1) runbat(copy register.doc prn) / tell DOS to print REGISTER.DOC on the printer (2) / note that this version requires the ">" symbol runbat(type register.doc >prn) / launch SEQUENCE.BAT with no parameters runbat(sequence) 26 Set() The set() command enables you to assign a symbolic or numerical value to a variable. Parameters consist of one or more "variable=value" phrases and may be as numerous as can fit on one line. All variables have certain default values that are discussed below; once you have assigned a value to a variable it retains that value until you change it. Currently only built-in variables may be set, but a future release will enable you to create variables of your own. The following examples illustrate the use of the set() command: set(blink=off) set(draw=1, erase=14) set(fadein=tunnelin, fadeout=venetian, delay=1) As you can see, some variables receive a numerical value, while others receive a symbolic value represented by a keyword. The list below explains what the variables mean and what values they can receive. BLINK Blink refers to the appearance of high-intensity background colors when an ansi screen is displayed with the ansi() command. Normally, such colors do NOT appear as high-intensity backgrounds but rather as areas that blink. The ability to give the command "set(blink=off)" lets you work with a more exciting color palette in your ansi screens. You can even use a time delay to show an ansi screen that starts off with blinking areas that suddenly stop and change color: set(blink=on) // in case it was set to off earlier ansi(mypic.ans) // display with blinking areas waitfor(18) // pause 1 second set(blink=off) // turn blink into bright backgrounds ansi(mypic.ans) // refresh display waitfor() // wait for keypress Note that for this effect to work you MUST make the second ansi() call, because Orpheus does not actually change blink when you give the set() command, only when an ansi screen is displayed. DELAY Delay refers to the speed of certain special effects such as fadein and fadeout, discussed below. The default value of delay is always 0, which results in a reasonably fast effect. Some special effects are quicker than others, and some are more attractive than others when slowed down. Since the delay setting applies to BOTH fadein and fadeout (and later perhaps to other variables) you may have to change it repeatedly if you are combining special effects in a sequence. The first example below sets delay to a very slow setting; the second returns it to normal: set(delay=4) / ......... set(delay=0) 27 DRAW, ERASE Draw and erase have to do with making hotspots in OH.EXE. They receive numerical values from 0 to 15, representing color values from black to white as shown in the chart below. Their default values are draw=15 (white), erase=0 (black). The following example sets draw to yellow, erase to grey: set(draw=14, erase=7) You only need to change these variables if the colors of a particular graphic made it difficult for you to distinguish between a hotspot in progress and the original graphic. Finished hotspots do not in any way alter the appearance of a graphic, and references to these variables are not included in the compiled version of a book. 0 black 8 dark grey 1 blue 9 light blue 2 green 10 light green 3 cyan 11 light cyan 4 red 12 light red 5 magenta 13 light magenta 6 brown 14 yellow 7 grey 15 white FADEIN, FADEOUT Fadein and fadeout refer to the style with which a graphic is displayed or erased. The following styles are available: normal ........ the default: replace pixels at random diagonal ...... splits the screen diagonally wipe .......... wipes image on or off from left to right split ......... splits the screen horizontally unveil ........ like a curtain venetian ...... like venetian blinds tunnelin ...... tunnels from outside to center tunnelout ..... tunnels from center to outside check ......... checkerboard style Fadein and fadeout are set individually, so you can have your graphics fading in with one style and fading out with another; you can even have a sequence of graphics in which the fade styles change with each graphic. To make this work, bear in mind that a graphic does not fade out until it is about to be replaced -- whether by another graphic, by an ansi screen, or by a text card. The following sequence varies both the speed and the style of fades: set(fadein=tunnelin, fadeout=tunnelout, delay=1) graphic(example1.pcx, 13, full) waitfor() set(fadein=diagonal, delay=0) 28 graphic(example2.pcx, 13, full) waitfor() set(fadein=wipe, fadeout=split) graphic(example3.pcx, 13, full) set(fadeout=venetian, delay=3) waitfor() The sequence begins by setting fadein, fadeout and delay for the first graphic. Before moving on it changes the fadein style for the second graphic. After displaying the second graphic it changes the fadeout style for it as well as the fadein style for the third graphic. After that graphic is displayed the fadeout style is changed again, and the delay factor set slow to emphasize the quality of the chosen style. Note that each graphic is separated by a waitfor() command to ensure that each one stays onscreen until the user presses a key. (The last waitfor() command would only be necessary in an Init or Action card.) 29 Trymode() The trymode() command provides a simple and precise way to determine the capabilities of the user's video hardware. The single parameter is the number of a video mode. Trymode() does not actually set the video mode, but rather tests the user's video system to see if it is capable of switching to that mode, and sets an internal flag accordingly. If the display CAN switch to that mode the flag is set to "okay". If the display CANNOT switch to that mode the flag is set to "failed". trymode(16) // can we do EGA? if (failed) goto END graphic(ega_pic.pcx, 16, full) :END Use trymode() in terms of the particular graphics you wish to display. The example above shows a script that might go in a Graphic card. Presumably the author first wrote the graphic() command and experimented with the mode parameter until he was sure that mode 16 was needed. As shown by Table 1, "Modes and Resolutions" (at the end of this guide), mode 16 can be handled by EGA/VGA displays, but not by less advanced displays such as the CGA. By controlling the program flow depending on the results of the trymode() test, he can ensure that if the user's hardware cannot display the graphic nothing bad will happen: the script will harmlessly skip to the end. 30 Waitfor() The waitfor() command enables you to insert a pause in a script. The optional parameter is a number representing 18ths of a second. If there is no parameter Orpheus waits until the user presses a key. If a number is given Orpheus waits that number of 18ths of a second OR until the user presses a key. In other words, waitfor() gives you an optionally timed pause that can always be broken by a keypress. / wait indefinitely until keypress waitfor() / wait 1 second (or until keypress) waitfor(18) / wait 10 seconds (or until keypress) waitfor(180) If you display graphics or ansi files from Init or Action cards, you will soon notice that you MUST place a waitfor() command at the end of the script. Otherwise, control returns immediately to the parent card and the image disappears a fraction of a second after it was displayed. This is NOT the case with Graphic cards, where control remains with the last-displayed image in the same manner as with a text card. 31 --------------------------------------------------------------------------- TABLE 1 - MODES AND RESOLUTIONS --------------------------------------------------------------------------- In the chart below, where two numbers are given under "Colors", such as 16/64, the first figure represents the number of colors that can be displayed simultaneously; the second figure represents the number of possible colors in that video mode. 256K means 262,144 possible colors. Mode Resolution Colors Adapters 4 320x200 4 CGA/EGA/VGA/MCGA 5 320x200 4 CGA/EGA/VGA/MCGA 6 640x200 2/16 CGA/EGA/VGA/MCGA 9 320x200 16 Tandy,PCjr 12 320x200 2 HGC 13 320x200 16 EGA/VGA 14 640x200 16 EGA/VGA 15 640x350 2 EGA/VGA 16 640x350 16/64 EGA/VGA 17 640x480 2/256K VGA/MCGA 18 640x480 16/256K VGA 19 320x200 256/256K VGA/MCGA 20 320x200 256/256K VGA 21 320x400 256/256K VGA 22 320x240 256/256K VGA 23 320x480 256/256K VGA 32