HELPMENU INFORMATION FILE

HELPMENU Syntax

   Begin                       End

   1: LIST                --->

PROGRAM DESCRIPTION

    HELPMENU is a User RPL program that can display pages of information
    for the user to review. It can be used freely with any software you 
    write. HELPMENU is FREEWARE, obviously. You can distribute it all you 
    like. Just use my name if you do.

1. HELPMENU COMMANDS

   To move forward a page, you can:
     - Press the >> softkey
     - Press NXT
     - Press the + key

   To move backward a page, you can:
     - Press the << softkey
     - Press PREV
     - Press the - key

   To quit
     - Press ENTER or ON

   To move to a specific page (ie 1-9)
     - Press the number that corresponds with that page

   To move to the last page
     - Press 0

2. BASIC HELPFILE INFORMATION

   Information about creating help files.

   The most basic help file is a list of strings. The strings can be made up
   of up to 8 lines. Multi-line strings are created by inserting the linefeed
   character into a string. This character is produced by [RightShift]-[.]

   Example: Creating a simple file (** REALLY BASIC **)

   1. Create an empty list:

      Stack:                             
      1:            {}

   2. Say you want the following in a help screen:

     +----------------------+
     | Concrete Design 1    |
     |                      |
     | Limit States Design  |
     |                      |
     | Title Screen         |
     |                      |
     |                      |
     +----------------------+

     What you're doing:                      What you see:
     =================================       ============================

     You'd begin with open quotes:           ""
     Type first line of text                 "Concrete Design 1"
     Enter first Line feed (rightshift-.)    "Concrete Design 1
                                             "
     Enter another line feed                 "Concrete Design 1
   
                                             "
     Enter another line of text              "Concrete Design 1
  
                                             Limit States Design"
 
     and so on...

   3. Now your stack looks like this:

      2:                    {}
      1: "Concrete Design 1...

      You want to add the string to the list, so press +

   4. Now you see:

      1: {
         "Concrete Design 1...
         }

   5. Add more strings as you wish, in the same manner as above.

   6. To see what you've created, make a copy first (press ENTER) and then
      run HELPMENU. 

3. ADVANCED HELPFILE INFORMATION: GRAPHICS

  This section assumes you know what A GROB is.
  
  To include a GROB in a helpfile, just add a grob to the list and it
  will be displayed. You can create GROBS that contain a lot of text by 
  using the programs in the HTOOLS directory. As a sample, try the string
  from the above and run the following programs on it:

  LSPLIT                   This program splits a string into several strings
  L->G                     Converts each string in the list into GROBS
  GSTITCH                  "Stitches" all the GROBS together into 1 GROB
  LOOK                     Lets you examine your handiwork

  The Table of Contents in SAMP.HLP was created this way.

  Of course, if you are an artistic type you can embed freehand drawings 
  done in the PICTURE mode, by recalling the PICT to the stack, as in:

  PICT RCL

  Note that a 132x64 GROB uses up about 1k of memory. A 64x32 GROB uses 
  1/4 that amount, about 250 bytes. Your memory is NOT infinite!

4. ADVANCED HELPFILE INFORMATION: PROGRAMS
  
  This section assumes you know a little User RPL.

  You can embed programs in a helpfile. They can handle keystrokes, animate,
  ask questions, do basically whatever you tell them to do.
                 
  SIMPLE DISPLAY PROGRAMS

  Sometimes you want to have a program just do a screen write. For example:

  << "The value of X " 10 CHR + "is: " +
     X + 1 DISP >>

  Or say you want to get input:

  << { } TMENU
     "Enter X" {1} INPUT
     OBJ-> 'X' STO >>

  GLOBAL VARIABLE 'Ctr'

  You can change the page number by changing the global variable 'Ctr', 
  which is active when you run HELPMENU.

  HANDLING KEYSTROKES 
  
  If you decide to trap keystrokes from within a program, you can alert the
  HELPMENU program to the key code by setting flag 64, and leaving the key
  code on the stack.

  Note that the KEY command returns numbers like 16 (for the F key) whereas
  the WAIT command returns 16.1 for the same key, not shifted. If you want
  the key to be processed by HELPMENU, and use the KEY command, then you 
  must add 0.1 to the key code. The following do-nothing program illustrates
  this idea:

  << DO    
      TIME 1 DISP
     UNTIL
      KEY
     END
     0.1 + 64 SF >>

  Note that the program does not reset the softkey area, so maybe -1 WAIT 
  is a better option:

  << "Choose (1-6)"
     1 DISP
     64 SF
     { 1 2 3 4 5 6 }
     -1 TMENU           
     10.1 - 'choice' STO    
     16.1                @ Leave key on stack, saying "go to next page"
  >>

5. THINGS YOU MIGHT WANT TO TRY

   I ended up creating a directory HELPDIR in many of my subdirectories,
   and I used the following program as a "help driver", which uses a choose
   list to pick a help file. CHOOSE is one of the new commands on the G/GX.

   (This program has been included, but won't run until you create the
    directory HELPDIR)

   HELP.DRV        @ Help "driver"
   << 'HELPDIR' DUP 
      IF VTYPE 15 == THEN
        EVAL
        "" 5 TVARS
        1 
        IF CHOOSE THEN 
          RCL UPDIR HELPMENU 
        ELSE
          UPDIR
        END
      ELSE
        DROP
        "HELP needs the subdir HELPDIR" MSGBOX
      END
   >>

   I keep this program in my HOME directory and put the program name as
   an element in all my custom menus.
      

6. NITTY GRITTY STUFF

   HELPMENU doesn't mess up your flags. It restores them when finished. So
   feel free to use flags as "semaphores" between programs in a help list.
   For example, the SAMP.HLP file uses flag 1 as an indicator that the 
   copyright message has already been shown.

   HELPMENU doesn't mess with your path. But your programs should be able
   to with no ill effects.

   HELPMENU doesn't leave "residual" global variables.

7. KNOWN BUGS

   If you have more than ten pages, and are viewing page 10/nn, the last 
   line of pixels of nn gets cut off. This is not a serious restriction,
   though. 

8. END BIT   

   I'm not really sure how much use all of this is, but if you write anything
   *REALLY* neat, please send me a copy. I used this stuff for design aids
   in some of my engineering courses. Students please remember though, it's 
   unethical to cram information into your calculator if you aren't even 
   permitted a cheat sheet in an exam.

Matt Willis
3mbw4@qucdn.queensu.ca (Until 30 April 1994)
