home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1993 #2 / Image.iso / wp / orph162b.zip / MANUAL2.DOC < prev    next >
Text File  |  1993-07-07  |  109KB  |  2,823 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.                               Orpheus User's Guide
  12.  
  13.  
  14.                                   * Part II *
  15.  
  16.  
  17.  
  18.                           THE ORPHEUS COMMAND LANGUAGE
  19.  
  20.  
  21.  
  22.  
  23.  
  24.                         Copyright 1993 Hyperion Softword
  25.  
  26.                                  (Version 1.62)
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.                                        1
  60.  
  61.  
  62.  
  63.  
  64.   ---------------------------------------------------------------------------
  65.                         T A B L E  O F  C O N T E N T S
  66.   ---------------------------------------------------------------------------
  67.  
  68.  
  69.  
  70.  Chapter 1  -  Programming Hypertext ................................... 4
  71.     Init Cards ......................................................... 4
  72.     Action Cards ....................................................... 5
  73.     Graphic Cards ...................................................... 5
  74.     Orpheus Command Language ........................................... 6
  75.         Syntax ......................................................... 6
  76.         Flow Control ................................................... 7
  77.         Parameters ..................................................... 7
  78.         Variables ...................................................... 8
  79.     Testing Commands & Scripts ......................................... 8
  80.  
  81.  Chapter 2  -  Programming Command Reference ........................... 9
  82.     :[label] ........................................................... 9
  83.     Ansi ............................................................... 10
  84.     Gbox ............................................................... 10
  85.     Goto ............................................................... 12
  86.     Graphic ............................................................ 13
  87.     Gtext .............................................................. 15
  88.     Hide ............................................................... 17
  89.     Hotspot ............................................................ 18
  90.        Multiple copies of linkwords .................................... 20
  91.        Hotspots and the keyboard ....................................... 20
  92.     If ................................................................. 21
  93.     Jump ............................................................... 22
  94.     Jumplist ........................................................... 24
  95.     Load ............................................................... 26
  96.        New ............................................................. 26
  97.        Text ............................................................ 27
  98.        Form ............................................................ 28
  99.     Lookfor ............................................................ 29
  100.     Play ............................................................... 30
  101.     Quit ............................................................... 32
  102.     Run ................................................................ 33
  103.     Runbat ............................................................. 33
  104.     Set ................................................................ 34
  105.        Blink ........................................................... 34
  106.        Delay ........................................................... 34
  107.        Draw, Erase ..................................................... 35
  108.        Fadein, Fadeout ................................................. 35
  109.        Mode ............................................................ 36
  110.     Text ............................................................... 37
  111.     Trymode ............................................................ 41
  112.     Waitfor ............................................................ 42
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.                                        2
  120.  
  121.  
  122.  
  123.  
  124.  Chapter 3  -  Converting Old Commands ................................. 43
  125.     Versions Before 1.30: .............................................. 43
  126.        Graphic Commands ................................................ 43
  127.        Run Commands .................................................... 45
  128.        Random Commands ................................................. 45
  129.     Versions Before 1.50: .............................................. 46
  130.        Hotspot() ....................................................... 46
  131.        Jump(), Jumplist() .............................................. 46
  132.        Play() .......................................................... 46
  133.  
  134.  Table 1  -  Modes and Resolutions ..................................... 47
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.                                        3
  180.  
  181.  
  182.  
  183.  
  184.   ---------------------------------------------------------------------------
  185.                       CHAPTER 1  -  PROGRAMMING HYPERTEXT
  186.   ---------------------------------------------------------------------------
  187.  
  188.  
  189.  
  190.  Topics in this chapter:  Init Cards
  191.                           Action Cards
  192.                           Graphic Cards
  193.                           Orpheus Command Language
  194.                              Syntax
  195.                              Flow Control
  196.                              Parameters
  197.                              Variables
  198.                           Testing Commands & Scripts
  199.  
  200.  
  201.  
  202.         NOTE:  Users who are upgrading from a version of Orpheus prior to
  203.     1.50, and who have used the earlier commands to display graphics or play
  204.     music, will need to update their work to the new language standard.
  205.     Please see Chapter 3, "Converting Old Commands".
  206.  
  207.         If you wish to display graphics, play music, or launch external
  208.     programs, you will appreciate the power and flexibility of the Orpheus
  209.     Command Language.  First released with Version 1.30 of Orpheus, OCL
  210.     provides the ability to write anything from a one-line jump command to a
  211.     miniature program complete with hardware tests, multiple branches, timed
  212.     pauses, even a slide show.  Future releases will add more commands, with
  213.     the emphasis on multimedia and user interaction.
  214.  
  215.         There are three types of link that lead to programmable cards:  Init,
  216.     Action, and Graphic links.  Only these cards are programmable, and
  217.     whatever you write on them will be *performed* rather than being displayed
  218.     as text when your work is viewed with the Orpheus Reader.  Unlike normal
  219.     text cards, where only the top 24 or 25 lines will be seen in the Reader,
  220.     with programmable cards you can you use the entire workspace and be sure
  221.     that every line will be compiled into your finished work.
  222.  
  223.         In this chapter we will explore the uses, syntax, and vocabulary of
  224.     the Orpheus Command Language.  In the next chapter you will find a
  225.     thorough presentation of every command, together with extensive examples.
  226.  
  227.  
  228.  Init Cards
  229.  
  230.         Inits are created by opening the Link Menu while in any text card
  231.     and selecting "Init".  Only text cards can have Inits, and they may have
  232.     only one each.  (Text cards include the Homecard and all cards attached
  233.     to Door, Note, or More links.)  When you are in a card that has an Init,
  234.     you can jump to it (in OH.EXE) either by pressing <Alt-I> or by opening
  235.     the Link Menu and selecting "Edit Init".
  236.  
  237.  
  238.  
  239.                                        4
  240.  
  241.  
  242.  
  243.  
  244.         When the Orpheus Reader loads a card that has an Init, it loads the
  245.     Init in the background and performs its commands before displaying the
  246.     Init's parent.  For example, an Init off the Homecard might contain a
  247.     graphical book-cover:  commands to display one or more graphics, or even a
  248.     choice of graphics or ansi graphics depending on the user's hardware.
  249.     Inits are processed every time the user enters a card that has one -- with
  250.     the sole exception of the Homecard, whose Init (if any) is only processed
  251.     once.
  252.  
  253.         After the last command in an Init, control returns to its parent;
  254.     normally this means that the text card is displayed and the user regains
  255.     the ability to navigate.  The exception is when the last command processed
  256.     is a jump() command, i.e. an instruction to go to a different card.  In
  257.     that case the Reader loads the new card and displays that, unless it too
  258.     has an Init that must be processed first.
  259.  
  260.         Aside from enabling you to do opening sequences, Inits are good places
  261.     to set variables and declare data automatically.  (These aspects will
  262.     expand considerably as the language evolves.)  Inits cannot contain links
  263.     to other cards, nor can a graphic displayed from an Init contain hotspots.
  264.  
  265.  
  266.  Action Cards
  267.  
  268.         Action cards are created by opening an Action link on a word or phrase
  269.     in any text card.  In OH.EXE you can jump to an Action card the same as
  270.     you would to any card that is accessed through a linkword.
  271.  
  272.         In the Orpheus Reader, when the user clicks on an Action linkword the
  273.     Action card is loaded in the background and its commands are processed.
  274.     After the last command, control returns immediately to the parent card. If
  275.     a graphic or ansi graphic was displayed, or if an external program was
  276.     launched, the parent card is displayed afresh.  The exception is if the
  277.     last command processed is a jump() command, i.e. an instruction to go to a
  278.     different card.  In that case the Reader loads and displays the new card.
  279.  
  280.         Action cards cannot contain links to other cards, nor can a graphic
  281.     displayed from an Action card contain hotspots.
  282.  
  283.  
  284.  Graphic Cards
  285.  
  286.         Graphic cards are created by opening a Graphic link on a word or
  287.     phrase in any text card.  You can jump to a Graphic card the same as you
  288.     would to any card that is accessed through a linkword.  When you do so in
  289.     OH.EXE you go to the Graphic card itself, not to whatever you intend to
  290.     display with it.  But when you jump to a Graphic in the Orpheus Reader you
  291.     really do jump to what is intended for display.
  292.  
  293.         Like an Init or Action card, a Graphic card may contain anything from
  294.     a single command to a script of tests and branches that display a suitable
  295.     graphic or ansi graphic depending on the capabilities of the user's
  296.  
  297.  
  298.  
  299.                                        5
  300.  
  301.  
  302.  
  303.  
  304.     hardware.  A Graphic card may even contain a sequence of multiple graphics
  305.     separated by timed delays.  Unlike Init and Action cards, when the last
  306.     command on a Graphic card is processed in the Reader, assuming that a
  307.     graphic or ansi graphic is onscreen, control remains in the Graphic card
  308.     the same as it would in a text card.  That is, a pointer appears, the
  309.     user can open the menu or use the titlebar, and if the graphic has
  310.     hotspots he can navigate through them.
  311.  
  312.         If you have selected "Graphic Titlebar" on the Project Menu, the
  313.     Orpheus Reader's titlebar will appear automatically atop the last graphic
  314.     or ansi graphic displayed from a Graphic card.  If this option was not
  315.     selected, the titlebar only appears when the user moves the mouse pointer
  316.     to the top of the screen (or presses Esc if no mouse is installed).
  317.  
  318.         Graphic cards may contain hotspots with links to other graphics or to
  319.     text cards, with just one restriction:  the linkword in a hotspot() 
  320.     command may receive a Door link or a Graphic link, but no other kind.
  321.     Graphic cards may not have Inits or More links.  A jump() command in a
  322.     Graphic card will either be rejected by the compiler or ignored by the
  323.     Reader.
  324.  
  325.         If by the last command in a Graphic card a graphic or ansi graphic is
  326.     NOT onscreen, the Orpheus Reader assumes that an error has occurred and
  327.     returns automatically to the parent card.
  328.  
  329.  
  330.  Orpheus Command Language
  331.  
  332.         If you have ever written a batch file or used any other programming
  333.     language, you will soon recognize how to get things done in Orpheus
  334.     Command Language.  Even if you have never programmed at all, you will find
  335.     it easy to accomplish what you need by using the examples given in the
  336.     next chapter.
  337.  
  338.     SYNTAX
  339.     Here are the basic rules of OCL:
  340.  
  341.         * Command lines:  commands must begin at the leftmost column.  The
  342.           examples in this manual are indented to enhance readability; in
  343.           Orpheus they would be ignored unless moved to the left of the
  344.           screen.
  345.  
  346.         * Comment lines:  lines beginning with a "/" or ";" are considered
  347.           to be comment lines and are ignored by the command processor (and
  348.           the compiler).  Additionally, lines beginning with a space are
  349.           ignored unless they are carried-over data from a preceding command.
  350.  
  351.         * Commands may be entered in any combination of upper and lower case.
  352.           To enhance readability, the examples in this manual use lowercase
  353.           for commands and uppercase for labels, but you do not have to do
  354.           the same.  (Music strings however must be in uppercase.)
  355.  
  356.  
  357.  
  358.  
  359.                                        6
  360.  
  361.  
  362.  
  363.  
  364.         * Within a command line, spaces may be used for readability, but are
  365.           not required.  The two examples below are equally valid:
  366.  
  367.                 set(fadein=tunnelin,fadeout=venetian,delay=1)
  368.                 set ( fadein = tunnelin, fadeout = venetian, delay = 1 )
  369.  
  370.  
  371.     FLOW CONTROL
  372.     The sum of the commands in a programmable card is called a "script".
  373.     Sometimes a script may consist of a single command, such as "jump
  374.     (retrace)" in an Action card to return the reader to wherever he came
  375.     from.  More often however you will write a sequence of commands that may
  376.     include various possible things that you would like to happen depending on
  377.     circumstances.  The following example displays one of 3 possible screens
  378.     in a Graphic card; which screen is chosen depends on whether the user has
  379.     a VGA display, an EGA display, or neither.
  380.  
  381.         trymode (19)                     // 1: Can we do VGA mode 19?
  382.         if (failed) goto NEXT            // 2: If not go to line 5.
  383.         graphic (vga_pic.pcx, 19, full)  // 3: Show fullscreen VGA graphic.
  384.         goto END                         // 4: Go to line 12.
  385.         :NEXT                            // 5: Label for goto command.
  386.         trymode (16)                     // 6: Can we do EGA mode 16?
  387.         if (failed) goto TEXT            // 7: If not go to line 10.
  388.         graphic (ega_pic.pcx, 16, full)  // 8: Show fullscreen EGA graphic.
  389.         goto END                         // 9: Go to line 12.
  390.         :TEXT                            // 10: Label for goto command.
  391.         ansi (ansi_pic.ans)              // 11: Show an ansi graphic.
  392.         :END                             // 12: Label for goto command
  393.  
  394.     This script uses two "if()" tests, three labels (":NEXT", ":TEXT", and
  395.     ":END"), and four "goto" commands.  Processing flows along one of three
  396.     possible paths depending on the user's hardware, with the result that in
  397.     just 12 simple lines we can ensure that if the user clicks on a certain
  398.     Graphic linkword he will actually see something.  The next chapter tells
  399.     about other conditions you can test, and gives a full explanation of how
  400.     to use each of the commands illustrated here.
  401.  
  402.     PARAMETERS
  403.     With the sole exception of "goto", all OCL commands must be followed by
  404.     parentheses, which usually enclose one or more parameters.  The number and
  405.     order of parameters are specific to each command, so before you use a
  406.     command for the first time you should read its entry in the Programming
  407.     Command Reference (Chapter 2).  In the following example, trymode() takes
  408.     a numeric parameter, if() takes a symbolic parameter (a keyword),
  409.     text() takes a string parameter, and quit() takes no parameter.
  410.  
  411.         trymode (16)                     // 1: Can we do EGA mode 16?
  412.         if (okay) goto END               // 2: If so, go to line 5.
  413.         text ("This book requires EGA graphics")  // 3: Text box.
  414.         quit ()                          // 4: Exit the Orpheus Reader.
  415.         :END                             // 5: Label for goto.
  416.  
  417.  
  418.  
  419.                                        7
  420.  
  421.  
  422.  
  423.  
  424.     (This script is one that would go in an Init off the Homecard, in a book
  425.     with a large number of EGA graphics at critical locations.  If the user
  426.     has an EGA-capable display he will proceed without even knowing that this
  427.     script was processed.  If he has a CGA or monochrome display, he will see
  428.     a note box with the message in it, and when he presses a key the
  429.     program will harmlessly exit.)
  430.  
  431.     VARIABLES
  432.     Variables are objects in memory that can hold values or other data.
  433.     Sometimes values are indicated with numbers, and sometimes they are
  434.     indicated symbolically using keywords.  The trymode() command sets an
  435.     internal variable to either "failed" or "okay" depending on whether the
  436.     user's display can or cannot switch to the specified video mode.  These
  437.     are symbolic values; in this case, the variable is unnamed.  Most
  438.     variables however do have names, and the set() command lets us assign
  439.     values to them, either with a number or with a keyword.
  440.  
  441.                 set (fadein=venetian, fadeout=venetian, delay=1)
  442.  
  443.     In this example, the first two variables are assigned the same symbolic
  444.     value, "venetian", which refers to a style of fading a graphic on or off
  445.     the screen.  The third variable is assigned a number representing the
  446.     delay factor for this effect; if delay=0 the fade is rather fast, while if
  447.     delay=3 the fade is rather slow.
  448.  
  449.  
  450.  Testing Commands & Scripts
  451.  
  452.         Most commands can be performed within OH.EXE as they would be in the
  453.     Orpheus Reader.  Those that cannot are at least checked for errors, and a
  454.     report given accordingly.  To test an individual command line, place the
  455.     cursor on that line (or on the line where it begins) and press <Alt-G>.  
  456.     This is an easy way to see if you are specifying the right video mode for 
  457.     a graphic() command, or to hear a performance of a music string.  In the 
  458.     case of a graphic() or ansi() command, once the image is displayed you 
  459.     need only press a key to return to editing.
  460.  
  461.         To test a complete script -- the entire sequence of commands in a
  462.     programmable card -- press <Alt-C> while in that card.  This is the "Check
  463.     Card" command, which works quite differently when given from a normal text
  464.     card.  Additionally, if you use <Alt-C> from an Action or Init card and 
  465.     your script includes a command to display a graphic or ansi graphic, you
  466.     will notice that without a waitfor() command at the end your graphic 
  467.     merely flashes onscreen and then disappears as the Edit window returns.  
  468.     This is because, as I explained above, when the last command is processed 
  469.     in an Action or Init card control returns immediately to the parent card.
  470.  
  471.         In a Graphic card (which does NOT require a waitfor() line at the
  472.     end), pressing <Alt-C> gives you the additional ability to create
  473.     hotspots.  This is explained under the hotspot() entry in the next
  474.     chapter.
  475.  
  476.  
  477.  
  478.  
  479.                                        8
  480.  
  481.  
  482.  
  483.  
  484.   ---------------------------------------------------------------------------
  485.                   CHAPTER 2  -  PROGRAMMING COMMAND REFERENCE
  486.   ---------------------------------------------------------------------------
  487.  
  488.  
  489.  
  490.  Commands in this reference:  :[label]           Load
  491.                               Ansi               Lookfor
  492.                               Gbox               Netwk
  493.                               Goto               Play
  494.                               Graphic            Quit
  495.                               Gtext              Run
  496.                               Hide               Runbat
  497.                               Hotspot            Set
  498.                               If                 Text
  499.                               Jump               Trymode
  500.                               Jumplist           Waitfor
  501.  
  502.  
  503.  
  504.         This chapter provides extensive discussion of every command in the
  505.     Orpheus Command Language.  For a general introduction to programming in
  506.     Orpheus, see Chapter 1.
  507.  
  508.  
  509.  :[label]
  510.  
  511.         Lines beginning with ":" are considered label lines, with the word
  512.     immediately following being a label for use in flow control.  As in DOS
  513.     batch files, labels are used with the goto command to control the flow
  514.     of processing.  The following example checks for a monochrome display,
  515.     and if one is detected directs processing to the ":END" label, which in
  516.     this case is the end of the script.  If a mono display is not detected,
  517.     processing continues to the next lines, which display a graphic and then
  518.     wait for the user to press a key.
  519.  
  520.                 if (mono) goto END
  521.                 graphic(mypic.pcx, 5, full)
  522.                 waitfor()
  523.                 :END
  524.  
  525.     Labels can be whatever you wish, but to avoid confusion you should
  526.     avoid using commands or keywords belonging to Orpheus Command Language.
  527.     A label is a single word, or multiple words joined by hyphen or
  528.     underscore, such as "first-part" or "has_vga".  (By the way, in case
  529.     you are wondering:  the label ":END" has no special meaning to
  530.     Orpheus.  You could use ":grmpflstx" and it would have the same effect,
  531.     as long as your goto command was "goto grmpflstx".  Also, if you
  532.     were to place the label ":END" in the middle of the script that would
  533.     =NOT= make it the end of the script.)
  534.  
  535.  
  536.  
  537.  
  538.  
  539.                                        9
  540.  
  541.  
  542.  
  543.  
  544.  Ansi()
  545.  
  546.         Display a text file containing ANSI escape sequences for color
  547.     effects.  Takes one or two parameters, optionally a library specification
  548.     and necessarily the name of the file to display.
  549.  
  550.                 ansi(ansipic.ans)
  551.                 ansi(lib=mylib.fgi, ansipic.ans)
  552.  
  553.     Ansi files may be located in either of two locations, depending on whether
  554.     OH.EXE or the Orpheus Reader is looking for them.  OH.EXE looks first
  555.     in the current directory, the one containing the Homecard.  The Reader
  556.     looks first in whichever directory contains the rest of the book files
  557.     (normally the current directory unless specified on the command line).
  558.     If the ansi file is not found there, Orpheus then checks for an ORPHEUS
  559.     environment variable, and if one exists uses the directory specified
  560.     there.  (See Appendix C, "Using the ORPHEUS Environment Variable".)
  561.  
  562.         If a library file is used it must reside in the current directory, for
  563.     either program.  For information on creating and managing library files
  564.     with FGILIB.EXE, see Chapter 7 in MANUAL1.DOC.
  565.  
  566.  
  567.  Gbox()
  568.  
  569.         Draw a filled rectangle in the current graphic video mode.  Requires
  570.     that a graphic video mode be already in effect on the user's display,
  571.     either as the result of a graphic() call or by using set() with the "mode"
  572.     keyword.  Parameters:  optional use of the keyword "text", and 5 numeric
  573.     parameters to specify the color, coordinates, and size of the rectangle.
  574.     Gbox() cannot be used in text modes.
  575.  
  576.     COLOR
  577.     The first numeric parameter sets the color for the rectangle.  Check the
  578.     table of Modes & Resolutions for the number of colors available in each
  579.     video mode.  Since some PCX files reset the color palettes, you may get
  580.     different results using the same number in the same mode but in
  581.     association with different PCX files.
  582.  
  583.     COORDINATES
  584.     The second numerical parameter gives the column of the upper left corner
  585.     of the box, with 0 as the left edge of the screen.  The next parameter
  586.     gives the row of the upper left corner, with 0 as the top of the screen.
  587.     The next parameter gives the width of the box (from left to right), and
  588.     the last gives its height (from top to bottom).  The smallest number
  589.     permitted for the height and width is 1, which has the effect of drawing
  590.     a thin line.
  591.  
  592.     COORDINATE SYSTEMS - PIXELS OR CELLS
  593.     Coordinates may be given in either character cells or pixel counts.  As
  594.     shown in the table of Modes & Resolutions, mode 16 (for example) has a
  595.     resolution of 640x350, with 80x25 character cells.  In other words, the
  596.  
  597.  
  598.  
  599.                                        10
  600.  
  601.  
  602.  
  603.  
  604.     screen in mode 16 has 640 pixels across by 350 pixels down, or 80 standard
  605.     characters across by 25 standard characters down.  While counting in
  606.     pixels gives you more precision, in some situations you will find it more
  607.     convenient to count in character cells.  If you use the keyword "text" as
  608.     the first parameter, all coordinates are read as character cells.  If you
  609.     do NOT use the keyword "text", coordinates are read as pixel counts.
  610.  
  611.                 set(mode = 16)
  612.                 gbox(text, 14, 9, 3, 61, 20)
  613.                 gbox(text, 1, 12, 4, 55, 18)
  614.                 gbox(15, 99, 58, 427, 235)
  615.  
  616.     This example puts up an attractive white box framed with a narrow
  617.     blue border surrounded in turn by a wide yellow border.  In actuality
  618.     there are 3 boxes created, one on top of the other.  The first gbox()
  619.     command draws the large yellow box (color 14), using text coordinates.
  620.     The second gbox() command draws a smaller blue box (color 1) inside it,
  621.     again using text coordinates.  Notice that the upper left corner of the
  622.     yellow box is at column 9, row 3, while the upper left corner of the
  623.     blue box is at column 12, row 4 -- below and to the right.  Additionally,
  624.     while the yellow box is 61 columns wide and 20 rows deep, the blue box
  625.     is 55 columns wide and 18 rows deep, so it fits neatly inside.  For the
  626.     white box (color 15) we want finer control in order to ensure that only
  627.     a thin border from the blue box is left showing.  By NOT using the text
  628.     keyword we ensure that our coordinate parameters are read as pixels.  With
  629.     a little experimentation we can get the desired effect, just by trying
  630.     some approximate numbers, pressing Alt-C to check the results, and making
  631.     adjustments accordingly.  In this case the blue box is reduced to a border
  632.     of 2 or 3 pixels all around.
  633.  
  634.         By specifying a depth or width of 1 or 2 pixels, gbox() can also
  635.     be used to draw a horizontal or vertical line.  You can in fact build up
  636.     some very interesting displays, generally with better performance and
  637.     less disk-space than if you created them in a paint program and saved
  638.     them to a PCX file.  Note however that if you wish to use gbox() and
  639.     then call graphic() to combine an image with a design onscreen, you
  640.     must use the command "set(fadein = off, fadeout = off)" to prevent
  641.     Orpheus from erasing the screen before displaying the graphic.
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.                                       11
  660.  
  661.  
  662.  
  663.  
  664.  Goto
  665.  
  666.         Direct command processing to the label following the goto command.
  667.     Goto may be used in two circumstances:  on the same line as an if() test,
  668.     and on a line of its own.
  669.  
  670.                 trymode(18)
  671.                 if (failed) goto DO_ANSI
  672.                 graphic(big_pic.pcx, 18, full)
  673.                 goto END
  674.                 :DO_ANSI
  675.                 ansi(ansipic.ans)
  676.                 :END
  677.  
  678.     This example checks whether the user's display can switch to mode 18,
  679.     a VGA mode.  If it can't, the first goto directs the flow to the :DO_ANSI
  680.     label.  If it can, a graphic is displayed and then the second goto
  681.     directs the flow to the :END label.  Note that goto can direct the flow
  682.     to *any* label in the script, regardless of whether the line is above
  683.     or below the goto.
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.                                       12
  720.  
  721.  
  722.  
  723.  
  724.  Graphic()
  725.  
  726.         Display a graphic in one of the image file formats permitted in
  727.     Orpheus.  Parameters:  normally three for a full-screen graphic, otherwise
  728.     from three to five.  Unless a library is used, the first parameter is the
  729.     filename, the second is the video mode in which to display it.  If the
  730.     third parameter is the keyword "full", no further parameters are required.
  731.     If the third parameter is not "full", the third and fourth parameters give
  732.     the x-y coordinates (column-row in pixels) of the origin of the image,
  733.     while the fifth (required for SPR/PPR files only) gives the image width in
  734.     pixels.  When a library used, place the library specification first,
  735.     followed by the other paramaters in the normal order.
  736.  
  737.         In the following examples, an identical full-screen graphic is shown
  738.     in both PCX and SPR image file formats, using mode 13, which has a
  739.     resolution of 320 columns by 200 rows:
  740.  
  741.                 graphic(example1.pcx, 13, full)
  742.                 graphic(example2.pcx, 13, 0, 0)
  743.                 graphic(example3.spr, 13, full)
  744.                 graphic(example4.spr, 13, 0, 199, 320)
  745.  
  746.     Here are the first and last examples with the images stored in a library.
  747.     (To learn about creating and maintaining libraries with FGILIB.EXE, see
  748.     Chapter 7 in MANUAL1.DOC.)
  749.  
  750.                 graphic(lib=stuff.fgi, example1.pcx, 13, full)
  751.                 graphic(lib=stuff.fgi, example4.spr, 13, 0, 199, 320)
  752.  
  753.  
  754.     PCX FILES
  755.  
  756.         With PCX files an image is considered to originate at the upper left
  757.     corner.  With a full-screen graphic this would be column 0, row 0, as
  758.     shown in example 2 above.  We do not require the image width of a PCX
  759.     file, so there is no fifth parameter.
  760.  
  761.         Let's suppose we have a PCX graphic that is half the size of the
  762.     screen in each dimension.  Since our examples use mode 13 with a
  763.     resolution of 320 x 200, we'll say that our image is 160 pixels across
  764.     by 100 pixels down.  To center this image we would use the following:
  765.  
  766.                 graphic(example5.pcx, 79, 49)
  767.  
  768.     Where did these numbers come from?  We take the horizontal resolution,
  769.     subtract the width of the image, divide by two, then subtract one:
  770.     320-160=160; 160/2=80; 80-1=79.  We subtract 1 because screen coordinates
  771.     are always counted from 0; thus the leftmost pixel coordinate is 0 and
  772.     the rightmost pixel coordinate (in mode 13) is 319.  The same procedure
  773.     works for the vertical dimension.  Take the vertical resolution, subtract
  774.     the height of the image, divide by two, subtract one:  200-100=100;
  775.     100/2=50; 50-1=49.
  776.  
  777.  
  778.  
  779.                                       13
  780.  
  781.  
  782.  
  783.  
  784.         You won't always know the dimensions of an image nor where you want to
  785.     show it onscreen.  The best way to proceed is to try out different numbers
  786.     and use the <Alt-G> Go Command to view the results.
  787.  
  788.  
  789.     SPR/PPR FILES
  790.  
  791.         SPR files are captured using the SNAPSHOT utility, which comes with
  792.     the registered version of Orpheus.  PPR files are generated from SPR
  793.     files using a Fastgraph utility that compresses them.  With SPR and PPR
  794.     files, an image is considered to originate at the LOWER left corner,
  795.     whereas with PCX files it originates at the upper left.  In addition,
  796.     SPR/PPR files require that we give the image width.  This accounts for
  797.     the numbers in example 4:
  798.  
  799.                 graphic(example4.spr, 13, 0, 199, 320)
  800.  
  801.     Since this a full-screen graphic and the resolution is 320 x 200, the
  802.     horizontal component of the lower left corner is pixel column 0, but the
  803.     vertical component is 199 -- 1 less than the vertical resolution.  The
  804.     width of the image is of course 320 pixels.
  805.  
  806.         Let's suppose we have an SPR graphic that is half the size of the
  807.     screen in both dimensions, in other words 160 pixels across by 100 pixels
  808.     down.  We'll center it just like we did with the half-size PCX graphic
  809.     above.  To calculate the column coordinate we follow the same procedure:
  810.     horizontal resolution - width, divided by 2, minus 1, or: 320-160=160;
  811.     160/2=80; 80-1=79.  For the row coordinate however we must proceed
  812.     differently because we're calculating the lower left corner rather than
  813.     the upper left corner.  The procedure is:  vertical resolution - height,
  814.     divided by 2, subtract that from the vertical resolution, minus 1, or:
  815.     200-100=100; 100/2=50; 200-50=150; 150-1=149.  Our command to center the
  816.     image would thus be:
  817.  
  818.                 graphic(example6.spr, 13, 79, 149, 160)
  819.  
  820.         Unless you stick to a single file type and a single video mode, you
  821.     will find it useful to consult a chart of the video modes and their
  822.     screen resolutions.  You can find such a chart in online help, under
  823.     Programming Hypertext->Graphics->Modes & Resolutions.
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.                                       14
  840.  
  841.  
  842.  
  843.  
  844.  Gtext()
  845.  
  846.         Display text in the current graphic video mode.  Requires that a
  847.     graphic video mode be already in effect on the user's display, either as
  848.     the result of a graphic() call or by using set() with the "mode" keyword.
  849.     Parameters:  optional use of the keyword "text", 3 numeric parameters
  850.     giving the foreground color of the text and the coordinates at which to
  851.     display the first character, and one or more text strings enclosed in
  852.     quotation marks.
  853.  
  854.     FONTS
  855.     Bitmapped fonts are not yet available (but soon will be); in their place
  856.     Orpheus displays the standard "system" characters that are built into
  857.     ROM.
  858.  
  859.     COLOR
  860.     The first numerical parameter gives the foreground color in which text
  861.     will be displayed.  For the most readable text you will often want to
  862.     create a consistent background color by preceding the gtext() call with
  863.     one to gbox().  Check the table of Modes & Resolutions for the number of
  864.     colors available in each video mode.  Since some PCX files reset the color
  865.     palettes, you may get different results if you display text on a PCX
  866.     graphic.
  867.  
  868.     COORDINATES
  869.     The second numerical parameter gives the column at which the first
  870.     character of the first string will be displayed, with 0 as the left edge
  871.     of the screen.  The next parameter gives the row, with 0 as the top of the
  872.     screen.  Multiple strings are left-justified with the first character
  873.     of the first string, and are displayed further down the screen according
  874.     to the calculated height of a character cell.
  875.  
  876.     COORDINATE SYSTEMS - PIXELS OR CELLS
  877.     Coordinates may be given in either character cells or pixel counts.  As
  878.     shown in the table of Modes & Resolutions, mode 16 for example has a
  879.     resolution of 640x350, with 80x25 character cells.  In other words, the
  880.     screen in mode 16 has 640 pixels across by 350 pixels down, or 80 standard
  881.     characters across by 25 standard characters down.  While counting in
  882.     pixels gives you far more precision, in some situations you will find it
  883.     more convenient to count in character cells.  If you use the keyword
  884.     "text" as the first parameter, all coordinates will be read as character
  885.     cells.  If you do NOT use the keyword "text", coordinates will be read
  886.     as pixel counts.
  887.  
  888.         In the current version of Orpheus, since only ROM characters are
  889.     supported (and they can ONLY be displayed along cell coordinates),
  890.     even if you give pixel coordinates they will be converted to cell
  891.     coordinates.  When bit-mapped fonts are available you will be able
  892.     to use pixel coordinates for finer positioning.
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.                                       15
  900.  
  901.  
  902.  
  903.  
  904.         The following illustration continues from the example begun for
  905.     gbox().
  906.  
  907.                 set(fadein = off, fadeout = off, mode = 16)
  908.                 gbox(text, 14, 9, 3, 61, 20)        // yellow box
  909.                 gbox(text, 1, 12, 4, 55, 18)        // blue box inside it
  910.                 gbox(15, 99, 58, 427, 234)          // white box inside it
  911.                 gbox(11, 99, 287, 427, 6)           // bright cyan lines
  912.                 gbox(11, 117, 278, 391, 5)
  913.                 gbox(11, 135, 271, 355, 4)
  914.                 gbox(11, 153, 266, 319, 3)
  915.                 gbox(11, 170, 262, 285, 2)
  916.                 gbox(11, 185, 259, 255, 1)
  917.                 gtext(text, 5, 28, 8, "Greetings", " ", "from", " ",
  918.                     "Rod Willmot and the animals", " ",
  919.                     "at Hyperion Softword!")
  920.                 gtext(text, 5, 32, 17, "1-819-566-6296")
  921.                 set(fadeout = normal)
  922.  
  923.     This example begins by turning off fades in case we decide to add an
  924.     on-disk image using graphic().  It then sets the video mode in preparation
  925.     for the calls to gbox() and gtext().  The first three gbox() commands
  926.     are taken from the example given above to illustrated gbox(); they set
  927.     up a large white box in the middle of the screen, nicely framed by
  928.     a thin blue border and a wider yellow border.  The next 6 commands
  929.     draw a series of lines of decreasing thickness, from the bottom of the
  930.     white box toward the center; the effect is of receding perspective.
  931.     Finally we come to the gtext() commands, both of which use the "text"
  932.     keyword to let us use the coarser but easier cell coordinates.  The
  933.     color used is 5, magenta.  The first set of strings starts at column
  934.     28, row 5; blank lines are created by entering a string as " ", a
  935.     single space.  Each additional string within the same command is
  936.     left-justified with the first string, which begins exactly at the
  937.     specified coordinates.
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.                                       16
  960.  
  961.  
  962.  
  963.  
  964.  Hide()
  965.  
  966.         The hide() command is for use in an Init card when you wish to conceal
  967.     links in its parent card.  The command can be given either with no
  968.     parameters or with an indeterminate sequence of numeric parameters.
  969.  
  970.                 hide()
  971.                 hide(0, 2, 5)
  972.  
  973.     In the first example, ALL links in the parent card are concealed:  if it
  974.     has a More link this fact will not be known by the reader, and if it has
  975.     any linkwords they will look like ordinary text -- and clicking on them
  976.     will have no effect.  In the second example, the More link and the second
  977.     and fifth linkwords are concealed.  To sum up:  using hide() with no
  978.     parameters hides all links in the parent.  Using "0" as a parameter hides
  979.     the More link; other numbers hide the equivalent linkwords as numbered
  980.     sequentially from top to bottom and from left to right down the screen.
  981.  
  982.         The hide() command could be used in a network environment where not
  983.     all readers should have access to branches with sensitive material.  In
  984.     a work with illustrations in VGA color, it could be used to prevent
  985.     users with mono displays from experiencing the frustration of clicking
  986.     on Graphic links and getting no response.  Hide() will also add to the
  987.     repertoire of effects when the Orpheus Command Language extends to
  988.     interactive dialogs and author-created variables.
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.                                       17
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  Hotspot()
  1025.  
  1026.         The hotspot() command defines an area of a graphic or ansi screen that
  1027.     is linked to another graphic or text card, much like a linkword in a text
  1028.     card.  Hotspots may only be created in Graphic cards, where they can be
  1029.     associated either with true graphics (displayed in a graphic video mode)
  1030.     or with ansi graphics (displayed in text mode).  The hotspot() command
  1031.     cannot be used in Action or Init cards.  Hotspot data created for a true
  1032.     graphic is NOT compatible with data created for an ansi graphic.
  1033.  
  1034.         There are two parameters:  a linkword, and a coded data string
  1035.     enclosed in quotation marks.  The first character of the string is "0"
  1036.     if the hotspot is for a true graphic, "1" if it is for an ansi graphic.
  1037.  
  1038.                 hotspot( linkword , "0NLGOKLPKWQKXRKVSKUT\C")
  1039.  
  1040.         The hotspot() command, including the coded data string, is entered
  1041.     by Orpheus rather than being typed in by you.  The procedure is as
  1042.     follows:  assuming you are in a Graphic card with a valid graphic() or
  1043.     ansi() command, place the cursor on an empty line.  Press <Alt-C> to
  1044.     perform the entire script, even if it consists only of one graphic() or
  1045.     ansi() command.  Orpheus displays the graphic and waits for your input.
  1046.     Press <H> to indicate that you wish to make a hotspot; Orpheus will beep
  1047.     twice in acknowledgement.  You can now draw the hotspot by pressing or
  1048.     clicking the left mouse button.  To erase an area, press or click the
  1049.     right mouse button.  (Neither drawing nor erasing actually alters your
  1050.     original hotspot.)  To cancel a partially-drawn hotspot and refresh the
  1051.     screen, press <Esc>.  To signal that you have finished the hotspot, press
  1052.     <Enter>.
  1053.  
  1054.         When you press <Enter> to finish a hotspot, Orpheus returns you to
  1055.     the Graphic card where you will now see the new hotspot() command,
  1056.     something like this (the # will be 0 for a true graphic, 1 for an ansi
  1057.     screen):
  1058.  
  1059.                 hotspot( linkword , "#.......data string.........")
  1060.  
  1061.     One final step is required to make the command complete:  using the word
  1062.     "linkword" or a word of your own to replace it, open a link on that word
  1063.     (the first parameter in the hotspot() command) to create a new linked 
  1064.     card.  Three link types are permitted:  Doors, Graphics, and Crosslinks.
  1065.     Until this step is done the command is not considered complete, nor will
  1066.     Orpheus carry out an <Alt-C> command in that card.  When it is complete,
  1067.     press <Alt-C> and move the mouse pointer over the area where you drew
  1068.     the hotspot; notice that the mouse pointer changes shape.
  1069.  
  1070.         A hotspot can be small and simple, or large and complex; it can even
  1071.     be scattered in several unconnected locations.  The size and complexity
  1072.     of the hotspot determines the length of the data string forming the
  1073.     second parameter.  If the data string is too long to fit on one line,
  1074.     Orpheus will carry it over onto one or more subsequent lines.  As in all
  1075.     cases where data is carried over, each additional line must be padded
  1076.  
  1077.  
  1078.  
  1079.                                       18
  1080.  
  1081.  
  1082.  
  1083.  
  1084.     with one or more leading spaces.  (Orpheus does this automatically, but
  1085.     you should know the rule in case you rearrange things manually.)
  1086.  
  1087.         A graphic may have as many hotspots as you can define within the
  1088.     50-line workspace of a card.  Additionally, just as you can use flow
  1089.     control to provide alternate graphics for different hardware, you can
  1090.     provide a different set of hotspots for each graphic -- or use the same
  1091.     hotspots for all of them.  In the first example below, we put up either
  1092.     a VGA or an EGA graphic, using modes that have a resolution of 320 x 200.
  1093.     We then install 2 hotspots which are applicable to both.
  1094.  
  1095.                 trymode(19)
  1096.                 if (failed) goto HAS_EGA
  1097.                 graphic(vga_pic.pcx, 19, full)
  1098.                 goto ADD_HOTSPOTS
  1099.                 :HAS_EGA
  1100.                 graphic(ega_pic.pcx, 13, full)
  1101.                 :ADD_HOTSPOTS
  1102.                 hotspot( link1 , "0.........data string.........")
  1103.                 hotspot( link2 , "0.........data string.........")
  1104.  
  1105.         In the next example we will again use a VGA and an EGA graphic, but
  1106.     one will use a resolution of 320 x 400 (mode 23), while the other will
  1107.     use a resolution of 640 x 350 (mode 16).  We'll suppose that the pictures
  1108.     are sufficiently different that each requires its own set of hotspots.
  1109.     (For safety's sake, you should never try to use a hotspot in two different
  1110.     video modes.)  In order to create the hotspots we must of course press
  1111.     <Alt-C> to perform the entire script; this means that at some point we
  1112.     must comment out all command lines that do not pertain to the graphic for
  1113.     which we wish to create a hotspot.
  1114.  
  1115.                 /trymode(23)
  1116.                 /if (failed) goto HAS_EGA
  1117.                 /graphic(vga_pic.pcx, 23, full)
  1118.                 /hotspot( link1 , "0.........data string.........")
  1119.                 /hotspot( link2 , "0.........data string.........")
  1120.                 /goto END
  1121.                 /:HAS_EGA
  1122.                 graphic(ega_pic.pcx, 16, full)
  1123.                 hotspot( link1 , "0.........data string.........")
  1124.                 :END
  1125.  
  1126.     In this example we have already completed our work for the VGA graphic,
  1127.     and have temporarily commented out that section of the script using
  1128.     a "/" character at the beginning of each line.  This ensures that <Alt-C>
  1129.     will only display the EGA graphic.  The example shows one hotspot
  1130.     completed, with an empty line left where we can create another. When work
  1131.     is completed for both graphics we simply remove the comment characters to
  1132.     return the commented-out lines to the script.  To provide ansi graphics
  1133.     for users with neither EGA nor VGA, we would comment out all of the
  1134.     commands that use graphic modes, add our ansi() command to display an ansi
  1135.     screen, then proceed as above to create hotspots in the ansi screen.
  1136.  
  1137.  
  1138.  
  1139.                                       19
  1140.  
  1141.  
  1142.  
  1143.  
  1144.     MULTIPLE COPIES OF LINKWORDS
  1145.  
  1146.         If you use multiple sets of hotspots for alternate graphics, you will
  1147.     probably want each set of hotspots to use the same links.  Normally in
  1148.     Orpheus it is not permitted to have more than one copy of a linkword; in
  1149.     other words, you can copy the text as often as you like, but only one
  1150.     instance of it can bear the embedded linking codes.  This rule is ignored
  1151.     for Graphic cards in order to allow multiple sets of hotspots to share
  1152.     links.  Note that to delete a linkword copy you must still use the
  1153.     Unlink command on the Link Menu; if a copy is detected, the unlinking
  1154.     procedure will only remove the linking codes from the linkword at the
  1155.     cursor, and will not affect the linked card.
  1156.  
  1157.  
  1158.     HOTSPOTS AND THE KEYBOARD 
  1159.  
  1160.         In the Orpheus Reader, the mouse interface for accessing hotspots is 
  1161.     similar to that in OH.EXE:  wherever the pointer changes shape it is over 
  1162.     a hotspot.  When the mouse is disabled or absent, however, a special 
  1163.     keyboard interface comes into play that handles hotspots in a manner 
  1164.     similar to the handling of linkwords.  That is, much as the up/down arrow 
  1165.     keys move the selection bar from linkword to linkword, they move the 
  1166.     keyboard pointer from hotspot to hotspot; if there are no linkwords there 
  1167.     is no selection bar, and if there are no hotspots there is no keyboard 
  1168.     pointer.  (This rule does NOT apply to the mouse pointer.) 
  1169.  
  1170.         If many of your users will be dependent on the keyboard interface,
  1171.     you may want to consider the following information when drawing hotspots. 
  1172.     The keyboard pointer is always displayed in the uppermost, leftmost 
  1173.     location in a hotspot.  This means that in a T-shaped hotspot it would 
  1174.     appear at the top left, while in an O-shaped hotspot it would appear at 
  1175.     the top center.  In true graphics this can lead to effects that are either 
  1176.     peculiar or perfectly acceptable depending on how the hotspots are shaped.  
  1177.     In ansi graphics, on the other hand, IF your hotspots are formed in the 
  1178.     manner of linkwords, it can be a highly effective feature.  An example 
  1179.     would be an ansi screen serving as a colorful menu, with each hotspot 
  1180.     underlying a word or phrase on a single line.  Note that on ansi screens 
  1181.     the keyboard pointer is a bright (normally blinking) right arrow.  For the 
  1182.     best effect, draw your ansi hotspots so that the first character is a 
  1183.     space rather than a letter; this way, the arrow will appear to the left of 
  1184.     the hotspot word instead of overwriting its first letter. 
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.                                       20
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  If()
  1205.  
  1206.         The if() command lets you test a condition, and either direct control
  1207.     to a specified label if the condition is true, or fall through to the
  1208.     next line if the condition is false.  If() commands must be followed on
  1209.     the same line by a goto with a label.
  1210.  
  1211.                 if (okay) goto ALRIGHT
  1212.  
  1213.     Only one parameter is permitted, from the following list:
  1214.  
  1215.                 okay
  1216.                 failed
  1217.                 mono
  1218.                 color
  1219.  
  1220.     "Okay" and "failed" test an internal flag that is set by the trymode()
  1221.     command (and in future by others).  "Mono" tests whether the user has a
  1222.     monochrome display running in mode 7.  (A monochrome display refers to one
  1223.     on which besides normal and blinking text we can use underline, bright,
  1224.     and reverse video, but not shades.)  "Color" tests whether the user has a
  1225.     true color display, as distinct from a 1-color display capable of showing
  1226.     16 shades.  Other tests will be added in future.
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.                                       21
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  Jump()
  1265.  
  1266.         The jump() command tells the Orpheus Reader to navigate directly to
  1267.     another card, which may be determined at random, by number, or by
  1268.     circumstance.  Jumping automatically terminates processing of the current
  1269.     script; in other words, you cannot jump to another card and then carry
  1270.     on to the next line of the script with the jump() command.  Jump commands
  1271.     cannot be simulated in OH.EXE.
  1272.  
  1273.         Up to two parameters are permitted, of which the first must be from
  1274.     the following list, while the second (if any) must be a card number as
  1275.     explained on the next page.
  1276.  
  1277.                 [card number]
  1278.                 home
  1279.                 random
  1280.                 retrace
  1281.  
  1282.     To force a jump to a particular card, navigate to that card in another
  1283.     window and open the File Menu.  To the right of the "Save As" command
  1284.     you will see the hilited number of that card.  Use this number as the
  1285.     jump parameter:
  1286.  
  1287.                 jump(112)       // if the card's number is 112
  1288.  
  1289.     Such a command could theoretically be given in any programmable card, but
  1290.     the logical place would be in an Action card, as a replacement for a
  1291.     Crosslink.  Whereas a Crosslink can have only one destination, an Action
  1292.     card can contain a script that tests various things and conditionally
  1293.     jumps to a choice of multiple destinations.  (In future releases the
  1294.     number of conditions to test will increase to give you considerable power
  1295.     and flexibility in this regard.)  Note that you should NEVER force a jump
  1296.     to either an Init or an Action card.
  1297.  
  1298.         To force a jump to Designated Home (or if none, the Homecard) use:
  1299.  
  1300.                 jump(home)
  1301.  
  1302.     Random jumps are permitted if you have previously initialized random
  1303.     jumps by using a jumplist() command together with the "random" parameter.
  1304.     To force a jump to a card selected at random, use:
  1305.  
  1306.                 jump(random)
  1307.  
  1308.     Finally, you can force a jump to the PREVIOUS card the reader visited:
  1309.  
  1310.                 jump(retrace)
  1311.  
  1312.     As of version 1.60 this last capability is probably unnecessary, since the
  1313.     normal method of backtracking (in the Reader) is simply to retrace with
  1314.     either the <Left Arrow> or the right mouse button.
  1315.  
  1316.  
  1317.  
  1318.  
  1319.                                       22
  1320.  
  1321.  
  1322.  
  1323.  
  1324.         The optional second parameter is the number of the card from which
  1325.     you wish to "pretend" to have jumped.  Suppose for example that you have
  1326.     a card that serves as a menu or table of contents, and that at the end
  1327.     of each branch leading down from it you have a "Return to Menu" or some
  1328.     such linkword, directing the reader back to the top.  Your jump() command
  1329.     might use "home" or the number of the menu card.  Now, if the reader were
  1330.     to return to the menu manually through a series of PgUp moves, on his
  1331.     arrival at the menu card the linkword through which he originally descended
  1332.     would be hilited, making it easy to select a different item from the menu.
  1333.     But by using the jump() command you skip over the intervening cards, so
  1334.     that Orpheus keeps hiliting the first linkword on the menu.  Here's where
  1335.     the second parameter comes in handy.  At each location where you wish to
  1336.     use jump(), go to the menu card (using a different Edit window) and find
  1337.     the linkword leading to that location.  Go through that linkword and open
  1338.     the File Menu to find the card's number, and use that as your second
  1339.     parameter.  The effect will be the same as if the reader had come from the
  1340.     card directly under the linkword instead of one far below.
  1341.  
  1342.                 jump(10, 12)
  1343.  
  1344.     This example jumps to card 10, and pretends to have done so from card 12.
  1345.     If card 10 has a linkword connected to card 12, that linkword will be
  1346.     hilited as if the reader had just come from there.
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.                                       23
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  Jumplist()
  1385.  
  1386.         The jumplist() command sets up a list of cards to which the Orpheus
  1387.     Reader can or cannot jump when given an appropriate jump() command as
  1388.     described in the previous section.  Currently such a list can only be
  1389.     set up for the purpose of making random jumps; a future release will add
  1390.     the ability to set up a list for a guided tour.
  1391.  
  1392.         Two parameters are required, of which the first must for now be the
  1393.     keyword "random".  The second parameter may be "all", or either "include"
  1394.     or "exclude" followed by a list of card numbers represented by their file
  1395.     extensions.  The example below initializes a random jumplist and tells
  1396.     the Orpheus Reader that choices may be made from all of the cards in the
  1397.     book.  Note that this automatically excludes Init and Action cards.
  1398.  
  1399.                 jumplist(random, all)
  1400.  
  1401.     The next example initializes a random jumplist that includes only the
  1402.     cards listed by number.  When the Reader encounters a jump(random)
  1403.     command, it will select at random from that list.  Note that the list must
  1404.     not include Init or Action cards.  (To find out the number of a particular
  1405.     card, open the File Menu while in that card and note the hilited number
  1406.     to the right of the "Save As" prompt.)
  1407.  
  1408.                 jumplist(random, include, 12, 43, 159,.........)
  1409.  
  1410.     The final example initializes a random jumplist that includes all cards
  1411.     EXCEPT those specified in the list.  When the Reader encounters a
  1412.     jump(random) command, it will select at random from all cards, rejecting
  1413.     any choice that is on the exclude list; it will also reject any choice
  1414.     that is an Init or Action card.
  1415.  
  1416.                 jumplist(random, exclude, 12, 76, 384,.........)
  1417.  
  1418.         The list of card numbers must be constructed as shown, with each
  1419.     number separated from the others by a comma; spaces are optional.
  1420.     If the list carries over to one or more additional lines, each broken line
  1421.     must end with a comma, and each additional line must begin with at least
  1422.     one leading space.  The list must be terminated by a closing parenthesis.
  1423.  
  1424.         The normal place to declare a jumplist is in an Init card.  You can
  1425.     build the list either manually or automatically.  Both procedures require
  1426.     you to start with the Init card with the uncompleted jumplist() command
  1427.     in one window, and then switch to another window to navigate to the
  1428.     various cards that you intend to add to the jumplist.  To do this
  1429.     manually, open the File Menu when in such a card, get the card number
  1430.     as shown to the right of the "Save As..." command, then switch to the
  1431.     window with your Init card and add the number to the list.
  1432.  
  1433.         The semi-automatic way to accomplish the same thing requires a couple
  1434.     of setup steps but is then much faster.  First, leave the Init card with
  1435.     the uncompleted jumplist() command in one window, making sure that the
  1436.  
  1437.  
  1438.  
  1439.                                       24
  1440.  
  1441.  
  1442.  
  1443.  
  1444.     cursor is at the end of the line and in the position where the next
  1445.     card number is to be inserted.  The example below shows this with an
  1446.     underscore representing the position of the cursor:
  1447.  
  1448.                 jumplist(random, include, _
  1449.  
  1450.     Open the Tools Menu and select "Jumplist", then select "List Window" and
  1451.     tell Orpheus which window contains the Init card with the jumplist.  Now
  1452.     switch to another window and navigate to whichever cards you wish to add
  1453.     to the list.  At each such card, press <Alt-F3>.  If the procedure is
  1454.     successful Orpheus will post a message saying "Added to list".  Let us
  1455.     suppose that the first card you add is numbered "15".  The example
  1456.     below shows the growing jumplist with the underscore representing the
  1457.     new position of the cursor, which Orpheus has advanced in preparation
  1458.     to receive the next number.  Of course you will only see this if you
  1459.     switch back to the window with the Init card.
  1460.  
  1461.                 jumplist(random, include, 15,_
  1462.  
  1463.     Remember that to terminate the list and make the command complete, you
  1464.     must remove the last comma if there is one, and add a closing parenthesis
  1465.     as in the final example.
  1466.  
  1467.                 jumplist(random, include, 15,17,23,32,58,2,76)
  1468.  
  1469.  
  1470.  
  1471.  
  1472.  
  1473.  
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.                                       25
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  Load()
  1505.  
  1506.         The load() command is intended for use with "external objects", such
  1507.     as uncompiled text files, forms, or other hypertext books.  It takes at
  1508.     least two parameters:  a keyword to define the kind of object you wish to
  1509.     load, and a filename.  Use the "new" keyword to change to a different
  1510.     compiled book; use "text" to load an external text file in the Reader's
  1511.     version of the FileView window; use "form" to load a form file in the
  1512.     Formfill window.  Form files may also be stored in libaries, using the
  1513.     FGILIB.EXE utility described in Chapter 7 of MANUAL1.DOC.
  1514.  
  1515.     NEW
  1516.     Load(new, ...) provides a way of jumping to other hypertext books created
  1517.     with Orpheus.  To use it, open an Action link and give the load() command
  1518.     together with the "new" keyword and the name of the book to load:
  1519.  
  1520.                 load(new, filename.htx)
  1521.  
  1522.     The keyword "new" tells Orpheus that you want to load a new book.  For
  1523.     a well-behaved application you might want to ensure that the user actually
  1524.     has the desired book files.  You can do this with the lookfor() command,
  1525.     described below.  When a load() command is successful, it performs certain
  1526.     cleanup functions for whatever the user has just been reading, such as
  1527.     saving bookmarks and notes.  Then it fires up the new book, just as if the
  1528.     user had loaded it manually.  The transition is swift and seamless,
  1529.     especially if both books were designed by the same person in the same
  1530.     style.  Though currently an Orpheus book is limited to 32,000 links,
  1531.     with the load() command your work is infinitely extensible:  any book
  1532.     can contain links to hundreds or thousands of other books.
  1533.  
  1534.         As of version 1.60, load() can also receive the number of a card:
  1535.  
  1536.                 load(new, filename.htx, 199)
  1537.  
  1538.     This command would not only load the new book but would immediately go
  1539.     to the specified card, provided it is either a text card or a graphic
  1540.     card (associated with a Graphic link).  Note that the number of a card
  1541.     in compiled form is NOT the same as its number in uncompiled form.  To
  1542.     get a list of number equivalencies, open the Project List and select
  1543.     "List Compiled Numbers".  When you compile, the .DOC file produced for
  1544.     that project will include a list of number pairs in the form xxx=yyy,
  1545.     where xxx is a card's number before compiling, and yyy is the number
  1546.     with which you can access it in the Reader.
  1547.  
  1548.         Note that when load() is successful, the line with that command
  1549.     becomes in effect the last line of the script.  In other words, you
  1550.     cannot follow it with a play() command, for example, and expect music
  1551.     to play while the user starts reading the new book.
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.                                       26
  1560.  
  1561.  
  1562.  
  1563.  
  1564.     TEXT
  1565.     Load(text, ...) tells the Orpheus Reader to load an external text file for 
  1566.     viewing in the Reader's version of FileView.  To use it, open an Action 
  1567.     link and give the load() command together with the "text" keyword and the 
  1568.     name of the file to load.  Notice that in the second example, the filespec 
  1569.     include a drive letter and path; you should only do this if your work will 
  1570.     be used on systems known to you. 
  1571.  
  1572.                 load(text, filename.doc)
  1573.                 load(text, c:\biz\newinfo.txt)
  1574.  
  1575.     Load() has the additional capability of placing the reader at a specific
  1576.     line in a file.  The following command would load MANUAL.DOC with line
  1577.     235 at the top of the viewing window:
  1578.  
  1579.                 load(text, manual.doc, 235)
  1580.  
  1581.     You can also specify a label instead of a number.  The next command would
  1582.     load the same file but with the line containing the label {New Listings}
  1583.     at the top of the window.  Note that in the script command the text of
  1584.     the label must be in quotation marks, while in the *file* it must be
  1585.     in curly braces, like so: {New Listings}.
  1586.  
  1587.                 load(text, manual.doc, "New Listings")
  1588.  
  1589.     FileView will not display the curly braces, and in fact the entire label
  1590.     can be hidden by placing it at the end of the line and inserting enough
  1591.     spaces to push it offscreen to the right.  (FileView does not wrap lines
  1592.     that are longer than the screen.)
  1593.  
  1594.         Why would you want to link to an uncompiled text file?  It can give 
  1595.     your users convenient access to files that are frequently updated.  Users 
  1596.     can edit such files themselves, using any editor or word processor capable 
  1597.     of saving files as plain text.  They can even create additional links to 
  1598.     their own files using the simple hypertext capabilities of FileView, as 
  1599.     described in online help and below. 
  1600.  
  1601.         Provided the word "ORPHEUS" is found anywhere on the first line of a
  1602.     file, FileView will interpret certain characters in the file as being
  1603.     codes for embedded hypertext links.  These characters are:
  1604.     <angle brackets> around linkwords, [square brackets] around jump data,
  1605.     and {curly braces} around labels.  None of these characters will be
  1606.     displayed, nor will anything in square brackets.  The following examples
  1607.     show what you can do:
  1608.  
  1609.         <linkword>[#201]                 - jump to line 201
  1610.         <linkword>[:Hotels]              - jump to {Hotels} below
  1611.         <linkword>[:^Hotels]             - jump to {Hotels} ABOVE
  1612.         <linkword>[manual.doc]           - jump to MANUAL.DOC file
  1613.         <linkword>[manual.doc #201]      - jump to file, line 201
  1614.         <linkword>[manual.doc :Hotels]   - jump to file, line with {Hotels}
  1615.         {Hotels}                         - a label
  1616.  
  1617.  
  1618.  
  1619.                                       27
  1620.  
  1621.  
  1622.  
  1623.  
  1624.     FORM 
  1625.     Load(form, ...) tells the Orpheus Reader to load an external form file
  1626.     in the Formfill window.  This is a variation of the FileView window
  1627.     that is unique to the Reader:  it allows the user to fill out an order
  1628.     form or answer a questionnaire right onscreen, then print it out to the
  1629.     printer or to a disk file.  The original form is unchanged during this 
  1630.     process.  Forms may also be stored in library files, as described at the 
  1631.     end of this section. 
  1632.  
  1633.         Like the external text files used with load(text, ...), form files can 
  1634.     be created with any text editor or word processor capable of saving files 
  1635.     as plain text.  They can be any length and can contain any number of entry 
  1636.     fields.  Form files use the same brackets and braces as do hypertexted 
  1637.     text files, but for different purposes:  {curly braces} are used to create
  1638.     a hilite ; <angle brackets> are used to denote an entry field; and 
  1639.     [square brackets] are reserved for future use.  Finally, the _underscore_ 
  1640.     character should be used to fill each empty field. 
  1641.  
  1642.         To create a form file, start by setting it up the way you want it to
  1643.     look onscreen.  (Remember, you must use an external editor or word 
  1644.     processor for this, not OH.EXE.)  Draw your entry fields using 
  1645.     underscores, like this: 
  1646.  
  1647.           Name: ___________________________________________________
  1648.        Address: ___________________________________________________
  1649.                 ___________________________________________________
  1650.                 State: _____  Zip: ______  Country: _______________
  1651.  
  1652.     Next, insert angle brackets around each entry field, like so:
  1653.  
  1654.           Name: <___________________________________________________>
  1655.        Address: <___________________________________________________>
  1656.                 <___________________________________________________>
  1657.                 State: <_____>  Zip: <______>  Country: <_______________>
  1658.  
  1659.     The final step (this is optional) is to insert curly braces around any
  1660.     text you wish to hilite:
  1661.                   
  1662.           {Name}: <___________________________________________________>
  1663.        {Address}: <___________________________________________________>
  1664.                 <___________________________________________________>
  1665.                 State: <_____>  Zip: <______>  Country: <_______________>
  1666.  
  1667.     What would this look like onscreen?  First, you wouldn't see the brackets
  1668.     and braces.  The words "Name" and "Address" would be hilited (in the
  1669.     color of Note links).  And the empty fields would be displayed as strings
  1670.     of dots -- NOT as strings of underscores.  The user can move from field
  1671.     to field using the Up/Down arrow keys, the Tab/Shift-Tab keys, or by
  1672.     pressing Enter.  The same keys also scroll the form if it is longer than 
  1673.     the screen.  After a user fills in a field and moves on to another, the 
  1674.     data he entered in that field has the color of a Door link. 
  1675.  
  1676.  
  1677.    
  1678.  
  1679.                                       28
  1680.  
  1681.  
  1682.  
  1683.  
  1684.         If you wish to use any of the reserved characters {}, <>, or [] 
  1685.     literally, i.e. to be displayed as themselves instead of being interpreted
  1686.     as field delimiters, precede each such character with a \ backslash.
  1687.     (To use a \ literally you must do the same, \\.)  
  1688.     
  1689.         The following command in an Action card would load a form file
  1690.     called ORDER.FRM:
  1691.  
  1692.                 load(form, order.frm)
  1693.  
  1694.     Form files should ALWAYS be named with a ".FRM" extension to distinguish
  1695.     them clearly from other files.  If the user prints a form to a disk file,
  1696.     that file will be named with a ".PRN" extension.
  1697.  
  1698.         Finally, forms can be stored in libary files using the FGILIB.EXE
  1699.     utility, described in Chapter 7 of MANUAL1.DOC.  The following command 
  1700.     would load our form from within a libary named STUFF.FGI:
  1701.     
  1702.                 load(form, lib=stuff.fgi, order.frm)
  1703.     
  1704.     Notice that unlike the ansi() and graphic() commands, where the library 
  1705.     specification comes first, with load() we give the libary specification 
  1706.     AFTER the keyword "form". 
  1707.  
  1708.  
  1709.  
  1710.  Lookfor()
  1711.  
  1712.         The lookfor() command checks the user's disk for a file.  It takes
  1713.     a singe parameter, the file you wish to look for.  If the file is found
  1714.     the okay/failed flag is set to "okay"; if not it is set to "failed".
  1715.     The following example combines lookfor() with load() in a realistic
  1716.     setting:
  1717.  
  1718.                 lookfor(filename.htx)
  1719.                 if (failed) goto MESSAGE
  1720.                 load(new, filename.htx)
  1721.                 goto END
  1722.                 :MESSAGE
  1723.                 text(okay, "Unable to find FILENAME.HTX!")
  1724.                 :END
  1725.  
  1726.     This script checks for the presence of the desired book and skips to
  1727.     a text() command if the book cannot be found.  Otherwise it loads the
  1728.     book.  Even though a successful load() command would immediately
  1729.     abandon this script since it would no longer be present in memory,
  1730.     we insert a "goto END" line after it for logical consistency.
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738.  
  1739.                                       29
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  Play()
  1745.  
  1746.         The play() command performs 1-voice music on the PC's internal
  1747.     speaker, temporarily suspending other processing until the music is
  1748.     finished.  There is 1 parameter, a music string composed of a sequence of
  1749.     letters and numbers according to the convention described below.  Letters
  1750.     in the music string must be capitalized as shown in the examples.  The
  1751.     music string may include spaces for readability.  A music string may carry
  1752.     over onto one or more additional lines, provided that each broken line
  1753.     ends with a comma and each additional line begins with one or more leading
  1754.     spaces.  The music string must be enclosed in quotation marks as if it
  1755.     were text.
  1756.  
  1757.  
  1758.     MUSIC SYNTAX
  1759.  
  1760.         A to G    Play the specified note in the current octave.
  1761.  
  1762.         #         Append to a note character (A to G) to make that
  1763.                     note sharp.
  1764.  
  1765.         .         Append to a note character or to a sharp (#) to
  1766.                     extend that note by half its length.  Multiple
  1767.                     dots can be used, and each extends the note by
  1768.                     half as much as the previous dot.
  1769.  
  1770.         Ln        Set the length of notes and pauses.  The value
  1771.                     of "n" is a number between 1 and 64, where 1
  1772.                     indicates a whole note, 2 a half note, 4 a quarter
  1773.                     note, and so on.  The default is L4.
  1774.  
  1775.         On        Set the octave for subsequent notes.  The value
  1776.                     of "n" may be a number from 0 to 6 to specify the
  1777.                     octave, or it can be a "+" or "-" character to
  1778.                     increment or decrement the current octave number.
  1779.                     The default is O4, which contains middle C.
  1780.  
  1781.         P         Pause (rest) for the duration specified by the
  1782.                     previous L command.
  1783.  
  1784.         Sn        Set the amount of silence between notes.  The
  1785.                     value of "n" is a number from 0 to 2.  If 0, each
  1786.                     note plays for the full period set by the previous
  1787.                     L command.  If 1, each note plays for 7/8 of that
  1788.                     period.  If 2, each note plays for 3/4 of that
  1789.                     period.  These effects correspond to legato,
  1790.                     normal, and staccato playing styles.  The default
  1791.                     is S1.
  1792.  
  1793.         Tn        Set the tempo of the music (the number of quarter
  1794.                     notes per minute).  The value of "n" is a number
  1795.                     from 32 to 255.  The default is T120.
  1796.  
  1797.  
  1798.  
  1799.                                       30
  1800.  
  1801.  
  1802.  
  1803.  
  1804.         Here are a few examples:
  1805.  
  1806.         /  "Mary Had a Little Lamb"
  1807.         play("T150 L8 EDCDEEE P DDD P EGG P EDCDEEE L16 P L8 EDDEDC")
  1808.  
  1809.         /  Beethoven's Fifth:
  1810.         play("T180 O2 L2 P L8 P GGG L2 D# L24 P L8 P FFF L2 D")
  1811.  
  1812.         /  Simple scale up and down:
  1813.         play("L4 C L8S2 DEFGAB S1L4 O+C O-L8S2 BAGFED L2 C")
  1814.  
  1815.         /  Chromatic scale over two octaves, with the string carried
  1816.         /  over onto a second line
  1817.         play("L16 CC#DD#EFF#GG#AA#B O+ CC#DD#EFF#GG#AA#B O+ L4 C P,
  1818.             L16 C O- BA#AG#GF#FED#DC#C O- BA#AG#GF#FED#DC# L4 C")
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.  
  1858.  
  1859.                                       31
  1860.  
  1861.  
  1862.  
  1863.  
  1864.  Quit()
  1865.  
  1866.         The quit() command tells the Orpheus Reader to exit, the same as if
  1867.     the user had pressed <Alt-X> except that no attempt is made to save
  1868.     configuration, bookmark, or notepad files.  There are no parameters.
  1869.  
  1870.         An obvious use for quit() would be to prevent access to a work in which
  1871.     high-quality graphics were REQUIRED, if the user's display was not capable
  1872.     of displaying those graphics.  For example, the following script would go
  1873.     into an Init off the Homecard; after checking to see whether the user has
  1874.     at least a VGA color display, it either flows through to the rest of the
  1875.     book or displays a message and exits the program.
  1876.  
  1877.                 trymode(18)
  1878.                 if (okay) goto HAS_VGA
  1879.                 :EXIT
  1880.                 text("This book requires a VGA color display")
  1881.                 quit()
  1882.                 :HAS_VGA
  1883.                 if (color) goto READY
  1884.                 goto EXIT
  1885.                 :READY
  1886.  
  1887.     Note how this script uses two different tests, either of which can
  1888.     branch to the exit sequence.  If the user does not have VGA, the script
  1889.     flows through to the quit() command and we exit the program; if the user
  1890.     has VGA but does not have color, the script backs up so that again we
  1891.     flow into the quit() command and exit.  The actual words used for the
  1892.     labels can be anything you like, and do not have to capitalized; I use
  1893.     uppercase labels for readability.
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.                                       32
  1920.  
  1921.  
  1922.  
  1923.  
  1924.  Run()
  1925.  
  1926.         The run() command launches an external program having an extension of
  1927.     either EXE or COM.  There is a single parameter consisting of a command
  1928.     line reproduced exactly as you would enter it at the DOS prompt.  The
  1929.     command line may include space-delimited parameters as you would enter
  1930.     them at the DOS prompt.  Since a ")" character is considered to terminate
  1931.     the command line, the latter may not include parentheses.  The run()
  1932.     command must not be used to launch batch files, nor can it be used to
  1933.     run an internal DOS command such as TYPE or COPY.  (See runbat() below.)
  1934.  
  1935.                 /  launch LIST.COM to display README
  1936.                 run(list readme)
  1937.                 /  launch GIFSHOW.EXE to display a sequence of 3 pictures
  1938.                 run(gifshow jupiter.gif saturn.gif neptune.gif)
  1939.                 /  launch EDIT.EXE with no file specified
  1940.                 run(edit)
  1941.  
  1942.  
  1943.  Runbat()
  1944.  
  1945.         The runbat() command launches a batch file or runs an internal DOS
  1946.     command such as TYPE or COPY.  (Internal DOS commands are those for which
  1947.     there is no separate program of the same name and with a COM or EXE
  1948.     extension.  External DOS commands are those which do refer to a separate
  1949.     program, such as MORE.EXE.)  There is a single parameter consisting of a
  1950.     command line reproduced exactly as you would enter it at the DOS prompt.
  1951.     Since a ")" character is considered to terminate the command line, the
  1952.     latter may not include parentheses.  If using runbat() to launch a batch
  1953.     file, the batch file may include calls to internal and external DOS
  1954.     commands as well as to other programs.  Runbat() can also launch programs
  1955.     having a COM or EXE extension, but it takes a little more memory than
  1956.     run(), so it is better to use run() for such programs.
  1957.  
  1958.                 /  launch ORDER.BAT and specify a certain order form
  1959.                 runbat(order book1.frm)
  1960.  
  1961.                 /  tell DOS to print REGISTER.DOC on the printer (1)
  1962.                 runbat(copy register.doc prn)
  1963.  
  1964.                 /  tell DOS to print REGISTER.DOC on the printer (2)
  1965.                 /  note that this version requires the ">" symbol
  1966.                 runbat(type register.doc >prn)
  1967.  
  1968.  
  1969.     Both run() and runbat() clear the screen to the normal DOS colors before
  1970.     carrying out the requested action.  What they do on return depends on
  1971.     whether they were called from an Action card or a Graphic card.  If called
  1972.     from a Graphic card, assuming that a graphic or ansi screen was displayed,
  1973.     both run() and runbat() attempt to restore whatever was onscreen before
  1974.     the external program was called.  In an Action card however this is not
  1975.     done; the screen is not restored until control returns to the parent card.
  1976.  
  1977.  
  1978.  
  1979.                                       33
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  Set()
  1985.  
  1986.         The set() command enables you to assign a symbolic or numerical value
  1987.     to a variable.  Parameters consist of one or more "variable=value" phrases
  1988.     and may be as numerous as can fit on one line.  All variables have certain
  1989.     default values that are discussed below; once you have assigned a value
  1990.     to a variable it retains that value until you change it.  Currently only
  1991.     built-in variables may be set, but a future release will enable you to
  1992.     create variables of your own.  The following examples illustrate the use
  1993.     of the set() command:
  1994.  
  1995.                 set(blink=off)
  1996.                 set(draw=1, erase=14)
  1997.                 set(fadein=tunnelin, fadeout=venetian, delay=1)
  1998.  
  1999.     As you can see, some variables receive a numerical value, while others
  2000.     receive a symbolic value represented by a keyword.  The list below
  2001.     explains what the variables mean and what values they can receive.
  2002.  
  2003.     BLINK
  2004.     Blink refers to the appearance of high-intensity background colors
  2005.     when an ansi screen is displayed with the ansi() command.  Normally, such
  2006.     colors do NOT appear as high-intensity backgrounds but rather as areas
  2007.     that blink.  The ability to give the command "set(blink=off)" lets you
  2008.     work with a more exciting color palette in your ansi screens.  You can
  2009.     even use a time delay to show an ansi screen that starts off with blinking
  2010.     areas that suddenly stop and change color:
  2011.  
  2012.                 set(blink=on)      // in case it was set to off earlier
  2013.                 ansi(mypic.ans)    // display with blinking areas
  2014.                 waitfor(18)        // pause 1 second
  2015.                 set(blink=off)     // turn blink into bright backgrounds
  2016.                 ansi(mypic.ans)    // refresh display
  2017.                 waitfor()          // wait for keypress
  2018.  
  2019.     Note that for this effect to work you MUST make the second ansi() call,
  2020.     because Orpheus does not actually change blink when you give the set()
  2021.     command, only when an ansi screen is displayed.
  2022.  
  2023.     DELAY
  2024.     Delay refers to the speed of certain special effects such as fadein and
  2025.     fadeout, discussed below.  The default value of delay is always 0, which
  2026.     results in a reasonably fast effect.  Some special effects are quicker
  2027.     than others, and some are more attractive than others when slowed down.
  2028.     Since the delay setting applies to BOTH fadein and fadeout (and later
  2029.     perhaps to other variables) you may have to change it repeatedly if you
  2030.     are combining special effects in a sequence.  The first example below
  2031.     sets delay to a very slow setting; the second returns it to normal:
  2032.  
  2033.                 set(delay=4)
  2034.                 / .........
  2035.                 set(delay=0)
  2036.  
  2037.  
  2038.  
  2039.                                       34
  2040.  
  2041.  
  2042.  
  2043.  
  2044.     DRAW, ERASE
  2045.     Draw and erase have to do with making hotspots in OH.EXE.  They receive
  2046.     numerical values from 0 to 15, representing color values from black to
  2047.     white as shown in the chart below.  Their default values are draw=15
  2048.     (white), erase=0 (black).  The following example sets draw to yellow,
  2049.     erase to grey:
  2050.  
  2051.                 set(draw=14, erase=7)
  2052.  
  2053.     You only need to change these variables if the colors of a particular
  2054.     graphic made it difficult for you to distinguish between a hotspot in
  2055.     progress and the original graphic.  Finished hotspots do not in any way
  2056.     alter the appearance of a graphic, and references to these variables are
  2057.     not included in the compiled version of a book.
  2058.  
  2059.  
  2060.                     0 black             8 dark grey
  2061.                     1 blue              9 light blue
  2062.                     2 green            10 light green
  2063.                     3 cyan             11 light cyan
  2064.                     4 red              12 light red
  2065.                     5 magenta          13 light magenta
  2066.                     6 brown            14 yellow
  2067.                     7 grey             15 white
  2068.  
  2069.  
  2070.     FADEIN, FADEOUT
  2071.     Fadein and fadeout refer to the style with which a graphic is displayed
  2072.     or erased.  The following styles are available:
  2073.  
  2074.                 normal ........ the default:  replace pixels at random
  2075.                 diagonal ...... splits the screen diagonally
  2076.                 wipe .......... wipes image on or off from left to right
  2077.                 split ......... splits the screen horizontally
  2078.                 unveil ........ like a curtain
  2079.                 venetian ...... like venetian blinds
  2080.                 tunnelin ...... tunnels from outside to center
  2081.                 tunnelout ..... tunnels from center to outside
  2082.                 check ......... checkerboard style
  2083.                 off ........... ** turn off fades for multiple graphics **
  2084.  
  2085.     Fadein and fadeout are set individually, so you can have your graphics
  2086.     fading in with one style and fading out with another; you can even have a
  2087.     sequence of graphics in which the fade styles change with each graphic.
  2088.     To make this work, bear in mind that a graphic does not fade out until it
  2089.     is about to be replaced -- whether by another graphic, by an ansi screen,
  2090.     or by a text card.  The following sequence varies both the speed and the
  2091.     style of fades:
  2092.  
  2093.                 set(fadein=tunnelin, fadeout=tunnelout, delay=1)
  2094.                 graphic(example1.pcx, 13, full)
  2095.                 waitfor()
  2096.  
  2097.  
  2098.  
  2099.                                       35
  2100.  
  2101.  
  2102.  
  2103.  
  2104.                 set(fadein=diagonal, delay=0)
  2105.                 graphic(example2.pcx, 13, full)
  2106.                 waitfor()
  2107.                 set(fadein=wipe, fadeout=split)
  2108.                 graphic(example3.pcx, 13, full)
  2109.                 set(fadeout=venetian, delay=3)
  2110.                 waitfor()
  2111.  
  2112.     The sequence begins by setting fadein, fadeout and delay for the first
  2113.     graphic.  Before moving on it changes the fadein style for the second
  2114.     graphic.  After displaying the second graphic it changes the fadeout style
  2115.     for it as well as the fadein style for the third graphic.  After that
  2116.     graphic is displayed the fadeout style is changed again, and the delay
  2117.     factor set slow to emphasize the quality of the chosen style.  Note that
  2118.     each graphic is separated by a waitfor() command to ensure that each one
  2119.     stays onscreen until the user presses a key.  (The last waitfor() command
  2120.     would only be necessary in an Init or Action card.)
  2121.  
  2122.         In the final example we turn fades OFF in order to allow multiple
  2123.     graphics onscreen at the same time:
  2124.  
  2125.             set(fadein = off, fadeout = off)
  2126.             graphic(first.pcx, 18, 0, 0)
  2127.             graphic(second.pcx, 18, 450, 0)
  2128.             graphic(third.pcx, 18, 0, 390)
  2129.             graphic(fourth.pcx, 18, 450, 390)
  2130.             set(fadeout = normal)
  2131.  
  2132.  
  2133.     MODE
  2134.     Mode enables you to set the video mode independently of a call to
  2135.     graphic().  It is intended for situations in which you wish to do
  2136.     something that requires the prior establishment of a graphical video
  2137.     mode.  Specifically, the gbox() and gtext() commands do not include a
  2138.     mode parameter, and so require that the video mode be changed before
  2139.     they are called.  In the following example we want to draw a white box
  2140.     in the middle of the screen and then overlay a graphic inside it:
  2141.  
  2142.             set(fadein = off, fadeout = off, mode = 13)
  2143.             gbox(15, 99, 49, 120, 100)
  2144.             graphic(portrait.pcx, 13, 107, 55)
  2145.             set(fadeout = normal)
  2146.  
  2147.     Turning off fades ensures that the graphic() call will not erase the
  2148.     screen before displaying portrait.pcx.  Since the box is drawn larger
  2149.     than the graphic, which in turn is positioned so that its upper left
  2150.     corner is below and to the right of the upper left corner of the box,
  2151.     the final effect is of a white frame around the graphic.  However, in
  2152.     order to do this we had to set the video mode first, since gbox() requires
  2153.     that a graphical video mode be in effect before it is called.  Another way
  2154.     to achieve the same effect would be to make the graphic() call first,
  2155.     then draw the frame around it with four separate calls to gbox().
  2156.  
  2157.  
  2158.  
  2159.                                       36
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  Text()
  2165.  
  2166.         For use in Action cards, the text() command lets you display up to
  2167.     23 lines of text in a temporary window, with optional parameters to
  2168.     control appearance, screen position, and the length of time that the
  2169.     window remains onscreen.  If options are not specified, Orpheus uses
  2170.     default behaviors such as calculating screen coordinates to center the
  2171.     window.  The window area is automatically sized to fit the longest line,
  2172.     except when the "okay" keyword is used:  this forces the window to
  2173.     become a standard "Okay" box with the limitations discussed below.
  2174.  
  2175.         The text() command is at once powerful, flexible, and easy to use.
  2176.     It is ideal for situations where you want to display a small amount of
  2177.     information that does not require a separate card (such as the definition
  2178.     of a word), or where you want the temporary text to be shown side-by-side
  2179.     with text on the parent card.
  2180.  
  2181.     LINES OF TEXT
  2182.     The text() command must receive at least one string parameter, meaning
  2183.     a line of text enclosed in quotation marks.  Anything enclosed in
  2184.     quotation marks is interpreted as one line of text.
  2185.  
  2186.                 text("This is a one-line message")
  2187.  
  2188.     This command displays the quoted text in a standard box, centered on
  2189.     the screen.  To display multiple lines of text, separate your parameters
  2190.     with commas as you would with other commands.  If there is not enough
  2191.     room on a line, or if you wish to enter a multiline command so that it
  2192.     will resemble what you intend to display, start each new parameter on
  2193.     a separate line, being sure to indent each such additional line by at
  2194.     least one leading space.  The following examples have exactly the same
  2195.     results:
  2196.  
  2197.                 text("This message", "will appear", "on three lines.")
  2198.  
  2199.                 text("This message",
  2200.                      "will appear",
  2201.                      "on three lines.")
  2202.  
  2203.     In both versions, each intended line of text is enclosed in quotation
  2204.     marks, with commas separating the parameters.  In the second version the
  2205.     two additional lines are indented so as to ensure that Orpheus doesn't
  2206.     misinterpret them later as separate commands.  Regardless of whether
  2207.     the lines are entered as shown in the first version or in the second,
  2208.     the result will show all three lines flush left in a centered box,
  2209.     with two spaces on either side of the longest line:
  2210.  
  2211.                              +===================+
  2212.                              |  This message     |
  2213.                              |  will appear      |
  2214.                              |  on three lines.  |
  2215.                              +===================+
  2216.  
  2217.  
  2218.  
  2219.                                       37
  2220.  
  2221.  
  2222.  
  2223.  
  2224.     Individual text strings cannot be broken by a newline; in other words,
  2225.     you CANNOT do this:
  2226.  
  2227.                 text("This broken line will
  2228.                       generate an error message")
  2229.  
  2230.     To include a blank line in your text, enter the blank line as a space
  2231.     enclosed in quotation marks, like so:
  2232.  
  2233.                 text("This message", "will appear", " ", "on four lines!")
  2234.  
  2235.                              +===================+
  2236.                              |  This message    |
  2237.                              |  will appear     |
  2238.                              |                  |
  2239.                              |  on four lines!  |
  2240.                              +===================+
  2241.  
  2242.     SPECIAL CHARACTERS
  2243.     Two characters must be given special handling if you wish to include
  2244.     them in your lines of text.  The  "  character normally means the
  2245.     beginning or end of a text; to include it as a literal character, precede
  2246.     it with a  \  backslash.  The backslash in turn normally means that the
  2247.     next character is special, so to include it as a literal character,
  2248.     precede it by another backslash.  For example:
  2249.  
  2250.                 text("This \"message\"",
  2251.                      "gives the path",
  2252.                      "to C:\\ORPHEUS")
  2253.  
  2254.                              +===================+
  2255.                              |  This "message"  |
  2256.                              |  gives the path  |
  2257.                              |  to C:\ORPHEUS.  |
  2258.                              +===================+
  2259.  
  2260.  
  2261.     COORDINATES
  2262.     You can position the text window by specifying the screen coordinates of
  2263.     the upper left corner of the box.  Row 1 is at the top of the screen and
  2264.     column 1 is at the far left.  If two numbers are entered, the first is
  2265.     the row, the second is the column.  If only one number is entered it
  2266.     represents the row; the box will be horizontally centered.  You cannot
  2267.     specify the column without giving a number for the row.  If no numbers are
  2268.     given the window is centered vertically and horizontally.  For example:
  2269.  
  2270.                 text(1, "This will be centered at the top of the screen.")
  2271.  
  2272.                 text(1, 1, "This will be at the upper left corner.")
  2273.  
  2274.                 text("This will be centered vertically and horizontally.")
  2275.  
  2276.  
  2277.  
  2278.  
  2279.                                       38
  2280.  
  2281.  
  2282.  
  2283.  
  2284.                 text(18, 40, "This will appear", "in the lower right.")
  2285.  
  2286.     Whenever you use text() with coordinates, use the <Alt-G> command to
  2287.     verify your parameters and see the results.  (Place the cursor on the
  2288.     line where the command begins, then press <Alt-G>.)  If a row or column
  2289.     parameter would result in the window being partially offscreen, Orpheus
  2290.     will give an error message (and will not compile the command).
  2291.  
  2292.     COLOR
  2293.     The default colors of the text() window are those of the standard "Okay"
  2294.     box.  You have two other choices:  by using the "color" keyword with
  2295.     either the "help" or "text" keywords, you can use the current colors of
  2296.     the Help dialog or simply the current text color.  The real colors shown
  2297.     will depend on the current settings when the user views your book.
  2298.  
  2299.                 text("This appears in the colors of the \"Okay\" box")
  2300.  
  2301.                 text(color = help, "This will look like the Help window")
  2302.  
  2303.                 text(color = text, "This will look like normal text")
  2304.  
  2305.     Notice that the word "text" operates both as a command and as a keyword.
  2306.     When you use text color, both the border and the text itself appear in
  2307.     the same color.  With the other settings, the border is usually a
  2308.     different color.
  2309.  
  2310.     FRAME
  2311.     The default frame style of the window border is a double-line box.  You
  2312.     set your own style by using the "frame" keyword with a number from 0 to 6.
  2313.     The numbers represent the styles presented in the Frame Dialog, which
  2314.     you can view by opening the Project Menu and selecting "Frame".
  2315.  
  2316.                 text(frame = 1, "This appears in a single-line box")
  2317.  
  2318.                 text(frame = 0, "This appears in a box with no frame")
  2319.  
  2320.                 text(frame = 5, "This appears in a box with single lines",
  2321.                                 "on the top and sides, and a double line",
  2322.                                 "on the bottom")
  2323.  
  2324.  
  2325.     TIMING
  2326.     The default behavior of a text window is to remain onscreen until the
  2327.     user presses a key or clicks the mouse.  By using the "delay" keyword
  2328.     with a number from 1 to 99, you can specify the number of seconds for
  2329.     Orpheus to wait before clearing the screen automatically.  If the user
  2330.     presses a key before the time is up, Orpheus stops waiting.  (Note that
  2331.     setting "delay" inside a text() command does NOT affect the delay
  2332.     setting for fade effects in graphic modes.)
  2333.  
  2334.                 text("This remains until the user presses a key")
  2335.  
  2336.                 text(delay = 5, "This remains for 5 seconds only")
  2337.  
  2338.  
  2339.  
  2340.  
  2341.                                       39
  2342.  
  2343.  
  2344.  
  2345.  
  2346.     Now let's see all of the text() parameters working together:
  2347.  
  2348.                 text(1, 50, color = help, frame = 6, delay = 30,
  2349.                     "This little message",
  2350.                     "stretches from the",
  2351.                     "top line down",
  2352.                     "along the right half",
  2353.                     "of the screen, and",
  2354.                     "has the colors of the",
  2355.                     "Help dialog.",
  2356.                     " ",
  2357.                     "It has 2 blank lines,",
  2358.                     "2 \"quotation\" marks,",
  2359.                     "and a \\backslash,",
  2360.                     "not to mention,",
  2361.                     "commas at the ends",
  2362.                     "of several lines.",
  2363.                     " ",
  2364.                     "The frame has single",
  2365.                     "lines at top and left,",
  2366.                     "double lines at bottom",
  2367.                     "and right.  After 30",
  2368.                     "seconds it disappears")
  2369.  
  2370.  
  2371.     THE "OKAY" KEYWORD
  2372.     If you use the "okay" keyword as the first parameter in a text()
  2373.     command, you are telling Orpheus to display your message in a standard
  2374.     Okay box.  This means that the dimensions, position, color, and frame
  2375.     of the window are determined entirely by Orpheus, but the resulting
  2376.     window has a hilited "Okay" prompt in the lower right window.  No delay
  2377.     is permitted:  the user must press a key or click a mouse button.
  2378.     Your message is limited to 7 lines, with a maximum line length of 57
  2379.     characters.  (The longest line is centered in the window, with any other
  2380.     lines displayed flush left with it.)
  2381.  
  2382.  
  2383.         +=============================================================+
  2384.         |                                                             |
  2385.         |         This book requires an EGA graphics display.         |
  2386.         |         Sorry about that!
  2387.         |                                                  < Okay >   |
  2388.         +=============================================================+
  2389.  
  2390.  
  2391.  
  2392.  
  2393.  
  2394.  
  2395.  
  2396.  
  2397.  
  2398.  
  2399.  
  2400.  
  2401.                                       40
  2402.  
  2403.  
  2404.  
  2405.  
  2406.  Trymode()
  2407.  
  2408.         The trymode() command provides a simple and precise way to determine
  2409.     the capabilities of the user's video hardware.  The single parameter is
  2410.     the number of a video mode.  Trymode() does not actually set the video
  2411.     mode, but rather tests the user's video system to see if it is capable
  2412.     of switching to that mode, and sets an internal flag accordingly.  If
  2413.     the display CAN switch to that mode the flag is set to "okay".  If the
  2414.     display CANNOT switch to that mode the flag is set to "failed".
  2415.  
  2416.                 trymode(16)                 // can we do EGA?
  2417.                 if (failed) goto END
  2418.                 graphic(ega_pic.pcx, 16, full)
  2419.                 :END
  2420.  
  2421.         Use trymode() in terms of the particular graphics you wish to display.
  2422.     The example above shows a script that might go in a Graphic card.
  2423.     Presumably the author first wrote the graphic() command and experimented
  2424.     with the mode parameter until he was sure that mode 16 was needed.  As
  2425.     shown by Table 1, "Modes and Resolutions" (at the end of this guide), mode
  2426.     16 can be handled by EGA/VGA displays, but not by less advanced displays
  2427.     such as the CGA. By controlling the program flow depending on the results
  2428.     of the trymode() test, he can ensure that if the user's hardware cannot
  2429.     display the graphic nothing bad will happen:  the script will harmlessly
  2430.     skip to the end.
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.  
  2452.  
  2453.  
  2454.  
  2455.  
  2456.  
  2457.  
  2458.  
  2459.  
  2460.  
  2461.                                       41
  2462.  
  2463.  
  2464.  
  2465.  
  2466.  Waitfor()
  2467.  
  2468.         The waitfor() command enables you to insert a pause in a script.
  2469.     The optional parameter is a number representing 18ths of a second.  If
  2470.     there is no parameter Orpheus waits until the user presses a key.  If
  2471.     a number is given Orpheus waits that number of 18ths of a second OR until
  2472.     the user presses a key.  In other words, waitfor() gives you an optionally
  2473.     timed pause that can always be broken by a keypress.
  2474.  
  2475.                 /  wait indefinitely until keypress
  2476.                 waitfor()
  2477.                 /  wait 1 second (or until keypress)
  2478.                 waitfor(18)
  2479.                 /  wait 10 seconds (or until keypress)
  2480.                 waitfor(180)
  2481.  
  2482.         If you display graphics or ansi files from Init or Action cards, you
  2483.     will soon notice that you MUST place a waitfor() command at the end of
  2484.     the script.  Otherwise, control returns immediately to the parent card
  2485.     and the image disappears a fraction of a second after it was displayed.
  2486.     This is NOT the case with Graphic cards, where control remains with the
  2487.     last-displayed image in the same manner as with a text card.
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.  
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.  
  2516.  
  2517.  
  2518.  
  2519.  
  2520.  
  2521.                                       42
  2522.  
  2523.  
  2524.  
  2525.  
  2526.   ---------------------------------------------------------------------------
  2527.                      CHAPTER 3  -  CONVERTING OLD COMMANDS
  2528.   ---------------------------------------------------------------------------
  2529.  
  2530.  
  2531.  
  2532.  Versions Before 1.30:  Graphic Commands
  2533.                         Run Commands
  2534.                         Random Commands
  2535.  Versions Before 1.50:  Hotspot()
  2536.                         Jump(), Jumplist()
  2537.                         Play()
  2538.  
  2539.  
  2540.         ALL programming commands from versions prior to 1.30 must be
  2541.     converted to the new standard, which is described in Chapter 1 and in the 
  2542.     Command Reference (Chapter 2).  Commands no longer have to be entered in 
  2543.     capital letters.  Most conversions concern commands that would have been 
  2544.     in Graphic cards.  In addition, users of versions 1.30 to 1.41 will need 
  2545.     to update their use of hotspot(), jump(), jumplist(), and play().
  2546.  
  2547.  
  2548.  Graphic Commands - Before 1.30
  2549.  
  2550.         The commands FILEPATH=, RESOLUTION=, and MODE= are now combined into
  2551.     the graphic() command.  The following data in the old version:
  2552.  
  2553.                 FILEPATH=c:\art\bkcover.pcx
  2554.                 RESOLUTION=640x200
  2555.                 MODE=14
  2556.  
  2557.     becomes this in the new version:
  2558.  
  2559.                 graphic(bkcover.pcx, 14, full)
  2560.  
  2561.     There are three points to notice here.  (1) Instead of specifying the
  2562.     complete filepath you should give only the filename.  Although you _can_
  2563.     give a complete filepath, this would be compiled into the finished version
  2564.     of your work and would be of no use to your readers.
  2565.  
  2566.     (2) Instead of telling Orpheus what resolution to use, with the video mode 
  2567.     being an optional detail, you now specify only the video mode.  The table 
  2568.     of Modes & Resolutions makes it easy to find an appropriate mode, and you 
  2569.     can test the results by placing the cursor on the line with the command 
  2570.     and pressing <Alt-G>. 
  2571.  
  2572.     (3) Until Version 1.30 you could ONLY display full-screen graphics.  Now
  2573.     you can display graphics that are smaller than the screen and place them
  2574.     anywhere you want using parameters 3 to 5.  To display a full-screen
  2575.     graphic, just use the word "full" as in the example above.  Read the entry
  2576.     on graphic() in Chapter 2 to learn about displaying smaller graphics.
  2577.  
  2578.  
  2579.  
  2580.  
  2581.                                       43
  2582.  
  2583.  
  2584.  
  2585.  
  2586.         The commands HOTSPOT= and LINKWORD= are now combined into the
  2587.     hotspot() command.  This command takes the linkword as the first
  2588.     parameter, with the hotspot data string as the second parameter.  Note
  2589.     that when you draw a hotspot on a graphic, Orpheus enters the hotspot()
  2590.     command for you automatically along with the hotspot data, the same as it
  2591.     did in previous versions.  If you have existing hotspots you must delete
  2592.     redraw them, but read the following if you also have associated linkwords
  2593.     that you wish to keep.
  2594.  
  2595.         Suppose you have a graphic of a Mississippi riverboat, showing a
  2596.     gambler on whom you've made a hotspot.  In the old commands you would
  2597.     have something like:
  2598.  
  2599.             HOTSPOT=5Q&6Q(7P*8P+9P+9[":O/;O0<N2=N2>U,?U#?Y(@[&■
  2600.             LINKWORD=gambler
  2601.  
  2602.     In the new version this must become:
  2603.  
  2604.             hotspot( gambler, "0..........data string.........")
  2605.  
  2606.     Before you can redraw the hotspot you will have to comment out any lines 
  2607.     containing commands that are no longer valid.  Get your graphic() command 
  2608.     working first (you can test it individually with <Alt-G>), then comment 
  2609.     out all other lines by inserting a "/" at the far left.  Now delete the
  2610.     "HOTSPOT" line entirely, leaving the cursor on that empty line.  You can
  2611.     now press <Alt-C> and, if the graphic displays correctly, follow the
  2612.     procedure for making a hotspot described in Chapter 2.  Upon return from
  2613.     the graphic you will see a line like the one above, but with the word
  2614.     "linkword" as the first parameter.  The final step is delete that word,
  2615.     then mark the original linkword you wish to replace it with and MOVE it
  2616.     into the new location.  You can then remove the "LINKWORD" line.
  2617.  
  2618.         NOTE:  previous versions of Orpheus simply ignored hotspot commands
  2619.     for which the linkword command did not actually have a linkword with a
  2620.     completed link on it.  As of Version 1.30, Orpheus considers this an
  2621.     incomplete command and will not let you use the Alt-C command to perform
  2622.     the script and create new hotspots.  To bypass this without deleting
  2623.     the command, comment it out by placing a ";" or "/" at the beginning of
  2624.     the line.
  2625.  
  2626.         Finally, the DRAW= and ERASE= commands (for adjusting the colors used
  2627.     while drawing hotspots) have been changed into optional parameters of
  2628.     the new set() command.  Thus, if you used the following before:
  2629.  
  2630.             DRAW=14         // draw in yellow
  2631.             ERASE=1         // erase in blue
  2632.  
  2633.     you would now use the following:
  2634.  
  2635.             set(draw=14, erase=1)
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.                                       44
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  Run Commands - Before 1.30
  2647.  
  2648.         The RUN= and RUNBAT= commands now use parentheses in place of the "="
  2649.     sign.  If you have a line like:
  2650.  
  2651.             RUN=print file.doc
  2652.  
  2653.     you would convert it to:
  2654.  
  2655.             run(print file.doc)
  2656.  
  2657.  
  2658.  Random Commands - Before 1.30
  2659.  
  2660.         The RANDOM= commands have been replaced by the more capable jump()
  2661.     and jumplist() commands.  When specific cards were listed we originally
  2662.     used the 3-letter extension from the filename; as of 1.50 we get the
  2663.     card number in decimal form by opening the File Menu while in that card,
  2664.     and looking at the "Save As" line.  The card number is hilited at the 
  2665.     right.
  2666.  
  2667.             RANDOM=ALL                            // becomes:
  2668.             jumplist(random, all)
  2669.  
  2670.             RANDOM=INCLUDE,00B,01A,...            // became until 1.50,
  2671.             jumplist(random, include=00B,01A,...) // but is now:
  2672.             jumplist(random, include, 12, 49, ...)
  2673.  
  2674.             RANDOM=EXCLUDE,02Z,03G,...            // became until 1.50,
  2675.             jumplist(random, exclude=02Z,03G,...) // but is now:
  2676.             jumplist(random, exclude, 72, 99,...)
  2677.  
  2678.             RANDOM=JUMP                     becomes:
  2679.             jump(random)
  2680.  
  2681.     The jump() command in particular has far more useful purposes than the
  2682.     above, as you can see in the discussion of it in Chapter 2, the
  2683.     Programming Command Reference.
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.                                       45
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  Hotspot() - Before 1.50
  2707.  
  2708.         As noted above, from versions 1.30 to 1.41 the hotspot() command
  2709.     took a data string enclosed in two copies of the block character, ascii
  2710.     254.  As of version 1.50 the data string is enclosed in quotation marks
  2711.     like an ordinary text string, but has some other differences that are
  2712.     equally important.  First, the first character of the string is now either 
  2713.     "0" or "1" to mark a hotspot created for either a true graphic or an ansi 
  2714.     screen respectively.  Second, the characters used in the string are drawn
  2715.     from a higher range of ascii values, making old data strings completely
  2716.     incompatible with version 1.50 and up.  (The new standard is both more
  2717.     coherent and more powerful, so this should be the last time you have to
  2718.     convert your hotspots.)
  2719.  
  2720.         To convert existing hotspot commands, you will have to redraw them
  2721.     and let Orpheus insert the new data string.  Assuming you have a command
  2722.     a completed linkword that you wish to keep, comment out that line and
  2723.     any others that are no longer valid, then insert a blank line or two
  2724.     and proceed as described in chapter 2 for making a hotspot.  You should
  2725.     be able to redraw your hotspot without any difficulty.  Upon return from
  2726.     the graphic, delete the dummy word "linkword" and replace it with what
  2727.     you really want by marking the original linkword and moving it into place.
  2728.  
  2729.  
  2730.  Jump(), Jumplist() - Before 1.50
  2731.  
  2732.         When specific cards were referred to, these commands previously
  2733.     used the 3-letter extension from each card's filename.  In the case of
  2734.     jump() a colon was used to precede the 3-letter extension.  The new
  2735.     standard makes things simpler by using numbers in decimal, without some
  2736.     of the trappings that used to be required.  To find the number of a
  2737.     card, navigate to that card and open the File Menu; the number will be
  2738.     hilited on the "Save As" line.
  2739.  
  2740.             OLD USAGE:
  2741.             jumplist(random, include=00A, 01B, 0G9........)
  2742.             jump(:00A)
  2743.  
  2744.             NEW USAGE:
  2745.             jumplist(random, include, 10, 42, 129..........)
  2746.             jump(10)
  2747.  
  2748.     As you can see, the new standard is simpler and more in tune with the
  2749.     way other commands are given.
  2750.  
  2751.  
  2752.  Play() - Before 1.50
  2753.  
  2754.         The music string given in a play() command must now be enclosed in
  2755.     quotation marks, as shown in Chapter 2.
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.                                       46
  2762.  
  2763.  
  2764.  
  2765.  
  2766.   ---------------------------------------------------------------------------
  2767.                        TABLE 1  -  MODES AND RESOLUTIONS
  2768.   ---------------------------------------------------------------------------
  2769.  
  2770.  
  2771.  
  2772.         All of the listed video modes are graphic modes.  The "Resolution"
  2773.     column gives the number of pixels onscreen, with the first number being
  2774.     the horizontal count (pixel columns), the second being the vertical count
  2775.     (pixel rows).  The "Text" column refers to the number of character cells
  2776.     available when text is displayed using the built-in ROM characters (as
  2777.     seen in text mode).  The numbers are again given as columns x rows.
  2778.  
  2779.         Where two numbers are given under "Colors", such as 16/64, the first
  2780.     figure represents the number of colors that can be displayed at one time,
  2781.     while the second figure represents the number of colors available to
  2782.     choose from in that video mode.  256K means 262,144 possible colors.
  2783.  
  2784.  
  2785.             Mode   Resolution  Text     Colors      Adapters
  2786.  
  2787.             4      320x200     40x25       4        CGA/EGA/VGA/MCGA
  2788.             5      320x200     40x25       4        CGA/EGA/VGA/MCGA
  2789.             6      640x200     80x25      2/16      CGA/EGA/VGA/MCGA
  2790.             9      320x200     40x25      16        Tandy,PCjr
  2791.            12      320x200     40x25       2        HGC
  2792.            13      320x200     40x25      16        EGA/VGA
  2793.            14      640x200     80x25      16        EGA/VGA
  2794.            15      640x350     80x25       2        EGA/VGA
  2795.            16      640x350     80x25     16/64      EGA/VGA
  2796.            17      640x480     80x30      2/256K    VGA/MCGA
  2797.            18      640x480     80x30     16/256K    VGA
  2798.            19      320x200     40x25    256/256K    VGA/MCGA
  2799.            20      320x200     40x25    256/256K    VGA
  2800.            21      320x400     40x50    256/256K    VGA
  2801.            22      320x240     40x30    256/256K    VGA
  2802.            23      320x480     40x60    256/256K    VGA
  2803.  
  2804.  
  2805.  
  2806.  
  2807.  
  2808.  
  2809.  
  2810.  
  2811.  
  2812.  
  2813.  
  2814.  
  2815.  
  2816.  
  2817.  
  2818.  
  2819.  
  2820.  
  2821.                                       46
  2822.  
  2823.