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