Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / ORPH153B.ZIP / MANUAL2.DOC < prev next >

Wrap

Text File | 1993-03-14 | 95.7 KB | 2,583 lines

Orpheus User's Guide * Part II * THE ORPHEUS COMMAND LANGUAGE Copyright 1993 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 - Programming Command Reference ........................... 8 :[label] ........................................................... 8 Ansi ............................................................... 9 Gbox ............................................................... 9 Goto ............................................................... 11 Graphic ............................................................ 12 Gtext .............................................................. 14 Hide ............................................................... 16 Hotspot ............................................................ 17 If ................................................................. 20 Jump ............................................................... 21 Jumplist ........................................................... 22 Load ............................................................... 24 Lookfor ............................................................ 25 Netwk .............................................................. 25 Play ............................................................... 26 Quit ............................................................... 28 Run ................................................................ 29 Runbat ............................................................. 29 Set ................................................................ 30 Text ............................................................... 33 Trymode ............................................................ 37 Waitfor ............................................................ 38 Chapter 3 - Converting Old Commands ................................. 39 Versions Before 1.30: .............................................. 39 Graphic Commands ................................................ 39 Run Commands .................................................... 41 Random Commands ................................................. 41 Versions Before 1.50: .............................................. 42 Hotspot() ....................................................... 42 Jump(), Jumplist() .............................................. 42 Play() .......................................................... 42 Table 1 - Modes and Resolutions ..................................... 43 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.50, 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 3, "Converting Old 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 just one restriction: 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 moved 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 2). In the following example, trymode() takes a numeric parameter, if() takes a symbolic parameter (a keyword), text() takes a string 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. text ("This book requires EGA graphics") // 3: Text 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 note 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 or 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 (or on the line where it begins) 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. Additionally, if you use <Alt-C> from an Action or Init card and 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 - PROGRAMMING COMMAND REFERENCE --------------------------------------------------------------------------- Commands in this reference: :[label] Load Ansi Lookfor Gbox Netwk Goto Play Graphic Quit Gtext Run Hide Runbat Hotspot Set If Text 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". (By the way, in case you are wondering: the label ":END" has no special meaning to Orpheus. You could use ":grmpflstx" and it would have the same effect, as long as your goto command was "goto grmpflstx". Also, if you were to place the label ":END" in the middle of the script that would =NOT= make it the end of the script.) 8 Ansi() Display a text file containing ANSI escape sequences for color effects. Takes a single parameter, the name of the file to display. 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".) Gbox() Draw a filled rectangle in the current graphic video mode. Requires that a graphic video mode be already in effect on the user's display, either as the result of a graphic() call or by using set() with the "mode" keyword. Parameters: optional use of the keyword "text", and 5 numeric parameters to specify the color, coordinates, and size of the rectangle. Gbox() cannot be used in text modes. COLOR The first numeric parameter sets the color for the rectangle. Check the table of Modes & Resolutions for the number of colors available in each video mode. Since some PCX files reset the color palettes, you may get different results using the same number in the same mode but in association with different PCX files. COORDINATES The second numerical parameter gives the column of the upper left corner of the box, with 0 as the left edge of the screen. The next parameter gives the row of the upper left corner, with 0 as the top of the screen. The next parameter gives the width of the box (from left to right), and the last gives its height (from top to bottom). The smallest number permitted for the height and width is 1, which has the effect of drawing a thin line. COORDINATE SYSTEMS - PIXELS OR CELLS Coordinates may be given in either character cells or pixel counts. As shown in the table of Modes & Resolutions, mode 16 (for example) has a resolution of 640x350, with 80x25 character cells. In other words, the screen in mode 16 has 640 pixels across by 350 pixels down, or 80 standard characters across by 25 standard characters down. While counting in pixels gives you more precision, in some situations you will find it more convenient to count in character cells. If you use the keyword "text" as the first parameter, all coordinates are read as character cells. If you do NOT use the keyword "text", coordinates are read as pixel counts. 9 set(mode = 16) gbox(text, 14, 9, 3, 61, 20) gbox(text, 1, 12, 4, 55, 18) gbox(15, 99, 58, 427, 235) This example puts up an attractive white box framed with a narrow blue border surrounded in turn by a wide yellow border. In actuality there are 3 boxes created, one on top of the other. The first gbox() command draws the large yellow box (color 14), using text coordinates. The second gbox() command draws a smaller blue box (color 1) inside it, again using text coordinates. Notice that the upper left corner of the yellow box is at column 9, row 3, while the upper left corner of the blue box is at column 12, row 4 -- below and to the right. Additionally, while the yellow box is 61 columns wide and 20 rows deep, the blue box is 55 columns wide and 18 rows deep, so it fits neatly inside. For the white box (color 15) we want finer control in order to ensure that only a thin border from the blue box is left showing. By NOT using the text keyword we ensure that our coordinate parameters are read as pixels. With a little experimentation we can get the desired effect, just by trying some approximate numbers, pressing Alt-C to check the results, and making adjustments accordingly. In this case the blue box is reduced to a border of 2 or 3 pixels all around. By specifying a depth or width of 1 or 2 pixels, gbox() can also be used to draw a horizontal or vertical line. You can in fact build up some very interesting displays, generally with better performance and less disk-space than if you created them in a paint program and saved them to a PCX file. Note however that if you wish to use gbox() and then call graphic() to combine an image with a design onscreen, you must use the command "set(fadein = off, fadeout = off)" to prevent Orpheus from erasing the screen before displaying the graphic. 10 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. 11 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 12 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. 13 Gtext() Display text in the current graphic video mode. Requires that a graphic video mode be already in effect on the user's display, either as the result of a graphic() call or by using set() with the "mode" keyword. Parameters: optional use of the keyword "text", 3 numeric parameters giving the foreground color of the text and the coordinates at which to display the first character, and one or more text strings enclosed in quotation marks. FONTS Bitmapped fonts are not yet available (but soon will be); in their place Orpheus displays the standard "system" characters that are built into ROM. COLOR The first numerical parameter gives the foreground color in which text will be displayed. For the most readable text you will often want to create a consistent background color by preceding the gtext() call with one to gbox(). Check the table of Modes & Resolutions for the number of colors available in each video mode. Since some PCX files reset the color palettes, you may get different results if you display text on a PCX graphic. COORDINATES The second numerical parameter gives the column at which the first character of the first string will be displayed, with 0 as the left edge of the screen. The next parameter gives the row, with 0 as the top of the screen. Multiple strings are left-justified with the first character of the first string, and are displayed further down the screen according to the calculated height of a character cell. COORDINATE SYSTEMS - PIXELS OR CELLS Coordinates may be given in either character cells or pixel counts. As shown in the table of Modes & Resolutions, mode 16 for example has a resolution of 640x350, with 80x25 character cells. In other words, the screen in mode 16 has 640 pixels across by 350 pixels down, or 80 standard characters across by 25 standard characters down. While counting in pixels gives you far more precision, in some situations you will find it more convenient to count in character cells. If you use the keyword "text" as the first parameter, all coordinates will be read as character cells. If you do NOT use the keyword "text", coordinates will be read as pixel counts. In the current version of Orpheus, since only ROM characters are supported (and they can ONLY be displayed along cell coordinates), even if you give pixel coordinates they will be converted to cell coordinates. When bit-mapped fonts are available you will be able to use pixel coordinates for finer positioning. 14 The following illustration continues from the example begun for gbox(). set(fadein = off, fadeout = off, mode = 16) gbox(text, 14, 9, 3, 61, 20) // yellow box gbox(text, 1, 12, 4, 55, 18) // blue box inside it gbox(15, 99, 58, 427, 234) // white box inside it gbox(11, 99, 287, 427, 6) // bright cyan lines gbox(11, 117, 278, 391, 5) gbox(11, 135, 271, 355, 4) gbox(11, 153, 266, 319, 3) gbox(11, 170, 262, 285, 2) gbox(11, 185, 259, 255, 1) gtext(text, 5, 28, 8, "Greetings", " ", "from", " ", "Rod Willmot and the animals", " ", "at Hyperion Softword!") gtext(text, 5, 32, 17, "1-819-566-6296") set(fadeout = normal) This example begins by turning off fades in case we decide to add an on-disk image using graphic(). It then sets the video mode in preparation for the calls to gbox() and gtext(). The first three gbox() commands are taken from the example given above to illustrated gbox(); they set up a large white box in the middle of the screen, nicely framed by a thin blue border and a wider yellow border. The next 6 commands draw a series of lines of decreasing thickness, from the bottom of the white box toward the center; the effect is of receding perspective. Finally we come to the gtext() commands, both of which use the "text" keyword to let us use the coarser but easier cell coordinates. The color used is 5, magenta. The first set of strings starts at column 28, row 5; blank lines are created by entering a string as " ", a single space. Each additional string within the same command is left-justified with the first string, which begins exactly at the specified coordinates. 15 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. 16 Hotspot() The hotspot() command defines an area of a graphic or ansi screen 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, where they can be associated either with true graphics (displayed in a graphic video mode) or with ansi graphics (displayed in text mode). The hotspot() command cannot be used in Action or Init cards. Hotspot data created for a true graphic is NOT compatible with data created for an ansi graphic. There are two parameters: a linkword, and a coded data string enclosed in quotation marks. The first character of the string is "0" if the hotspot is for a true graphic, "1" if it is for an ansi graphic. hotspot( linkword , "0NLGOKLPKWQKXRKVSKUT\C") 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() or ansi() command, place the cursor on an empty line. Press <Alt-C> to perform the entire script, even if it consists only of one graphic() or ansi() 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 (the # will be 0 for a true graphic, 1 for an ansi screen): 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 17 with one or more leading spaces. (Orpheus does this automatically, but you should know the rule in case you rearrange things manually.) 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 , "0.........data string.........") hotspot( link2 , "0.........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. (For safety's sake, you should never try to use a hotspot in two different video modes.) 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 , "0.........data string.........") /hotspot( link2 , "0.........data string.........") /goto END /:HAS_EGA graphic(ega_pic.pcx, 16, full) hotspot( link1 , "0.........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 only display 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. To provide ansi graphics for users with neither EGA nor VGA, we would comment out all of the commands that use graphic modes, add our ansi() command to display an ansi screen, then proceed as above to create hotspots in the ansi screen. 18 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 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. 19 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. 20 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. Jump commands cannot be simulated in OH.EXE. Up to two parameters are permitted, of which the first must be from the following list, while the second (if any) must be a card number as explained on the next page. [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 the right of the "Save As" command you will see the hilited number of that card. Use this number as the jump parameter: jump(112) // if the card's number is 112 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 21 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. The optional second parameter is the number of the card from which you wish to "pretend" to have jumped. Suppose for example that you have a card that serves as a menu or table of contents, and that at the end of each branch leading down from it you have a "Return to Menu" or some such linkword, directing the reader back to the top. Your jump() command might use "home" or the number of the menu card. Now, if the reader were to return to the menu manually through a series of PgUp moves, on his arrival at the menu card the linkword through which he originally descended would be hilited, making it easy to select a different item from the menu. But by using the jump() command you skip over the intervening cards, so that Orpheus keeps hiliting the first linkword on the menu. Here's where the second parameter comes in handy. At each location where you wish to use jump(), go to the menu card (using a different Edit window) and find the linkword leading to that location. Go through that linkword and open the File Menu to find the card's number, and use that as your second parameter. The effect will be the same as if the reader had come from the card directly under the linkword instead of one far below. jump(10, 12) This example jumps to card 10, and pretends to have done so from card 12. If card 10 has a linkword connected to card 12, that linkword will be hilited as if the reader had just come from there. 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 listed by number. When the Reader encounters a jump(random) 22 command, it will select at random from that list. Note that the list must not include Init or Action cards. (To find out the number of a particular card, open the File Menu while in that card and note the hilited number to the right of the "Save As" prompt.) jumplist(random, include, 12, 43, 159,.........) The final example initializes a random jumplist that includes all cards EXCEPT those specified in the list. 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, 12, 76, 384,.........) The list of card numbers must be constructed as shown, with each number separated from the others by a comma; spaces are optional. 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 list must be terminated by a closing parenthesis. 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 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 card number as shown to the right of the "Save As..." command, then switch to the window with your Init card and add the number 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 card number 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 is numbered "15". 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 number. Of course you will only see this if you switch back to the window with the Init card. jumplist(random, include, 15,_ 23 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, 15,17,23,32,58,2,76) Load() The load() command is intended for use with "external objects", such as files, fonts, or other hypertext books. It takes two parameters: a keyword and a filename. Currently the sole purpose of load() is to provide a way of jumping to other hypertext books created with Orpheus. To use it, open an Action link and give the load() command together with the keyword "new" and the name of the book to load: load(new, filename.htx) The keyword "new" tells Orpheus that you want to load a new book. For a well-behaved application you might want to ensure that the user actually has the desired book files. You can do this with the lookfor() command, described below. When a load() command is successful, it performs certain cleanup functions for whatever the user has just been reading, such as saving bookmarks and notes. Then it fires up the new book, just as if the user had loaded it manually. The transition is swift and seamless, especially if both books were designed by the same person in the same style. Though currently an Orpheus book is limited to 32,000 links, with the load() command your work is infinitely extensible: any book can contain links to hundreds or thousands of other books. Note that when load() is successful, the line with that command becomes in effect the last line of the script. In other words, you cannot follow it with a play() command, for example, and expect music to play while the user starts reading the new book. 24 Lookfor() The lookfor() command checks the user's disk for a file. It takes a singe parameter, the file you wish to look for. If the file is found the okay/failed flag is set to "okay"; if not it is set to "failed". The following example combines lookfor() with load() in a realistic setting: lookfor(filename.htx) if (failed) goto MESSAGE load(new, filename.htx) goto END :MESSAGE text(okay, "Unable to find FILENAME.HTX!") :END This script checks for the presence of the desired book and skips to a text() command if the book cannot be found. Otherwise it loads the book. Even though a successful load() command would immediately abandon this script since it would no longer be present in memory, we insert a "goto END" line after it for logical consistency. 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. 25 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 enclosed in quotation marks as if it were text. 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. 26 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") 27 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 text("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. 28 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) 29 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) 30 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 off ........... ** turn off fades for multiple graphics ** 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() 31 set(fadein=diagonal, delay=0) 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.) In the final example we turn fades OFF in order to allow multiple graphics onscreen at the same time: set(fadein = off, fadeout = off) graphic(first.pcx, 18, 0, 0) graphic(second.pcx, 18, 450, 0) graphic(third.pcx, 18, 0, 390) graphic(fourth.pcx, 18, 450, 390) set(fadeout = normal) MODE Mode enables you to set the video mode independently of a call to graphic(). It is intended for situations in which you wish to do something that requires the prior establishment of a graphical video mode. Specifically, the gbox() and gtext() commands do not include a mode parameter, and so require that the video mode be changed before they are called. In the following example we want to draw a white box in the middle of the screen and then overlay a graphic inside it: set(fadein = off, fadeout = off, mode = 13) gbox(15, 99, 49, 120, 100) graphic(portrait.pcx, 13, 107, 55) set(fadeout = normal) Turning off fades ensures that the graphic() call will not erase the screen before displaying portrait.pcx. Since the box is drawn larger than the graphic, which in turn is positioned so that its upper left corner is below and to the right of the upper left corner of the box, the final effect is of a white frame around the graphic. However, in order to do this we had to set the video mode first, since gbox() requires that a graphical video mode be in effect before it is called. Another way to achieve the same effect would be to make the graphic() call first, then draw the frame around it with four separate calls to gbox(). 32 Text() For use in Action cards, the text() command lets you display up to 23 lines of text in a temporary window, with optional parameters to control appearance, screen position, and the length of time that the window remains onscreen. If options are not specified, Orpheus uses default behaviors such as calculating screen coordinates to center the window. The window area is automatically sized to fit the longest line, except when the "okay" keyword is used: this forces the window to become a standard "Okay" box with the limitations discussed below. The text() command is at once powerful, flexible, and easy to use. It is ideal for situations where you want to display a small amount of information that does not require a separate card (such as the definition of a word), or where you want the temporary text to be shown side-by-side with text on the parent card. LINES OF TEXT The text() command must receive at least one string parameter, meaning a line of text enclosed in quotation marks. Anything enclosed in quotation marks is interpreted as one line of text. text("This is a one-line message") This command displays the quoted text in a standard box, centered on the screen. To display multiple lines of text, separate your parameters with commas as you would with other commands. If there is not enough room on a line, or if you wish to enter a multiline command so that it will resemble what you intend to display, start each new parameter on a separate line, being sure to indent each such additional line by at least one leading space. The following examples have exactly the same results: text("This message", "will appear", "on three lines.") text("This message", "will appear", "on three lines.") In both versions, each intended line of text is enclosed in quotation marks, with commas separating the parameters. In the second version the two additional lines are indented so as to ensure that Orpheus doesn't misinterpret them later as separate commands. Regardless of whether the lines are entered as shown in the first version or in the second, the result will show all three lines flush left in a centered box, with two spaces on either side of the longest line: +===================+ | This message | | will appear | | on three lines. | +===================+ 33 Individual text strings cannot be broken by a newline; in other words, you CANNOT do this: text("This broken line will generate an error message") To include a blank line in your text, enter the blank line as a space enclosed in quotation marks, like so: text("This message", "will appear", " ", "on four lines!") +===================+ | This message | | will appear | | | | on four lines! | +===================+ SPECIAL CHARACTERS Two characters must be given special handling if you wish to include them in your lines of text. The " character normally means the beginning or end of a text; to include it as a literal character, precede it with a \ backslash. The backslash in turn normally means that the next character is special, so to include it as a literal character, precede it by another backslash. For example: text("This \"message\"", "gives the path", "to C:\\ORPHEUS") +===================+ | This "message" | | gives the path | | to C:\ORPHEUS. | +===================+ COORDINATES You can position the text window by specifying the screen coordinates of the upper left corner of the box. Row 1 is at the top of the screen and column 1 is at the far left. If two numbers are entered, the first is the row, the second is the column. If only one number is entered it represents the row; the box will be horizontally centered. You cannot specify the column without giving a number for the row. If no numbers are given the window is centered vertically and horizontally. For example: text(1, "This will be centered at the top of the screen.") text(1, 1, "This will be at the upper left corner.") text("This will be centered vertically and horizontally.") 34 text(18, 40, "This will appear", "in the lower right.") Whenever you use text() with coordinates, use the <Alt-G> command to verify your parameters and see the results. (Place the cursor on the line where the command begins, then press <Alt-G>.) If a row or column parameter would result in the window being partially offscreen, Orpheus will give an error message (and will not compile the command). COLOR The default colors of the text() window are those of the standard "Okay" box. You have two other choices: by using the "color" keyword with either the "help" or "text" keywords, you can use the current colors of the Help dialog or simply the current text color. The real colors shown will depend on the current settings when the user views your book. text("This appears in the colors of the \"Okay\" box") text(color = help, "This will look like the Help window") text(color = text, "This will look like normal text") Notice that the word "text" operates both as a command and as a keyword. When you use text color, both the border and the text itself appear in the same color. With the other settings, the border is usually a different color. FRAME The default frame style of the window border is a double-line box. You set your own style by using the "frame" keyword with a number from 0 to 6. The numbers represent the styles presented in the Frame Dialog, which you can view by opening the Project Menu and selecting "Frame". text(frame = 1, "This appears in a single-line box") text(frame = 0, "This appears in a box with no frame") text(frame = 5, "This appears in a box with single lines", "on the top and sides, and a double line", "on the bottom") TIMING The default behavior of a text window is to remain onscreen until the user presses a key or clicks the mouse. By using the "delay" keyword with a number from 1 to 99, you can specify the number of seconds for Orpheus to wait before clearing the screen automatically. If the user presses a key before the time is up, Orpheus stops waiting. (Note that setting "delay" inside a text() command does NOT affect the delay setting for fade effects in graphic modes.) text("This remains until the user presses a key") text(delay = 5, "This remains for 5 seconds only") 35 Now let's see all of the text() parameters working together: text(1, 50, color = help, frame = 6, delay = 30, "This little message", "stretches from the", "top line down", "along the right half", "of the screen, and", "has the colors of the", "Help dialog.", " ", "It has 2 blank lines,", "2 \"quotation\" marks,", "and a \\backslash,", "not to mention,", "commas at the ends", "of several lines.", " ", "The frame has single", "lines at top and left,", "double lines at bottom", "and right. After 30", "seconds it disappears") THE "OKAY" KEYWORD If you use the "okay" keyword as the first parameter in a text() command, you are telling Orpheus to display your message in a standard Okay box. This means that the dimensions, position, color, and frame of the window are determined entirely by Orpheus, but the resulting window has a hilited "Okay" prompt in the lower right window. No delay is permitted: the user must press a key or click a mouse button. Your message is limited to 7 lines, with a maximum line length of 57 characters. (The longest line is centered in the window, with any other lines displayed flush left with it.) +=============================================================+ | | | This book requires an EGA graphics display. | | Sorry about that! | < Okay > | +=============================================================+ 36 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. 37 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. 38 --------------------------------------------------------------------------- CHAPTER 3 - CONVERTING OLD COMMANDS --------------------------------------------------------------------------- Versions Before 1.30: Graphic Commands Run Commands Random Commands Versions Before 1.50: Hotspot() Jump(), Jumplist() Play() 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 2). Commands no longer have to be entered in capital letters. Most conversions concern commands that would have been in Graphic cards. In addition, users of versions 1.30 to 1.41 will need to update their use of hotspot(), jump(), jumplist(), and play(). Graphic Commands - Before 1.30 The commands FILEPATH=, RESOLUTION=, and MODE= are now combined into the graphic() command. 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. (2) Instead of telling Orpheus what resolution to use, with the video mode being an optional detail, you now specify only the video mode. The table of Modes & Resolutions makes it easy to find an appropriate mode, and you can test the results 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 the entry on graphic() in Chapter 2 to learn about displaying smaller graphics. 39 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. If you have existing hotspots you must delete redraw them, but read the following if you also have associated linkwords that you wish to keep. 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, "0..........data string.........") Before you can redraw the hotspot you will have to comment out any lines containing commands that are no longer valid. Get your graphic() command working first (you can test it individually with <Alt-G>), then comment out all other lines by inserting a "/" at the far left. Now delete the "HOTSPOT" line entirely, leaving the cursor on that empty line. You can now press <Alt-C> and, if the graphic displays correctly, follow the procedure for making a hotspot described in Chapter 2. Upon return from the graphic you will see a line like the one above, but with the word "linkword" as the first parameter. The final step is delete that word, then mark the original linkword you wish to replace it with and MOVE it into the new location. You can then remove the "LINKWORD" line. 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. 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) 40 Run Commands - Before 1.30 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 - Before 1.30 The RANDOM= commands have been replaced by the more capable jump() and jumplist() commands. When specific cards were listed we originally used the 3-letter extension from the filename; as of 1.50 we get the card number in decimal form by opening the File Menu while in that card, and looking at the "Save As" line. The card number is hilited at the right. RANDOM=ALL // becomes: jumplist(random, all) RANDOM=INCLUDE,00B,01A,... // became until 1.50, jumplist(random, include=00B,01A,...) // but is now: jumplist(random, include, 12, 49, ...) RANDOM=EXCLUDE,02Z,03G,... // became until 1.50, jumplist(random, exclude=02Z,03G,...) // but is now: jumplist(random, exclude, 72, 99,...) 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 2, the Programming Command Reference. 41 Hotspot() - Before 1.50 As noted above, from versions 1.30 to 1.41 the hotspot() command took a data string enclosed in two copies of the block character, ascii 254. As of version 1.50 the data string is enclosed in quotation marks like an ordinary text string, but has some other differences that are equally important. First, the first character of the string is now either "0" or "1" to mark a hotspot created for either a true graphic or an ansi screen respectively. Second, the characters used in the string are drawn from a higher range of ascii values, making old data strings completely incompatible with version 1.50 and up. (The new standard is both more coherent and more powerful, so this should be the last time you have to convert your hotspots.) To convert existing hotspot commands, you will have to redraw them and let Orpheus insert the new data string. Assuming you have a command a completed linkword that you wish to keep, comment out that line and any others that are no longer valid, then insert a blank line or two and proceed as described in chapter 2 for making a hotspot. You should be able to redraw your hotspot without any difficulty. Upon return from the graphic, delete the dummy word "linkword" and replace it with what you really want by marking the original linkword and moving it into place. Jump(), Jumplist() - Before 1.50 When specific cards were referred to, these commands previously used the 3-letter extension from each card's filename. In the case of jump() a colon was used to precede the 3-letter extension. The new standard makes things simpler by using numbers in decimal, without some of the trappings that used to be required. To find the number of a card, navigate to that card and open the File Menu; the number will be hilited on the "Save As" line. OLD USAGE: jumplist(random, include=00A, 01B, 0G9........) jump(:00A) NEW USAGE: jumplist(random, include, 10, 42, 129..........) jump(10) As you can see, the new standard is simpler and more in tune with the way other commands are given. Play() - Before 1.50 The music string given in a play() command must now be enclosed in quotation marks, as shown in Chapter 2. 42 --------------------------------------------------------------------------- TABLE 1 - MODES AND RESOLUTIONS --------------------------------------------------------------------------- All of the listed video modes are graphic modes. The "Resolution" column gives the number of pixels onscreen, with the first number being the horizontal count (pixel columns), the second being the vertical count (pixel rows). The "Text" column refers to the number of character cells available when text is displayed using the built-in ROM characters (as seen in text mode). The numbers are again given as columns x rows. Where two numbers are given under "Colors", such as 16/64, the first figure represents the number of colors that can be displayed at one time, while the second figure represents the number of colors available to choose from in that video mode. 256K means 262,144 possible colors. Mode Resolution Text Colors Adapters 4 320x200 40x25 4 CGA/EGA/VGA/MCGA 5 320x200 40x25 4 CGA/EGA/VGA/MCGA 6 640x200 80x25 2/16 CGA/EGA/VGA/MCGA 9 320x200 40x25 16 Tandy,PCjr 12 320x200 40x25 2 HGC 13 320x200 40x25 16 EGA/VGA 14 640x200 80x25 16 EGA/VGA 15 640x350 80x25 2 EGA/VGA 16 640x350 80x25 16/64 EGA/VGA 17 640x480 80x30 2/256K VGA/MCGA 18 640x480 80x30 16/256K VGA 19 320x200 40x25 256/256K VGA/MCGA 20 320x200 40x25 256/256K VGA 21 320x400 40x50 256/256K VGA 22 320x240 40x30 256/256K VGA 23 320x480 40x60 256/256K VGA 43