home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / utils / hdmiv.zip / CLIPHELP.COM / AHELP.DOC next >
Text File  |  1990-02-21  |  18KB  |  416 lines
  1.  
  2.      AHELP.LIB - ADVANCED HELP SYSTEM FOR CLIPPER (SUMMER '87) APPLICATIONS
  3.  Version 1.3                                   Copyright (C) 1990, 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.  provides both context-sensitive and generalized help windows.  The major
  14.  features included with version 1 of AHELP (be sure to see version 2, 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   - a character string containing the name of your 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.  
  114.         /Dn defines drop shadows:           n=0 means shadows are off
  115.                                             n=1 means shadows are on
  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.  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 
  128.            screen color values:
  129.                 element 1 = the foreground/background colors of the help window
  130.                             content
  131.                 element 2 = the foreground/background colors of the help index
  132.                             highlight bar
  133.                 element 3 = the foreground/background colors of the help window
  134.                             title and bottom-row message
  135.                 element 4 = the foreground/background colors of the help window
  136.                             border
  137.  
  138.         This array is not needed after AHELP returns.
  139.  
  140.  Example 1:
  141.  
  142.    DECLARE HCOLOR[4]
  143.    HCOLOR[1] = "N/W"    && content
  144.    HCOLOR[2] = "W+/B"   && highlight
  145.    HCOLOR[3] = "B/W"    && title
  146.    HCOLOR[4] = "W+/W"   && border
  147.    DO AHELP WITH "MYAPHELP",0,"/B2/C1/D1/E0",HCOLOR
  148.  
  149.                      |           |  |  |  |     |
  150.                   filename       |  |  |  |   color
  151.                             double  |  |  |   array
  152.                             border  |  |  |   name
  153.                                     |  |  |
  154.                                single  |  |
  155.                              crossbar  |  |
  156.                                        |  |
  157.                                      drop |
  158.                                   shadows |
  159.                                       on  |
  160.                                           |
  161.                                         edit
  162.                                          off
  163.  
  164.  
  165.  Example 2:
  166.    <declare color array and values as above>
  167.    DO AHELP WITH "MYAPHELP",0,"",HCOLOR        && use default switch options
  168.  
  169.  
  170.  
  171.  After making this setup call, activate the "hotkey" that will invoke AHELP
  172.  with the SET KEY command.  Examples:
  173.  
  174.    SET KEY 28 TO AHELP         && F1 is the help key
  175.  
  176.    SET KEY 291 TO AHELP        && Alt-H is the help key
  177.  
  178.    SET KEY -9 TO AHELP         && F10 is the help key
  179.  
  180.  Execution
  181.  ---------
  182.  
  183.  When the user presses the help key while your application is in any wait
  184.  state, Clipper automatically calls AHELP with three parameters: the name of
  185.  the procedure in control when the key was pressed, the line number that was
  186.  executing, and the name of the wait state input variable.  AHELP uses the 
  187.  first and third parameters only (not all applications are compiled with line
  188.  numbers) to construct a "seek key".  It opens the help file and performs a
  189.  seek for that key.
  190.  
  191.  If the key is found, AHELP opens a help window and displays the help text; the
  192.  window is opened as close as possible to the input variable screen position.
  193.  
  194.  If the key is not found, AHELP opens a smaller help window in the center of
  195.  the screen and notifies the user that no help is available.
  196.  
  197.  Either window will show available options at the bottom of the window: Escape
  198.  to cancel help, F1 to call up the help index, and F4 to edit or create the
  199.  help display (if editing is enabled).
  200.  
  201.  Cancel:  If the user presses Escape, AHELP closes the help window and returns
  202.  to your application.
  203.  
  204.  Help Index:  If the user presses F1, AHELP closes the help window, opens a
  205.  help index window, and displays a scrolling list of help subjects.  The user
  206.  may press Escape again (AHELP will close the window and return), or move the
  207.  highlight bar to the desired subject and press Enter to select that subject.
  208.  AHELP will close the window and use the subject as the new seek key.
  209.  
  210.  Edit:  If the user presses F4, AHELP turns on the cursor and allows the user
  211.  to modify or add text until F2 is pressed (to save any changes).  The user
  212.  may press Escape to abort this process, which restores the original help text
  213.  (if any) and cancels the edit process.  If the user chooses to save changes,
  214.  AHELP prompts for a new title for the help text, and for a new index subject;
  215.  both are optional.  Any title is converted to upper case and centered when the
  216.  help window is recalled, prefixed with the words "Help on".  If there is no
  217.  title, AHELP provides the word "Help" centered at the top of the window.  If
  218.  the user specifies an index subject, AHELP adds it to the help index (below).
  219.  
  220.  Editing keys available during creation or modification of help text are those
  221.  provided by MEMOEDIT.
  222.  
  223.  AHELP is not intended for recursion; if the public variable HELPACTIVE is true
  224.  when AHELP is invoked, AHELP immediately returns.  Otherwise, it sets variable
  225.  HELPACTIVE to true and continues.  When AHELP is done, it resets HELPACTIVE
  226.  to false.
  227.  
  228.  
  229.  Help Index
  230.  ----------
  231.  
  232.  The help index is basically an alphabetized table of contents for generalized
  233.  help (although context-sensitive subjects may also be listed).  The scrolling
  234.  highlight bar is used to point to the subject desired; the cursor keys move
  235.  the highlight bar, and typing a character moves the highlight bar to the first
  236.  occurrence of that character, if any.  Pressing the Enter key selects the
  237.  highlighted entry, and the Escape key cancels the help index.
  238.  
  239.  If edit is enabled, the user may press F4 to edit the highlighted entry,
  240.  Delete to delete the highlighted entry, or Insert to add a new entry.
  241.  
  242.  Edit:  If the user presses F4, AHELP opens a small window containing the index
  243.  entry, turns on the cursor, and prompts for any changes.  Pressing Enter saves
  244.  the entry; pressing Escape cancels the edit operation.
  245.  
  246.  Delete:  If the user presses Delete, AHELP opens a dialog box to confirm that
  247.  deletion is desired.  The dialog box contains two choices: "Cancel" and
  248.  "Delete".  The cursor keys switch between these choices and Enter selects the
  249.  choice that is highlighted; alternatively, typing the first letter of either
  250.  choice selects that choice.
  251.  
  252.  Insert:  If the user presses Insert, AHELP opens a small window containing a
  253.  blank index entry, turns on the cursor, and prompts for the new index entry.
  254.  Pressing Enter saves the new entry; pressing Escape cancels the add operation.
  255.  
  256.  
  257.  
  258.  Structure of Help File
  259.  ----------------------
  260.  
  261.  AHELP uses a .DBF (and associated .DBT) for help displays.  The name of the
  262.  help file is determined by the application and passed to AHELP as a parameter
  263.  in the setup call.  If AHELP is unable to find the help file in the current
  264.  directory, it creates both the .DBF and .DBT files.
  265.  
  266.  The record layout is:
  267.       Field  Field Name  Type       Width Dec  Usage
  268.           1  HELPKEY     Character     20      Seek Key (see below)
  269.           2  HELPTITL    Character     30      Title for help display
  270.           3  HELPTEXT    Memo          10      Content of help display
  271.           4  HELPSUBJ    Character     30      Subject for help index
  272.           5  HELPTROW    Numeric        2      Window top row        [reserved]
  273.           6  HELPLCOL    Numeric        2      Window left column    [reserved]
  274.           7  HELPNROW    Numeric        2      No. of window rows    [reserved]
  275.           8  HELPNCOL    Numeric        2      No. of window columns [reserved]
  276.       ** Total **                      99
  277.  
  278.  The Seek Key (field HELPKEY) consists of two concatenated ten-character
  279.  fields: the first ten characters are the name of the calling procedure,
  280.  AHELP's first parameter; and the second ten characters are the name of the
  281.  input variable, AHELP's third parameter.
  282.  
  283.  
  284.  There are two index files created and maintained by AHELP: HELPKEY.N*X and
  285.  HELPSUBJ.N*X.  The filename extension, .NDX or .NTX, is determined by 
  286.  whether you link your application with Nantucket's NDX.OBJ or not.  
  287.  
  288.  Since AHELP adds four to the number of file handles in use, you may need to
  289.  increase FILES= in CONFIG.SYS and SET CLIPPER=Fnn in AUTOEXEC.BAT.  This will
  290.  be determined by how many files your application tries to have open at one
  291.  time.
  292.  
  293.  
  294.  Reserved Names
  295.  --------------
  296.  
  297.  All function and procedure names in AHELP.LIB begin with the four letters
  298.  "HELP" followed by at least four more characters, except for the "AHELP"
  299.  procedure itself.  Your application should avoid naming any functions or
  300.  procedures in a similar fashion, to eliminate any potential conflict at link
  301.  time.  All variables used internally by AHELP are declared PRIVATE, with the
  302.  exception of the four PUBLIC variables HELPACTIVE, HELPCODE, HELPFILE, and
  303.  HELPOPTN (all of which also begin with the four letters "HELP").
  304.  
  305.  
  306.  
  307.  Version 2
  308.  ---------
  309.  
  310.  Version 2 of AHELP adds three major features:
  311.  
  312.  *  Network capability.  In this version, AHELP opens the help file for 
  313.     shared use only unless an update is required.  Then it locks the record
  314.     long enough for the update, and immediately unlocks the record.
  315.  
  316.  *  "Drag" or move the help window around the screen and save its new position.
  317.     You control whether or not this feature is enabled.  If it is enabled, it
  318.     is activated by pressing F5.
  319.  
  320.  *  Expand or reduce the size of the help window and save its new shape.  You
  321.     control whether or not this feature is enabled.  If it is enabled, it is
  322.     activated by pressing F6.
  323.  
  324.  Both the move and resize features store the new help window coordinates in the
  325.  help file record, so the window will be opened in its new place or shape when
  326.  recalled.
  327.  
  328.  
  329.  Future steps
  330.  ------------
  331.  
  332.  What features would you like to see in AHELP?  Integrated mouse support? 
  333.  Control over which function keys perform which tasks?  Access to the internal
  334.  windowing routines?  Something else?  What other products are you interested
  335.  in?  Let us know your interests; we may add them to our product development
  336.  wish list.
  337.  
  338.  
  339.  Registration
  340.  ------------
  341.  
  342.  The registration fee for AHELP is $50.00 for a single-PC license.  A site
  343.  license is $400.00, and a corporate license is $1000.00.  The last page of
  344.  this user guide is a ready-to-mail registration form.
  345.  
  346.  Send your check or money order for the appropriate license to:
  347.                    MicroFox
  348.                    P.O. Box 447
  349.                    Richfield, OH 44286-0447
  350.                    U.S.A.
  351.  
  352.  We will send you version 2 of AHELP, and add your name(s) to our list of users
  353.  for future upgrade notices and other offers.  Specify diskette size(s).
  354.  
  355. <End of AHELP.DOC>
  356.  
  357.  
  358.                        AHELP REGISTRATION AND ORDER FORM
  359.  
  360.    Send to:        MicroFox Co.                  P.O. # _________________
  361.                    P.O. Box 447
  362.                    Richfield, OH                   DATE _________________
  363.                    44286-0447  U.S.A.
  364.  
  365.    ______________________________________________________________________
  366.  
  367.  
  368.      Single-User License ..................................... $50 U.S.
  369.  
  370.         Number of Single-User Licenses  _________    SUBTOTAL  $_________ 
  371.  
  372.  
  373.      Site License (unlimited use per site) ............... $400.00 U.S.
  374.  
  375.         Number of Site Licenses         _________    SUBTOTAL  $_________ 
  376.  
  377.  
  378.      Corporate License (unlimited use within enterprise): $1000.00 U.S.
  379.  
  380.         Number of Corporate Licenses    _________    SUBTOTAL  $_________ 
  381.  
  382.  
  383.      Each License includes a master disk. 
  384.  
  385.                                                LICENSES TOTAL  $_________
  386.    ______________________________________________________________________
  387.  
  388.  
  389.      Ohio residents add 5.5% sales tax              SALES TAX  __________
  390.  
  391.  
  392.      Shipping charges:  U.S.A. ...... $2 each        SHIPPING  __________
  393.                         Canada ...... $3 each                          
  394.                         All others .. $5 each  
  395.                                                         TOTAL  __________
  396.      
  397.    ______________________________________________________________________
  398.  
  399.  
  400.                  Name ___________________________________________________
  401.  
  402.               Company ___________________________________________________
  403.  
  404.               Address ___________________________________________________
  405.  
  406.                       ___________________________________________________
  407.  
  408.                       ___________________________________________________
  409.  
  410.                 Phone ___________________________________________________
  411.  
  412.  
  413.        Diskette media:     _____ 5.25" acceptable     _____ 3.5" required
  414.  
  415.  
  416.