home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource1 / program2 / ahp140.ins / AHELP.DOC next >
Text File  |  1993-09-08  |  19KB  |  428 lines
  1.  
  2.      AHELP.LIB - ADVANCED HELP SYSTEM FOR CLIPPER (SUMMER '87) APPLICATIONS
  3.  Version 1.4                              Copyright (C) 1990-1993, Capella Inc.
  4.  
  5.  
  6.  For a printed copy of this user guide, copy this file to your printer.
  7.  
  8.  
  9.  Introduction
  10.  ------------
  11.  
  12.  Welcome to AHELP!  This help system, for use with your Clipper applications
  13.  (Summer '87), provides both context-sensitive and generalized help windows.
  14.  Features of AHELP version 1 (be sure to see version 3, p.7):
  15.  
  16.  * You control whether help windows have no border, a single-line border, or
  17.    a double-line border.
  18.  
  19.  * You control whether the cross-bars drawn inside the help windows have no
  20.    line, a single line, or a double line.
  21.  
  22.  * AHELP automatically determines the appropriate intersections.
  23.  
  24.  * You control what colors AHELP will use for the help window border, title,
  25.    content, and highlight bar in the help index window.
  26.  
  27.  * You control whether or not the end user has the ability to create or
  28.    modify help windows.
  29.  
  30.  * You control whether or not the help windows have drop shadows.
  31.  
  32.  * AHELP automatically positions the help window immediately below the screen
  33.    position of the input variable (e.g., a GET variable) if the window will fit
  34.    there; otherwise, the window appears immediately above the input variable.
  35.  
  36.  * AHELP provides a help index; whenever any help window is on the screen,
  37.    the user may press F1 to see the help index.  The help index is another
  38.    window with a scrolling alphabetic listing of help subjects.  The user
  39.    uses the cursor control keys to highlight the subject of interest, and
  40.    presses Enter to see the corresponding help window.  The user may also
  41.    type the first letter of the subject to move the highlight bar immediately
  42.    to the first occurrence of that letter.
  43.  
  44.  * AHELP is sensitive to the Clipper environment.  If the cursor is off when
  45.    help is invoked, it will be off when control returns to your application.
  46.    Conversely, if the cursor is on when help is invoked, it will be on when
  47.    control returns to your application.  The same principle applies to colors,
  48.    function keys, insert status, work area, and the status of SET CONSOLE,
  49.    DELETED, ESCAPE, and SCOREBOARD.
  50.  
  51.  * AHELP does not use any "wait state" commands (READ, WAIT, ACCEPT, INPUT,
  52.    MENU TO), to avoid conflicts with any pending GETs.  It uses the INKEY()
  53.    function for all keyboard input, with two exceptions: it calls DBEDIT() for
  54.    the help index window and MEMOEDIT() for displaying/editing help text.
  55.  
  56.  
  57.  
  58.  What do you have to do in order to use AHELP?  Three things:
  59.  
  60.  1.  Insert a call to AHELP in your application with the setup parameters you
  61.      want to use as described in the next section.
  62.  
  63.  2.  Insert the command SET KEY XX TO AHELP in your application.
  64.  
  65.  3.  Compile your application and link, specifying AHELP.LIB as one of the
  66.      LIB files (AHELP requires both CLIPPER.LIB and EXTEND.LIB).
  67.  
  68.  That's all.  The rest is transparent to your application.
  69.  
  70.  
  71.  Setup
  72.  -----
  73.  
  74.  The application must call AHELP with four parameters before starting the user
  75.  interface, in order to initialize the help system.  During initialization,
  76.  AHELP declares four PUBLIC memory variables:
  77.  
  78.     HELPFILE   - the name of the application's help file
  79.     HELPOPTN   - a character string of application options
  80.     HELPCODE   - a character string for use by the application when no input
  81.                  variable is waiting -- AHELP uses the content of `HELPCODE' as
  82.                  its third parameter if the Clipper-passed third parameter is
  83.                  empty
  84.   and
  85.     HELPACTIVE - a logical variable set to true when AHELP is executing, and
  86.                  false otherwise.
  87.  
  88.  Also during initialization, AHELP checks for the existence of the help file
  89.  (and creates it if it is missing), and for the existence of the two index 
  90.  files needed (and creates them if they are missing).
  91.  
  92.  
  93.  Setup Syntax:
  94.  
  95.    DO AHELP WITH <expC1>, <expN>, <expC2>, <expA>
  96.  
  97.  where
  98.  
  99.    <expC1> is the name of the application's Help File (one to eight characters)
  100.     
  101.    <expN>  is any value (ignored by AHELP)
  102.  
  103.    <expC2> is a string of switch values: /Bn/Cn/Dn/En
  104.  
  105.         /Bn defines the help window Border: n=0 means no lines
  106.                                             n=1 means single line
  107.                                             n=2 means double line
  108.  
  109.         /Cn defines the window crossbar:    n=0 means no lines
  110.                                             n=1 means single line
  111.                                             n=2 means double line
  112.  
  113.         /Dn defines drop shadows:           n=0 means shadows are off
  114.                                             n=1 means shadows are on
  115.  
  116.  
  117.         /En defines Edit capability:        n=0 means edit is off
  118.                                             n=1 means edit is on
  119.  
  120.         These switches may appear in any order.  No other switches are defined
  121.         in version 1.x.  If any switch is missing, default values are:
  122.                 B = 2 (double line border)
  123.                 C = 1 (single line crossbar)
  124.                 D = 0 (drop shadows off)
  125.                 E = 1 (edit on)
  126.  
  127.    <expA>  is the name of a four-element character array containing screen
  128.            color values:
  129.         element 1 = foreground/background colors, help window content
  130.         element 2 = foreground/background colors, help index highlight bar
  131.         element 3 = foreground/background colors, help window title and
  132.                     bottom-row message
  133.         element 4 = foreground/background colors, help window border
  134.  
  135.         This array is not needed after AHELP returns.
  136.  
  137.  Example 1:
  138.  
  139.    DECLARE HCOLOR[4]
  140.    HCOLOR[1] = "N/W"    && content
  141.    HCOLOR[2] = "W+/B"   && highlight
  142.    HCOLOR[3] = "B/W"    && title
  143.    HCOLOR[4] = "W+/W"   && border
  144.    DO AHELP WITH "MYAPHELP",0,"/B2/C1/D1/E0",HCOLOR
  145.                      |           |  |  |  |     |
  146.                   filename       |  |  |  |   color
  147.                             double  |  |  |   array
  148.                             border  |  |  |   name
  149.                                     |  |  |
  150.                                single  |  |
  151.                              crossbar  |  |
  152.                                        |  |
  153.                                      drop |
  154.                                   shadows |
  155.                                       on  |
  156.                                           |
  157.                                         edit
  158.                                          off
  159.  
  160.  
  161.  Example 2:
  162.    <declare color array and values as above>
  163.    DO AHELP WITH "MYAPHELP",0,"",HCOLOR        && use default switch options
  164.  
  165.  
  166.  After making this setup call, activate the "hotkey" that will invoke AHELP
  167.  with the SET KEY command.  Examples:
  168.  
  169.    SET KEY 28 TO AHELP         && F1 is the help key
  170.  
  171.    SET KEY 291 TO AHELP        && Alt-H is the help key
  172.  
  173.    SET KEY -9 TO AHELP         && F10 is the help key
  174.  
  175.  
  176.  Execution
  177.  ---------
  178.  
  179.  When the user presses the help key while your application is in any wait
  180.  state, Clipper automatically calls AHELP with three parameters: the name of
  181.  the procedure in control when the key was pressed, the line number that was
  182.  executing, and the name of the wait state input variable.  AHELP uses the 
  183.  first and third parameters only (not all applications are compiled with line
  184.  numbers) to construct a "seek key".  It opens the help file and performs a
  185.  seek for that key.
  186.  
  187.  If the key is found, AHELP opens a help window and displays the help text; the
  188.  window is opened as close as possible to the input variable screen position.
  189.  
  190.  If the key is not found, AHELP opens a smaller help window in the center of
  191.  the screen and notifies the user that no help is available.
  192.  
  193.  Either window will show available options at the bottom of the window: Escape
  194.  to cancel help, F1 to call up the help index, and F4 to edit or create the
  195.  help display (if editing is enabled).
  196.  
  197.  Cancel:  If the user presses Escape, AHELP closes the help window and returns
  198.  to y