home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / screen / intui110 / tui3.hlp < prev    next >
Encoding:
Text File  |  1992-01-19  |  21.4 KB  |  567 lines
  1. `co(4,7);───────────────────────── /// The InTUItion Library ──────────────────────────`co();
  2.  
  3.         The InTUItion library is a small set of macros and functions that allow
  4.     you to use the TUI files created with the construction program.  Very few
  5.     library functions are normally needed by the programmer as InTUItion does
  6.     most of the work for you.  There are a number of undocumented functions
  7.     used internally by InTUItion: if you are a real "power programmer" you may
  8.     wish to examine the source code and see how things are done.
  9.  
  10.                `keyword(InTUItion Macros,/// InTUItion Macros);     `keyword(InTUItion Functions,/// InTUItion Functions);
  11.  
  12. `co(4,7);──────────────────────────── /// InTUItion Macros ────────────────────────────`co();
  13.  
  14.     NOTE: All object's x and y coordinates are offsets from the dialog's
  15.                 upper-left hand corner.  Therefore, if you move a dialog with
  16.                 position_dialog or center_dialog, no other adjustments are required.
  17.                 Furthermore, you can adjust a dialog's parameters on the fly to
  18.                 alter its shape, size, appearance, etc.  EnQue's Hypertext Help
  19.                 Engine does this depending on its size.  The "get" macros below can
  20.                 be used on both sides of a "C" expression. For instance:
  21.  
  22.                 `co(15,?);tmp = get_sldr_pos(&Work_tui, H_SLIDER);
  23.         get_sldr_pos(&Work_tui, H_SLIDER) = 124L;`co();
  24.  
  25.     `co(15,?);get_dlg_wnp(tp, i)`co();    - gets the dialog's window pointer.
  26.     `co(15,?);get_item_type(tp, i)`co();  - gets an object's type (BUTTON, SLIDER, etc).
  27.     `co(15,?);get_item_x(tp, i)`co();     - gets an object's x offset.
  28.     `co(15,?);get_item_y(tp, i)`co();     - gets an object's y offset.
  29.     `co(15,?);get_item_w(tp, i)`co();     - gets an object's width.
  30.     `co(15,?);get_item_h(tp, i)`co();     - gets an object's heigth.
  31.     `co(15,?);get_box_att(tp, i)`co();    - gets a box's normal attribute.
  32.     `co(15,?);get_sldr_pos(tp, i)`co();   - gets a slider's current position.
  33.     `co(15,?);get_str_text(tp, i)`co();   - gets a pointer to a text string's text.
  34.     `co(15,?);get_btn_text(tp, i)`co();   - gets a pointer to a button's text.
  35.     `co(15,?);get_btn_att(tp, i)`co();    - gets a button's normal color attribute.
  36.     `co(15,?);get_check_text(tp, i)`co(); - gets a pointer to a check box's text.
  37.     `co(15,?);get_inp_text(tp, i)`co();   - gets a pointer to an input's text.
  38.     `co(15,?);get_inp_mask(tp, i)`co();   - gets a pointer to an input's mask.
  39.     `co(15,?);get_inp_tplt(tp, i)`co();   - gets a pointer to an input's template.
  40.  
  41.     `co(15,?);set_btn_text(tp,i,s)`co();     - sets a button's text, reallocating if necessary.
  42.     `co(15,?);set_str_text(tp,i,s)`co();     - sets a string's text, reallocating if necessary.
  43.     `co(15,?);set_inp_strs(tp,i,t,m,p)`co(); - sets an input's text, mask, and template,
  44.                                reallocating if necessary.
  45.  
  46.     `co(15,?);is_valid_inx(tp, i)`co();   - returns 1 if "i" is a valid TUI index.
  47.     `co(15,?);is_selected(tp, i)`co();    - returns 1 if the object "i" is currently selected.
  48.     `co(15,?);is_tabbed(tp, i)`co();      - returns 1 if the object "i" is currently tabbed.
  49.  
  50.     `co(15,?);select(tp, i)`co();         - selects the object "i".
  51.     `co(15,?);deselect(tp, i)`co();       - deselects the object "i".
  52.     `co(15,?);tab(tp, i)`co();            - tabs to the object "i".
  53.     `co(15,?);detab(tp, i)`co();          - detabs the object "i".
  54.  
  55. `co(4,7);─────────────────────────── /// InTUItion Functions ──────────────────────────`co();
  56.  
  57.         InTUItion is comprised of many functions.  Few, however, need to be used
  58.     by the programmer.  By design, InTUItion does all of the grunt work,
  59.     freeing you for more important matters.  Listed below are the InTUItion
  60.     functions.  Learning just these few will give you full control over
  61.     InTUItion!
  62.  
  63.     `keyword(A) base_at_cr,/// base_at_cr);
  64.     `keyword(B) draw_item,/// draw_item);
  65.     `keyword(C) refresh_dialog,/// refresh_dialog);
  66.     `keyword(D) draw_dialog,/// draw_dialog);
  67.     `keyword(E) erase_dialog,/// erase_dialog);
  68.     `keyword(F) center_dialog,/// center_dialog);
  69.     `keyword(G) position_dialog,/// position_dialog);
  70.     `keyword(H) do_dialog,/// do_dialog);
  71.     `keyword(I) load_tui,/// load_tui);
  72.     `keyword(J) save_tui,/// save_tui);
  73.     `keyword(K) init_tui,/// init_tui);
  74.     `keyword(L) register_xxxx_tui,/// register_xxxx_tui);
  75.     `keyword(M) end_tui,/// end_tui);
  76.     `keyword(N) free_tui,/// free_tui);
  77.     `keyword(O) set_slider,/// set_slider);
  78.     `keyword(P) file_selected,/// file_selected);
  79.     `keyword(Q) tui_help,/// tui_help);
  80.  
  81.  
  82. `co(15,?);/// base_at_cr`co();   `keyword(source,[T_BASE.C]~base_at_cr);
  83.       Looks for an object under the specified column and row within a dialog
  84.     box.  This is useful where you have buttons in a dialog and need to find
  85.     which button is located at a specific column and row.  This routine is
  86.     used internally by InTUItion.
  87.  
  88. Prototype:
  89.     int base_at_cr( TUI *tuip, int inx, int col, int row );
  90.  
  91. Parameters:
  92. `co(11,?);  TUI *tuip`co();
  93.     A pointer to a TUI structure.                             
  94. `co(11,?);  int  inx`co();
  95.     The index for the dialog box in question.
  96. `co(11,?);  int  col`co();
  97.     The column in question.
  98. `co(11,?);  int  row`co();
  99.     The row in question.
  100.  
  101. Usage:
  102.   int inx;
  103.   TUI tui, TUI *tuip = &tui;
  104.   
  105.   inx = base_at_cr(tuip, 0, 10, 14);  /* find object that 10,14 is within */
  106.  
  107. `co(15,?);/// draw_item`co();   `keyword(source,[T_DLG.C]~draw_item);
  108.       Draws the TUI object indexed by "inx".   Call this to redraw an item
  109.     when needed, such as after changing its position or attribute.
  110.  
  111. Prototype:
  112.     int draw_item( TUI *tuip, int inx );
  113.  
  114. Parameters:
  115. `co(11,?);  TUI *tuip`co();
  116.     A pointer to a TUI structure.                             
  117. `co(11,?);  int  inx`co();
  118.     The index into the TUI for this object. (Use #define name).
  119.  
  120. Usage:
  121.   int inx;
  122.   TUI tui, TUI *tuip = &tui;
  123.   
  124.   inx = draw_item(tuip, OK_BUTTON);
  125.  
  126. `co(15,?);/// refresh_dialog`co();   `keyword(source,[T_DLG.C]~refresh_dialog);
  127.       Redraws all dialog objects and might be used where several items are
  128.     modified and you don't wish to call draw_item for each.  This routine does
  129.     not clear the dialog first; to do this if needed, get the dialog window
  130.     pointer and call wn_clear.
  131.  
  132. Prototype:
  133.     int refresh_dialog( TUI *tuip, int inx );
  134.  
  135. Parameters:
  136. `co(11,?);  TUI *tuip`co();
  137.     A pointer to a TUI structure.                             
  138. `co(11,?);  int  inx`co();
  139.     The index into the TUI for this dialog object. (Use #define name).
  140.  
  141. Usage:
  142.   TUI tui, TUI *tuip = &tui;
  143.   
  144.   /* modify button attributes */
  145.   refresh_dialog(tuip, HELP_DLG);
  146.  
  147.  
  148. `co(15,?);/// draw_dialog`co();   `keyword(source,[T_DLG.C]~draw_dialog);
  149.       Draws the dialog on the screen, allocating space for the window and
  150.     adding it to the UltraWin Window Manager linked list (if used). Do not
  151.     call this routine more than once without calling `keyword(erase_dialog,///erase_dialog);.  To
  152.     redraw a dialog that has been drawn but overwritten, call `keyword(refresh_dialog,/// refresh_dialog);.
  153.  
  154. Prototype:
  155.     int draw_dialog( TUI *tuip, int inx );
  156.  
  157. Parameters:
  158. `co(11,?);  TUI *tuip`co();
  159.     A pointer to a TUI structure.                             
  160. `co(11,?);  int  inx`co();
  161.     The index into the TUI for this dialog object. (Use #define name).
  162.  
  163. Usage:
  164.   TUI tui, TUI *tuip = &tui;
  165.   
  166.   draw_dialog(tuip, HELP_DLG);
  167.   erase_dialog(tuip, HELP_DPG);
  168.  
  169. `co(15,?);/// erase_dialog`co();   `keyword(source,[T_DLG.C]~erase_dialog);
  170.       Erases a dialog drawn on the screen, freeing any space that was
  171.     allocated and removing the window from the UltraWin window manager linked
  172.     list (if used).  Do not call this routine more than once without calling
  173.     `keyword(draw_dialog,/// draw_dialog);.
  174.  
  175. Prototype:
  176.     int erase_dialog( TUI *tuip, int inx );
  177.  
  178. Parameters:
  179. `co(11,?);  TUI *tuip`co();
  180.     A pointer to a TUI structure.                             
  181. `co(11,?);  int  inx`co();
  182.     The index into the TUI for this dialog object. (Use #define name).
  183.  
  184. Usage:
  185.   TUI tui, TUI *tuip = &tui;
  186.   
  187.   draw_dialog(tuip, HELP_DLG);
  188.   erase_dialog(tuip, HELP_DPG);
  189.  
  190. `co(15,?);/// center_dialog`co();   `keyword(source,[T_DLG.C]~center_dialog);
  191.       Centers a dialog on the screen.  Note that this routine does not
  192.     actually redraw the dialog, it merely changes the position; hence it
  193.     should be called before `keyword(draw_dialog,/// draw_dialog);.
  194.  
  195. Prototype:
  196.     int center_dialog( TUI *tuip, int inx );
  197.  
  198. Parameters:
  199. `co(11,?);  TUI *tuip`co();
  200.     A pointer to a TUI structure.                             
  201. `co(11,?);  int  inx`co();
  202.     The index into the TUI for this dialog object. (Use #define name).
  203.  
  204. Usage:
  205.   TUI tui, TUI *tuip = &tui;
  206.   
  207.   center_dialog(tuip, HELP_DLG);
  208.   draw_dialog(tuip, HELP_DLG);
  209.   erase_dialog(tuip, HELP_DPG);
  210.  
  211. `co(15,?);/// position_dialog`co();   `keyword(source,[T_DLG.C]~position_dialog);
  212.       Positions a dialog on the screen at a given column and row.  Note that
  213.     this routine does not actually redraw the dialog, it merely changes the
  214.     position.  Like `keyword(center_dialog,/// center_dialog);, this function should be called
  215.     before drawing the dialog on the screen with `keyword(draw_dialog,/// draw_dialog);.
  216.  
  217. Prototype:
  218.     int position_dialog( TUI *tuip, int inx, int col, int row );
  219.  
  220. Parameters:
  221. `co(11,?);  TUI *tuip`co();
  222.     A pointer to a TUI structure.                             
  223. `co(11,?);  int  inx`co();
  224.     The index into the TUI for this dialog object. (Use #define name).
  225. `co(11,?);  int  col`co();
  226.     The new column position.
  227. `co(11,?);  int  row`co();
  228.     The new row position.
  229.  
  230. Usage:
  231.   TUI tui, TUI *tuip = &tui;
  232.   
  233.   position_dialog(tuip, HELP_DLG, 10, 7);
  234.   draw_dialog(tuip, HELP_DLG);
  235.   erase_dialog(tuip, HELP_DPG);
  236.  
  237. `co(15,?);/// do_dialog`co();   `keyword(source,[T_DLG.C]~do_dialog);
  238.       This is the core function of InTUItion.  Very few other functions will
  239.     ever be used.  This is a testament to the simplicity of interfacing to
  240.     InTUItion.  This routine handles the users interaction with the dialog and
  241.     returns the index of the object selected, modified, entered, etc.
  242.  
  243. Prototype:
  244.     int do_dialog( TUI *tuip, int inx, int mode );
  245.  
  246. Parameters:
  247. `co(11,?);  TUI *tuip`co();
  248.     A pointer to a TUI structure.                             
  249. `co(11,?);  int  inx`co();
  250.     The index into the TUI for this dialog object. (Use #define name).
  251. `co(11,?);  int  mode`co();
  252.     This is a very important parameter.  It's the key to making the
  253.     do_dialog function do exactly what you need and nothing more.  You may
  254.     use the following (defined in T.H):
  255.     `co(15,?);DO_NORMAL`co();       - returns control only after a user selects a dialog
  256.                       object that has been set as an exit, or ESC has been
  257.                       pressed, or the mouse has been clicked off of the
  258.                       dialog box.  This bit makes the usage of inputs modal,
  259.                       in that you must tab or cursor to the input, press
  260.                       <Enter>, type the input and press <Enter> to accept.
  261.  
  262.     `co(15,?);DO_RETURN_EVENT`co(); - returns when the user enters a key or mouse event
  263.                       that the dialog routine does not process.
  264.     `co(15,?);DO_RETURN_TAB`co();    - returns when the Tab key is pressed.
  265.     `co(15,?);DO_RETURN_ENTER`co();  - returns when the Enter key is pressed.
  266.     `co(15,?);DO_RETURN_LEFT`co();  - returns when the left cursor key is pressed.
  267.     `co(15,?);DO_RETURN_RIGHT`co();  - returns when the right cursor key is pressed.
  268.     `co(15,?);DO_RETURN_UP`co();    - returns when the up cursor key is pressed.
  269.     `co(15,?);DO_RETURN_DOWN`co();  - returns when the down cursor key is pressed.
  270.     `co(15,?);DO_RETURN_ARROW`co(); - returns when a user presses any arrow cursor key.
  271.     `co(15,?);DO_RETURN_CMD`co();   - returns when a user presses any of the above.
  272.  
  273.     `co(15,?);DO_INPUT_ADV`co();    - causes the tab to advance when an input is entered.
  274.                       This bit makes forms that contain a lot of input much
  275.                       easier to work, as it is not necessary to <Enter> on
  276.                       each input to begin the entry.  In addition the user
  277.                       will be able to use the <Tab>, <Up> and <Down> keys
  278.                       or the mouse to move around the input fields while
  279.                       actually in "edit input" mode.
  280.  
  281.     NOTE:  Any of the `co(15,?);DO_RETURN_X`co(); dialog defines can be or'ed together to
  282.     combine dialog functionality.  For example, if you wish do_dialog to
  283.     not process the Tab key, but rather return it to you, and return all
  284.     events not processed, you would use `co(15,?);DO_RETURN_EVENT | DO_RETURN_TAB`co();.
  285.     Or if you wish do_dialog to just do normal processing, you could use
  286.     `co(15,?);DO_NORMAL`co();.  For a data entry form type dialog, just use `co(15,?);DO_INPUT_ADV`co();.
  287.     As an extreme example, to make do_dialog return only when the arrow
  288.     cursor keys are pressed, the Enter key, the Tab key, and any other
  289.     event that is not an event that do_dialog will act upon, use
  290.     `co(15,?);DO_RETURN_EVENT | DO_RETURN_ARROW | DO_RETURN_TAB | DO_RETURN_ENTER`co();.
  291.  
  292. Usage:
  293.   TUI tui, TUI *tuip = &tui;
  294.   
  295.   draw_dialog(tuip, HELP_DLG);
  296.   switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  297.     {
  298.         ...
  299.     }
  300.   erase_dialog(tuip, HELP_DPG);
  301.  
  302. `co(15,?);/// load_tui`co();   `keyword(source,[T_LOAD.C]~load_tui);
  303.   Loads a TUI from disk.
  304.  
  305. Prototype:
  306.     int load_tui( TUI *tuip, char *fname );
  307.  
  308. Parameters:
  309. `co(11,?);  TUI  *tuip`co();
  310.     A pointer to a TUI structure.                             
  311. `co(11,?);  char *fname`co();
  312.     The filename to load.
  313.     
  314. Usage:
  315.   TUI tui, TUI *tuip = &tui;
  316.   
  317.   load_tui(tuip, "help.tui");
  318.   init_tui(tuip);
  319.   draw_dialog(tuip, HELP_DLG);
  320.   switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  321.   {
  322.       ...
  323.   }
  324.   erase_dialog(tuip, HELP_DPG);
  325.   end_tui(tuip);
  326.   free_tui(tuip);
  327.  
  328. `co(15,?);/// save_tui`co();   `keyword(source,[T_SAVE.C]~save_tui);
  329.   Saves a TUI to disk.
  330.  
  331. Prototype:
  332.     int save_tui( TUI *tuip, char *fname );
  333.  
  334. Parameters:
  335. `co(11,?);  TUI  *tuip`co();
  336.     A pointer to a TUI structure.                             
  337. `co(11,?);  char *fname`co();
  338.     The filename to save.
  339.     
  340. Usage:
  341.   TUI tui, TUI *tuip = &tui;
  342.   
  343.   load_tui(tuip, "help.tui");
  344.   init_tui(tuip);
  345.   /* modify buttons, positions, colors, etc */
  346.   draw_dialog(tuip, HELP_DLG);
  347.   switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  348.   {
  349.       ...
  350.   }
  351.   erase_dialog(tuip, HELP_DPG);
  352.   save_tui(tuip, "help.tui");
  353.   end_tui(tuip);
  354.   free_tui(tuip);
  355.  
  356. `co(15,?);/// init_tui`co();   `keyword(source,[T_INIT.C]~init_tui */);
  357.       Initializes a TUI after it has been loaded or registered. This routine
  358.     initializes the video mode and mouse and creates a full-screen background
  359.     window.  This is the complement of `keyword(end_tui,/// end_tui);.
  360.  
  361. Prototype:
  362.     int init_tui( TUI *tuip );
  363.  
  364. Parameters:
  365. `co(11,?);  TUI *tuip`co();
  366.     A pointer to a TUI structure.                             
  367.     
  368. Usage:
  369.   TUI tui, TUI *tuip = &tui;
  370.   
  371.   load_tui(tuip, "help.tui");
  372.   init_tui(tuip);
  373.   draw_dialog(tuip, HELP_DLG);
  374.   switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  375.   {
  376.       ...
  377.   }
  378.   erase_dialog(tuip, HELP_DPG);
  379.   end_tui(tuip);
  380.   free_tui(tuip);
  381.  
  382. `co(15,?);/// register_xxxx_tui`co();
  383.       Is used when a linkable TUI file is used instead of a disk loaded TUI.
  384.     The dialog editor will generate a source file with a function named
  385.     register_xxxx_tui where xxxx is the name of the TUI in question.  All you
  386.     need to do is include this file in your project and call the function.
  387.     This method prevents users from modifying the TUIs or deleting the TUI
  388.     files accidently.
  389.  
  390. Prototype:
  391.     int register_xxxx_tui( TUI *tuip );
  392.  
  393. Parameters:
  394. `co(11,?);  TUI *tuip`co();
  395.     A pointer to a TUI structure.  It will be filled out with the
  396.     information in the linked TUI.
  397.  
  398. Usage:
  399.   TUI tui, TUI *tuip = &tui;
  400.   
  401.   register_help_tui(tuip);
  402.   init_tui(tuip);
  403.   draw_dialog(tuip, HELP_DLG);
  404.   switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  405.   {
  406.       ...
  407.   }
  408.   erase_dialog(tuip, HELP_DPG);
  409.   end_tui(tuip);
  410.   free_tui(tuip);
  411.  
  412. `co(15,?);/// end_tui`co();   `keyword(source,[T_INIT.C]~end_tui);
  413.       Ends a TUI, removes the full screen window and restores the video and
  414.     mouse modes.  This is the complement of `keyword(init_tui,/// init_tui);.
  415.  
  416. Prototype:
  417.     int end_tui( TUI *tuip );
  418.  
  419. Parameters:
  420. `co(11,?);  TUI *tuip`co();
  421.     A pointer to a TUI structure.                             
  422.     
  423. Usage:
  424.   TUI tui, TUI *tuip = &tui;
  425.   
  426.   load_tui(tuip, "help.tui");
  427.   init_tui(tuip);
  428.   draw_dialog(tuip, HELP_DLG);
  429.   switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  430.   {
  431.       ...
  432.   }
  433.   erase_dialog(tuip, HELP_DPG);
  434.   end_tui(tuip);
  435.  
  436. `co(15,?);/// free_tui`co();   `keyword(source,[T_BASE.C]~free_tui);
  437.       Frees all objects within a TUI.  This function should be called when all
  438.     operations with a TUI are complete.
  439.  
  440. Prototype:
  441.     int free_tui( TUI *tuip );
  442.  
  443. Parameters:
  444. `co(11,?);  TUI *tuip`co();
  445.     A pointer to a TUI structure.                             
  446.     
  447. Usage:
  448.   TUI tui, TUI *tuip = &tui;
  449.   
  450.   load_tui(tuip, "help.tui");
  451.   init_tui(tuip);
  452.   draw_dialog(tuip, HELP_DLG);
  453.   switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  454.   {
  455.       ...
  456.   }
  457.   erase_dialog(tuip, HELP_DPG);
  458.   end_tui(tuip);
  459.   free_tui(tuip);
  460.  
  461. `co(15,?);/// set_slider`co();   `keyword(source,[T_UTIL.C]~set_slider);
  462.       Sets the slider variables.  A slider can range from 0 to total-1.  The
  463.     arrow incs/decs by 1, a page incs/decs by page_amt, and sliding the grab
  464.     box adjusts the position between 0 and total-1. Be sure to use long
  465.     variables here or unexpected results will occur!
  466.  
  467. Prototype:
  468.     set_slider( TUI *tuip, int inx, long position, long page_amt, long total );
  469.  
  470. Parameters:
  471. `co(11,?);  TUI *tuip`co();
  472.     A pointer to a TUI structure.                             
  473. `co(11,?);  int  inx`co();
  474.     The index into the TUI for this dialog object. (Use #define name).
  475. `co(11,?);  long position`co();
  476.     The initial offset of the slider (be sure to use long ints). 
  477. `co(11,?);  long page_amt`co();
  478.     The amount the slider incs/decs when paged (be sure to use long ints).
  479. `co(11,?);  long total`co();
  480.     The largest value - 1 the slider can have (be sure to use long ints). 
  481.     
  482. Usage:
  483.   TUI tui, TUI *tuip = &tui;
  484.   
  485.   load_tui(tuip, "help.tui");
  486.   init_tui(tuip);
  487.   draw_dialog(tuip, HELP_DLG);
  488.   switch( do_dialog(tuip, HELP_DLG, DO_NORMAL) )
  489.   {
  490.       ...
  491.   }
  492.   erase_dialog(tuip, HELP_DPG);
  493.   end_tui(tuip);
  494.   free_tui(tuip);
  495.  
  496. `co(15,?);/// file_selected`co();   `keyword(source,[T_FSEL.C]~file_selected);
  497.       Pulls up InTUItion's file selector and waits for the user to select a
  498.     file.  The function will return 1 if a file was selected, or 0 if the
  499.     selection was cancelled.  If a file was selected, the function will fill
  500.     out the strings passed with information about the path and filename.
  501.  
  502. Prototype:
  503.     file_selected(char *wildcard, char *path, char *filename, char *fullname);
  504.  
  505. Parameters:
  506. `co(11,?);  char *wildcard`co();
  507.     The initial wildcard to use.  For example, to use the file selector
  508.     to select a "C" file, pass a wildcard of "*.C";
  509. `co(11,?);  char *path`co();
  510.     The default path to show.  If you wish, just pass a null string
  511.     and the function will fill it out with the current path.
  512. `co(11,?);  char *filename`co();
  513.     The default filename.  Simply pass a null string, or if you wish
  514.     pass a default filename.
  515. `co(11,?);  char *fullname`co();
  516.     This final parameter is what makes the file selector so easy to use.
  517.     It is simply the drive, path and filename put together, ready for
  518.     use in a file i/o function (like open).  This keeps you from having
  519.     to concatenate the returned path and filename yourself.
  520.     
  521. Usage:
  522.   WINDOW *wnp;
  523.   char path[81], filename[13], fullname[81];  
  524.   
  525.   if ( file_selected("*.c", path, filename, fullname) )
  526.   {
  527.     mv_cs(0, 0, wnp);
  528.     wn_printf(wnp, "The filename is <%s>, fullname <%s>",filename, fullname);
  529.   }
  530.  
  531. `co(15,?);/// tui_help`co();   `keyword(source,[T_HELP.C]~tui_help);
  532.       Pulls up InTUItion's linkable help engine, and allows the user to browse
  533.     through the help.  This is sometimes preferable over using the stand alone
  534.     ENQHELP.EXE help engine.  Parameters to this function allow you to specify
  535.     size, position, startup file, optional search string, and more.  Refer to
  536.     the help engine documentation for information on how to create your own
  537.     help files.
  538.  
  539. Prototype:
  540.     tui_help( int sx, int sy, int ex, int ey, char *fname,
  541.                         char *search_str, int mode );
  542.  
  543. Parameters:
  544. `co(11,?);  int sx, sy, ex, ey`co();
  545.     The coordinates of the top-left and bottom-right corners of the help
  546.     window.  These parameters allow you to change placement and size of
  547.     the window.
  548. `co(11,?);  char *fname`co();
  549.     The default file to show.
  550. `co(11,?);  char *search_str`co();
  551.     The initial search string.  This parameter is what makes the help
  552.     engine context-sensitive.  Just use "" if you wish to begin at the
  553.     start of the file.
  554. `co(11,?);  int mode`co();
  555.     This is the chain mode, which tells the engine that if the search
  556.     ends up on a hypertext keyword, to press <Enter> for the user.  This
  557.     allows the engine to "chain" until the desired topic is reached,
  558.     even across multiple files.
  559.     
  560. Usage:
  561.   tui_help(1, 1, 79, 24, "SOURCE.C", "", 0);
  562.   /* get the file SOURCE.C, and place the cursor at the top line */
  563.  
  564.   tui_help(1, 1, 79, 24, "MYFILE.HLP", "Introduction", 1);
  565.   /* get the file MYFILE.HLP, search for the text "Introduction", and if
  566.      it is a keyword <Enter> on it */
  567.