Help/Message System


 TCXL has always had a context-sensitive Help System that works hand-in-hand
 with TCXL's  other high-level systems.  With Version 6, the Help System has
 been extended  to become  what is now called the Help/Message System.  This
 new system gives you the powerful capability of keeping all literal strings
 in your  program (not  just help  text!) in a separate, compressed, indexed
 file.     These  externalized   strings,  which  can  contain  TCXL  format
 characters, printf()  escape sequences,  or even  binary data,  are  easily
 retrieved in  a variety  of ways.  There are several distinct advantages to
 using externalized  strings in  your programs:  text strings  used in  help
 screens, menus, or anywhere else can be edited or translated into different
 languages without  changing your code, your program will use much less data
 segment space, and program text could even be changed by someone other than
 the programmer.

 There are  several other  new features  in TCXL's  Help  System.  The  help
 display now includes five mouse-selectable buttons called PgUp, PgDn, Prev,
 Index, and  Quit.   PgUp and  PgDn work identically to the keys of the same
 names. Quit works like the [Esc] key. Prev brings you to the last displayed
 help topic.  When the Index button is pressed,  all help topics with cross-
 reference labels  are  automatically  collected  into  a  sorted  list  and
 displayed.   The user  can navigate through this list and use it to jump to
 any topic.

 The Help  System operates on the principle of a current help category and a
 help category  stack.  Both require some explaining before you begin to use
 them.

 The current  help category  is the  one that  will be  used when  the  user
 presses the  help key.   It  can be set by one of several ways.  The direct
 way is  for you  to explicitly  set it by calling HlpSet().  There are also
 indirect ways  that the  current help  category can be set.  Windows, input
 fields, and  menu items  each have  individual help  categories as  part of
 their record.   If  you were  to activate  a window  which has its own help
 category, then  that would  become the  current help  category. During  the
 processing of  input fields and menus, each time you move to a new field or
 menu item,  the current  help category  is set to whatever the field/item's
 help category  is, even  if that  category is zero (empty). This means that
 input forms  and menus  overwrite what  was in  the current  help  category
 before the form/menu began processing.

 To keep  from losing  the current  help category  during the  processing of
 forms and  menus, you  need to  be able  to save  the current help category
 during that period.  This is where you can use the help stack.  To save the
 current help category, push it onto the stack with HlpCur().  When you need
 to retrieve  it, pop it back off of the stack using HlpPop().  The category
 popped off  of the stack then becomes the current help category.  This help
 stack is  a LIFO  (Last In  First Out)  stack  and  holds  up  to  20  help
 categories.

 When the  help key  is pressed (or when the HlpGet() function is called) by
 the user,  TCXL's help  processor will search the help file for the current
 help category.  If the current help category is zero (empty), then the help
 category from  the top  of the  stack will be used.  This is where the help
 stack comes in handy.  It allows you to have a background help category for
 menu items and fields that don't have help categories of their own.  Before
 processing the  form or menu, simply push the background help category onto
 the stack.

 When the  help category  is found  in the help file, the corresponding help
 text will  be displayed  on the  screen in  the help window.  The following
 keys are active:

 Key Event      Result
 ---------      ------
 [PgDn]:........Pressed once, moves cursor to bottom left of help screen.  If
                pressed a second time, and the text for the displayed topic
                extends past the end of the help window, the next screen will
                be displayed.
 [PgUp]:........Pressed once, moves cursor to top left of help screen.  If
                pressed a second time, and the text for the displayed topic
                extends past the top of the help window, the previous screen
                will be displayed.
 [Home]:........Same as [PgUp].
 [End]:.........Same as [PgDn].
 [LeftArrow]:...Moves cursor one character to the left.  If this results in
                the cursor being on top of a cross-reference, the cross-
                reference will be highlighted.
 [RightArrow]:..Same as [LeftArrow], except that the cursor moves one
                character to the right.
 [UpArrow]:.....Same as [LeftArrow], except that the cursor moves up one row.
 [DownArrow]:...Same as [RightArrow], except that the cursor moves down one
                row.
 [Enter]:.......If the cursor is on a cross-reference, it displays the help
                screen for the cross-referenced topic.
 [Esc]:.........Closes the help window and returns to the previous task.
 [Tab]:.........Moves cursor to next cross-reference and highlights it.  If
                cursor is currently on last cross-reference, cursor is moved
                to first cross-reference.
 [Shift-Tab]:...Moves cursor to previous cross-reference and highlights it.
                If cursor is currently on first cross-reference, cursor is
                moved to last cross-reference.
 [Alt-F1]:......Displays previously displayed help topic.
 [Alt-I]:.......Displays help index.

 The mouse behaves as follows when a help window is displayed:

   Mouse Event                                                   Result
   -----------                                                   ------
   Click on PgUp button                             Same as [PgUp] key.
   Click on PgDn button                             Same as [PgDn] key.
   Click on Prev button                           Same as [Alt-F1] key.
   Click on Index button                           Displays Help Index.
   Click on Quit button                              Same as [Esc] key.
   Click on Cross-Ref.                 Displays the help screen for the
                                       cross-referenced topic.
   Right click                                       Same as [Esc] key.

 Also, if  the topic  is longer than a single help screen, the mouse can use
 the scroll bar as it can in any scrollable window.

 During help  processing, all  keys attached to functions via KbndSet() will
 be disabled  to avoid  conflict with  the help system.  If you wish to have
 defined keys  available during  help processing,  you can define them using
 KbndSet() in  the open function specified in the HlpDef() function.  If you
 define any  keys in  the open  function, you  will not  need to worry about
 freeing them  because the  help processor  will free  any user-defined keys
 before exiting help.

 The size  and placement of the help window are adjustable.  The help window
 size by  default is  19 rows by 64 columns centered on the screen. This can
 be changed  using HlpWind().    The  HlpWind()  function  sets  the  screen
 coordinates to  be used  when opening the help window and can be called any
 time after  HlpDef().   If you ever want to disengage the help system, just
 call HlpOff().