home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / FOXPRO / VLIST110 / VLIST3.DOC < prev    next >
Text File  |  1992-09-25  |  37KB  |  1,258 lines
  1.           VList Library V1.1 -- (c) 1992, Jayson R. Minard
  2.                                           P.O. Box 1306
  3.                                           Westminster, CO 80030-1306 (USA)
  4. ===============================================================================
  5.                              LIBRARY REFERENCE
  6. ===============================================================================
  7.  
  8.                      GLOBAL VARIABLES and MISC #DEFINEs
  9. -------------------------------------------------------------------------------
  10.  
  11. These variables should be declared as external.  The VLIST.HDR file contains
  12. the correct definition.  They are listed here with their TYPE and definition.
  13. The variables __color_std and __color_enhcd are in the FORCE library and
  14. are not declared in VLIST.HDR but are used in some META-Functions.  Therefore
  15. they are described here.
  16.  
  17.   BYTE  __color_std
  18.  
  19.       This is used as the color for all normal elements in a list when the
  20.       highlight bar is NOT on the element.
  21.  
  22.   BYTE  __color_enhcd
  23.  
  24.       This is used as the color for ALL elements in a list when the highlight
  25.       bar is ON the element.
  26.  
  27.   BYTE  __color_skip
  28.  
  29.       The color for non-highlighted SKIPped elements.  These can never
  30.       be highlighted so this will be the only color they are displayed in.
  31.  
  32.   BYTE  __color_hit
  33.  
  34.       The color for non-highlighted HIT elements.
  35.  
  36.   BYTE  __color_bar
  37.  
  38.       The color for the scroll-bar shaded area.
  39.  
  40.   BYTE  __color_tab
  41.  
  42.       The color for the scroll-bar tabs.
  43.  
  44.   BYTE  __color_hi_std
  45.  
  46.       This is the color used for any character following the __EMBED_CHAR
  47.       when displayed using VLIST_SAY().  This is when the item is NOT
  48.       highlighted.
  49.  
  50.   BYTE  __color_hi_enhcd
  51.  
  52.       Same as __color_hi_std except when the item IS highlighted.
  53.  
  54.   INT  __scroll_offset
  55.  
  56.       From the right border of a pick area, or of a menu, this is the
  57.       offset to display the scroll-bar.  Default is 1.
  58.  
  59.   CHAR( 1 )  __embed_char
  60.  
  61.       The character to signify an imbedded color change.  Any character
  62.       following this, when using VLIST_SAY(), will be displayed in the
  63.       __color_hi_std or __color_hi_enhcd colors.
  64.  
  65.   #DEFINES:
  66.  
  67.      &JL_NORMAL   - a normal element status
  68.      &JL_SKIP     - a skipped element status
  69.      &JL_HIT      - a hit element status
  70.      &JL_HIDDEN   - a hidden element status
  71.  
  72.      &JL_DEFAULT  - use the default color for an element
  73.  
  74.      &JL_FORWARD  - use with VLIST_SKIP() to determine forward direction
  75.      &JL_BACKWARD - use with VLIST_SKIP() to determine backward direction
  76.  
  77. ===============================================================================
  78.                       PROCEDURE/FUNCTION Reference
  79.  
  80. -------------------------------------------------------------------------------
  81. VList_Add()
  82. -------------------------------------------------------------------------------
  83.  
  84. PROTOTYPE:
  85.  
  86.   FUNCTION LOGICAL Vlist_Add PROTOTYPE
  87.     PARAMETERS VALUE LONG handle,;
  88.                CONST CHAR item_string_contents
  89.  
  90. RETURN VALUE:
  91.  
  92.   LOGICAL <success>
  93.  
  94.   <success> value of .T. indicates that there was enough memory to create
  95.   this list element, a .F. indicates failure.
  96.  
  97. DESCRIPTION:
  98.  
  99.   Adds an item to an existing list.  If the list is not initialized then
  100.   a run-time error will occur.  This is identical to VLIST_APPEND() except
  101.   that the status and color parameters are assumed to be &JL_NORMAL and
  102.   &JL_DEFAULT.
  103.  
  104. EXAMPLE:
  105.  
  106.   handle = VList_Init( 40 )
  107.   VList_Add( handle, "Jayson was HERE!" )
  108.  
  109. -------------------------------------------------------------------------------
  110. VList_Append()
  111. -------------------------------------------------------------------------------
  112.  
  113. PROTOTYPE:
  114.  
  115.   FUNCTION LOGICAL Vlist_Append PROTOTYPE
  116.     PARAMETERS VALUE LONG handle,;       
  117.                VALUE UINT item_status,;  
  118.                VALUE INT  item_color,;   
  119.                CONST CHAR item_string_contents
  120.  
  121. RETURN VALUE:
  122.  
  123.   LOGICAL <success>
  124.  
  125.   <success> value of .T. indicates that there was enough memory to create
  126.   this list element, a .F. indicates failure.
  127.  
  128. DESCRIPTION:
  129.  
  130.   This adds an element to an EXISTING list.  If the list does not exist,
  131.   a run-time error will result.  The element consists of:
  132.  
  133.      item_status    -  Either &JL_NORMAL, &JL_SKIP, &JL_HIT, or &JL_HIDDEN
  134.  
  135.      item_color     -  Either &JL_DEFAULT, or a valid FORCE color
  136.  
  137.      item_string    -  The CHAR contents of the string.  If this is greater
  138.                        than the max width of the list, then the string is
  139.                        truncated.
  140.  
  141. EXAMPLE:
  142.  
  143.   handle = VList_Init( 40 )
  144.   VList_Append( handle, &JL_NORMAL, &JL_DEFAULT, "Jayson was HERE!" )
  145.   VList_Append( handle, &JL_NORMAL, &BLACK_YELLOW, "this is yellow" )
  146.  
  147. -------------------------------------------------------------------------------
  148. VList_BOL()
  149. -------------------------------------------------------------------------------
  150.  
  151. PROTOTYPE:
  152.  
  153.   FUNCTION LOGICAL Vlist_BOL PROTOTYPE
  154.     PARAMETERS VALUE LONG handle
  155.  
  156. RETURN VALUE:
  157.  
  158.   LOGICAL <at_bottom>
  159.  
  160.   <at_bottom> is .T. if the internal list pointer is past the last element
  161.   in the list, else it is .F.
  162.  
  163. DESCRIPTION:
  164.  
  165.   Is similar to the database related A_EOF() and returns a logical .T.
  166.   if the list's internal pointer is PAST the end (Bottom) of the list.
  167.  
  168. EXAMPLE:
  169.  
  170.   ? "The list in normal order is:"
  171.   ?
  172.   VList_Top( handle )
  173.   DO WHILE .NOT. VList_BOL( handle )
  174.     ? VList_CStr( handle )
  175.     VList_Skip( handle, &JL_FORWARD )
  176.   ENDDO
  177.  
  178. -------------------------------------------------------------------------------
  179. VList_Bottom()
  180. -------------------------------------------------------------------------------
  181.  
  182. PROTOTYPE:
  183.  
  184.   PROCEDURE Vlist_Bottom PROTOTYPE
  185.     PARAMETERS VALUE LONG handle
  186.  
  187. RETURN VALUE:
  188.  
  189.   - none -
  190.  
  191. DESCRIPTION:
  192.  
  193.   Moves the internal list pointer to the last element in the list.  The list
  194.   number is now equal to VLIST_MAX().
  195.  
  196. EXAMPLE:
  197.  
  198.   VList_Bottom( handle )
  199.   ? "The last element is:  " + VList_CStr( handle )
  200.  
  201. -------------------------------------------------------------------------------
  202. VList_CEdit()
  203. -------------------------------------------------------------------------------
  204.  
  205. PROTOTYPE:
  206.  
  207.   FUNCTION LOGICAL Vlist_CEdit PROTOTYPE
  208.     PARAMETERS VALUE LONG handle,;
  209.                CONST CHAR edit_str
  210.  
  211. RETURN VALUE:
  212.  
  213.   LOGICAL <succeeded>
  214.  
  215.   <succeeded> indicates whether the edit worked or not.
  216.  
  217. DESCRIPTION:
  218.  
  219.   This allows you to change the string contents of the CURRENT element.
  220.  
  221. EXAMPLE:
  222.  
  223.   temp_str = VList_CStr( handle )
  224.   temp_str = temp_str + " - Fish"
  225.   VList_CEdit( handle, temp_str )
  226.  
  227. -------------------------------------------------------------------------------
  228. VList_CGet_Color()
  229. -------------------------------------------------------------------------------
  230.  
  231. PROTOTYPE:
  232.  
  233.   FUNCTION INT Vlist_CGet_Color PROTOTYPE
  234.     PARAMETERS VALUE LONG handle
  235.  
  236. RETURN VALUE:
  237.  
  238.   INT <current_color>
  239.  
  240.   <current_color> is the current color contents of the element.
  241.  
  242. DESCRIPTION:
  243.  
  244.   Returns the color of the CURRENT element.  This can either
  245.   be &JL_DEFAULT or a valid FORCE color.  
  246.  
  247. EXAMPLE:
  248.  
  249.   old_color = VList_CGet_Color( handle )
  250.   new_color = old_color + 128   && make the sucker blink
  251.   VList_CSet_Color( handle, new_color )
  252.  
  253. -------------------------------------------------------------------------------
  254. VList_CGet_Status()
  255. -------------------------------------------------------------------------------
  256.  
  257. PROTOTYPE:
  258.  
  259.   FUNCTION UINT Vlist_Cget_Status PROTOTYPE
  260.     PARAMETERS VALUE LONG handle
  261.  
  262. RETURN VALUE:
  263.  
  264.   UINT <current_status>
  265.  
  266.   <current_status> is the current status contents of the element.
  267.  
  268. DESCRIPTION:
  269.  
  270.   Returns the status contents of the CURRENT element that the internal
  271.   list pointer is pointing to.  This can be one of the following macros:
  272.  
  273.      &JL_NORMAL
  274.      &JL_SKIP
  275.      &JL_HIT
  276.      &JL_HIDDEN
  277.  
  278. EXAMPLE:
  279.  
  280.   IF VList_CGet_Status( handle ) <> &JL_NORMAL
  281.     VList_CDelete( handle )
  282.   ENDIF
  283.  
  284. -------------------------------------------------------------------------------
  285. VList_CReplace()
  286. -------------------------------------------------------------------------------
  287.  
  288. PROTOTYPE:
  289.  
  290.   FUNCTION LOGICAL Vlist_CReplace PROTOTYPE
  291.     PARAMETERS VALUE LONG handle,;
  292.                VALUE UINT item_status,;
  293.                VALUE INT  item_color,;
  294.                CONST CHAR new_str
  295.  
  296. RETURN VALUE:
  297.  
  298.   LOGICAL <succeeded>
  299.  
  300.   <succeeded> indicates whether the replacement worked (.T.) or failed (.F.)
  301.  
  302. DESCRIPTION:
  303.  
  304.   This is similar to VLIST_CEDIT() except that it changes ALL of the element's
  305.   contents including the status, color, and string contents.  This works
  306.   for the CURRENT element.
  307.  
  308. EXAMPLE:
  309.  
  310.   *- replace the current element with a new dude.
  311.   VList_CReplace( handle, &JL_NORMAL, &JL_DEFAULT, "New Guy!!!" )
  312.  
  313. -------------------------------------------------------------------------------
  314. VList_CSet_Color()
  315. -------------------------------------------------------------------------------
  316.  
  317. PROTOTYPE:
  318.   
  319.   FUNCTION LOGICAL Vlist_Cset_Color PROTOTYPE
  320.     PARAMETERS VALUE LONG handle,;
  321.                VALUE INT  new_color
  322.  
  323. RETURN VALUE:
  324.  
  325.   LOGICAL <succeeded>
  326.  
  327.   <succeeded> indicates whether the SET was successful.
  328.  
  329. DESCRIPTION:
  330.  
  331.   Sets the color contents for the CURRENT element.  This can either
  332.   be &JL_DEFAULT or any valid FORCE color, such as those in COLORS.HDR.
  333.  
  334. EXAMPLE:
  335.  
  336.   IF LEFT( VList_CStr( handle ), 5 ) = "<DIR>"
  337.     VList_CSet_Color( handle, &BLACK_LIGHT_CYAN )
  338.   ELSE
  339.     VList_CSet_Color( handle, &JL_DEFAULT )
  340.   ENDIF
  341.  
  342. -------------------------------------------------------------------------------
  343. VList_CSet_Status()
  344. -------------------------------------------------------------------------------
  345.  
  346. PROTOTYPE:
  347.  
  348.   FUNCTION LOGICAL Vlist_Cset_Status PROTOTYPE
  349.     PARAMETERS VALUE LONG handle,;
  350.                VALUE UINT new_status
  351.  
  352. RETURN VALUE:
  353.  
  354.   LOGICAL <succeeded>
  355.  
  356.   <succeeded> indicates whether or not the SET occured without error.  An
  357.   error usually indicates that the element doesn't exist.
  358.  
  359. DESCRIPTION:
  360.  
  361.   Sets the CURRENT element's status contents which can be one of the 
  362.   following macros:
  363.  
  364.    &JL_NORMAL
  365.    &JL_SKIP
  366.    &JL_HIT
  367.    &JL_HIDDEN
  368.  
  369. EXAMPLE:
  370.  
  371.   IF LEFT( VList_CStr( handle ), 1 ) = "$"
  372.     VList_CSet_Status( handle, &JL_SKIP )
  373.   ELSE
  374.     VList_CSet_Status( handle, &JL_NORMAL )
  375.   ENDIF
  376.  
  377. -------------------------------------------------------------------------------
  378. VList_CStr()
  379. -------------------------------------------------------------------------------
  380.  
  381. PROTOTYPE:
  382.  
  383.   FUNCTION CHAR Vlist_CStr PROTOTYPE
  384.     PARAMETERS VALUE LONG handle
  385.  
  386. RETURN VALUE:
  387.  
  388.   CHAR <contents>
  389.  
  390.   <contents> is the string contents of the element.
  391.  
  392. DESCRIPTION:
  393.  
  394.   Returns the string contents of the current element pointed to by the
  395.   internal list pointer.
  396.  
  397. EXAMPLE:
  398.  
  399.   ? "Current Element:"
  400.   ? "  " + VList_CStr( handle )
  401.  
  402. -------------------------------------------------------------------------------
  403. VList_Default_Key_Handler()
  404. -------------------------------------------------------------------------------
  405.  
  406. PROTOTYPE:
  407.  
  408.   FUNCTION INT VLIST_Default_Key_Handler PROTOTYPE
  409.     PARAMETERS VALUE LONG list_handle,;    
  410.                VALUE UINT current_element,;   
  411.                      UINT mouse_status,;     
  412.                VALUE UINT mouse_row,;      
  413.                VALUE UINT mouse_col,;           
  414.                       INT pick_key,; 
  415.                VALUE UINT top_element_displayed,;    
  416.                VALUE UINT last_element_displayed,;   
  417.                VALUE UINT upper_row_of_pick_area,;             
  418.                VALUE UINT upper_col,;            
  419.                VALUE UINT lower_row,;             
  420.                VALUE UINT lower_col               
  421.  
  422. RETURN VALUE:
  423.  
  424.   INT <action>
  425.  
  426.   <action> is a return that informs the pick routine how to act.  These
  427.   values are descibed in VLIST2.DOC under the keyboard handler section.
  428.  
  429. DESCRIPTION:
  430.  
  431.   The keyboard handler interprets all mouse and keyboard activity and
  432.   responds to the call function with codes that correspond to cursor
  433.   movement, element selection, mouse movement, and the flow of the
  434.   pick.  The VLIST_DEFAULT_KEY_HANDLER() is the default that can
  435.   be used with VLIST_PICK().  The name of the function is passed to 
  436.   these functions without the parentheses.
  437.  
  438. EXAMPLE:
  439.  
  440.   VList_SomeFunction( handle, 1, 1, 22, 50, VList_Default_Key_Handler, .T. )
  441.  
  442.  
  443. -------------------------------------------------------------------------------
  444. VList_Default_Menu_Handler()
  445. -------------------------------------------------------------------------------
  446.  
  447. PROTOTYPE:
  448.  
  449.   FUNCTION INT VList_Default_Menu_Handler PROTOTYPE
  450.     PARAMETERS VALUE LONG list_handle,;
  451.                VALUE UINT current_element,;   
  452.                      UINT mouse_status,;     
  453.                VALUE UINT mouse_row,;           
  454.                VALUE UINT mouse_col,;           
  455.                       INT pick_key,;       
  456.                VALUE UINT top_element_displayed,;    
  457.                VALUE UINT last_element_displayed,;   
  458.                VALUE UINT upper_row_of_pick_area,;             
  459.                VALUE UINT upper_col,;             
  460.                VALUE UINT lower_row,;             
  461.                VALUE UINT lower_col
  462.  
  463. RETURN VALUE:
  464.  
  465.   INT <action>
  466.  
  467.   <action> is a return that informs the pick routine how to act.  These
  468.   values are descibed in VLIST2.DOC under the keyboard handler section.
  469.  
  470. DESCRIPTION:
  471.  
  472.   The keyboard handler interprets all mouse and keyboard activity and
  473.   responds to the call function with codes that correspond to cursor
  474.   movement, element selection, mouse movement, and the flow of the
  475.   pick.  The VLIST_DEFAULT_MENU_HANDLER() is the default that can
  476.   be used with VLIST_POPUP() and VLIST_PULLDOWN().  The name of
  477.   the function is passed to these functions without the parentheses.
  478.  
  479. EXAMPLE:
  480.  
  481.   VList_SomeFunction( handle, 1, 1, 22, 50, VList_Default_Menu_Handler, .T. )
  482.  
  483. -------------------------------------------------------------------------------
  484. VList_Default_Prompt_Handler()
  485. -------------------------------------------------------------------------------
  486.  
  487. PROTOTYPE:
  488.  
  489.   FUNCTION INT VLIST_Default_Prompt_Handler PROTOTYPE
  490.     PARAMETERS VALUE LONG list_handle,;
  491.                VALUE UINT current_element,;
  492.                      UINT mouse_status,;
  493.                VALUE UINT mouse_row,;
  494.                VALUE UINT mouse_col,;
  495.                       INT pick_key,;
  496.                VALUE UINT top_element_in_list_for_this_system,;
  497.                VALUE UINT last_element_in_list_for_this_system
  498.  
  499. RETURN VALUE:
  500.  
  501.   INT <action>
  502.  
  503.   <action> is a return that informs the pick routine how to act.  These
  504.   values are descibed in VLIST2.DOC under the keyboard handler section.
  505.  
  506. DESCRIPTION:
  507.  
  508.   The keyboard handler interprets all mouse and keyboard activity and
  509.   responds to the call function with codes that correspond to cursor
  510.   movement, element selection, mouse movement, and the flow of the
  511.   pick.  The VLIST_DEFAULT_PROMPT_HANDLER() is the default that can
  512.   be used with VLIST_PROMPT().  The name of the function is passed to 
  513.   these functions without the parentheses.
  514.  
  515. EXAMPLE:
  516.  
  517.   VList_SomeFunction( handle, 1, 1, 22, 50, VList_Default_Key_Handler, .T. )
  518.  
  519. -------------------------------------------------------------------------------
  520. VList_Edit()
  521. -------------------------------------------------------------------------------
  522.  
  523. PROTOTYPE:
  524.  
  525.   FUNCTION LOGICAL Vlist_Edit PROTOTYPE
  526.     PARAMETERS VALUE LONG handle,;
  527.                VALUE UINT which_element,;
  528.                CONST CHAR edit_str
  529.  
  530. RETURN VALUE:
  531.  
  532.   LOGICAL <succeeded>
  533.  
  534.   <succeeded> indicates whether the edit worked or not.
  535.  
  536. DESCRIPTION:
  537.  
  538.   This allows you to change the string contents of an already existing
  539.   element 'which_element'.  The list pointer is NOT moved to this 
  540.   element from the current element.
  541.  
  542. EXAMPLE:
  543.  
  544.   temp_str = VList_Str( handle, some_element_number )
  545.   temp_str = temp_str + " - Fish"
  546.   VList_Edit( handle, some_element_number, temp_str )
  547.  
  548. -------------------------------------------------------------------------------
  549. VList_Get_Color()
  550. -------------------------------------------------------------------------------
  551.  
  552. PROTOTYPE:
  553.  
  554.   FUNCTION INT Vlist_Get_Color PROTOTYPE
  555.     PARAMETERS VALUE LONG handle,;
  556.                VALUE UINT which_element
  557.  
  558. RETURN VALUE:
  559.  
  560.   INT <current_color>
  561.  
  562.   <current_color> is the current color contents of the element.
  563.  
  564. DESCRIPTION:
  565.  
  566.   Returns the color of the element 'which_element'.  This can either
  567.   be &JL_DEFAULT or a valid FORCE color.  The current element pointer
  568.   is NOT moved to this element.
  569.  
  570. EXAMPLE:
  571.  
  572.   old_color = VList_Get_Color( handle, some_poor_element )
  573.   new_color = old_color + 128   && make the sucker blink
  574.   VList_Set_Color( handle, some_poor_element, new_color )
  575.  
  576. -------------------------------------------------------------------------------
  577. VList_Get_Status()
  578. -------------------------------------------------------------------------------
  579.  
  580. PROTOTYPE:
  581.  
  582.   FUNCTION UINT Vlist_Get_Status PROTOTYPE
  583.     PARAMETERS VALUE LONG handle,;
  584.                VALUE UINT which_element
  585.  
  586. RETURN VALUE:
  587.  
  588.   UINT <current_status>
  589.  
  590.   <current_status> is the current status contents of the element.
  591.  
  592. DESCRIPTION:
  593.  
  594.   Returns the status contents of the element 'which_element'.  This
  595.   can be one of the following macros:
  596.  
  597.      &JL_NORMAL
  598.      &JL_SKIP
  599.      &JL_HIT
  600.      &JL_HIDDEN
  601.  
  602.   The current list pointer is not moved to this element, it will be
  603.   the 'same as it ever was' (sounds like a Talking Heads song?).
  604.  
  605. EXAMPLE:
  606.  
  607.   IF VList_Get_Status( handle, some_element ) <> &JL_NORMAL
  608.     VList_Delete( handle, some_element )
  609.   ENDIF
  610.  
  611. -------------------------------------------------------------------------------
  612. VList_Get_StrLen()
  613. -------------------------------------------------------------------------------
  614.  
  615. PROTOTYPE:
  616.  
  617.   FUNCTION UINT Vlist_Get_StrLen PROTOTYPE
  618.     PARAMETERS VALUE LONG handle
  619.  
  620. RETURN VALUE:
  621.  
  622.   UINT <max_length>
  623.  
  624.   <max_length> is the maximum length an element can be in this list.
  625.  
  626. DESCRIPTION:
  627.  
  628.   Returns the max element length from a specific list.  This is the same
  629.   value used when initializing the list.
  630.  
  631. EXAMPLE:
  632.  
  633.   handle = VList_Init( 33 )
  634.   IF VList_Get_StrLen( handle ) <> 33
  635.     ? "something is wrong!"
  636.   ENDIF
  637.  
  638. -------------------------------------------------------------------------------
  639. VList_Goto()
  640. -------------------------------------------------------------------------------
  641.  
  642. PROTOTYPE:
  643.  
  644.   FUNCTION LOGICAL Vlist_Goto PROTOTYPE
  645.     PARAMETERS VALUE LONG handle,;
  646.                VALUE UINT which_element
  647.  
  648. RETURN VALUE:
  649.  
  650.   LOGICAL <succeeded>
  651.  
  652.   <succeeded> is .F. if the element number does not exist, else a .T. is
  653.   returned if the goto was successful.
  654.  
  655. DESCRIPTION:
  656.  
  657.   This moves the internal list pointer to the element defined by
  658.   'which_element'.
  659.  
  660. EXAMPLE:
  661.  
  662.   VList_Goto( handle, VList_Max( handle ) - 5 )
  663.   ? "The 5th to last element is:  " + Vlist_CStr( handle )
  664.  
  665. -------------------------------------------------------------------------------
  666. VList_Init()
  667. -------------------------------------------------------------------------------
  668.  
  669. PROTOTYPE:
  670.  
  671.   FUNCTION LONG Vlist_Init PROTOTYPE
  672.     PARAMETERS VALUE UINT max_string_length
  673.  
  674. RETURN VALUE:
  675.  
  676.   LONG <handle>
  677.  
  678.   <handle> is a pointer to the VLIST internal memory structure for a list.
  679.   This structure has information that can be checked to ensure that the list
  680.   is intact.
  681.  
  682.   A return value of 0 signifies that the memory could not be allocated.
  683.  
  684. DESCRIPTION:
  685.  
  686.   Initializes a VLIST with elements that will have a set length of
  687.   'max_string_length'.  This list will then be active until either
  688.   a QUIT, program exit, or VLIST_CLEAR() is called.
  689.  
  690.   The minimum 'max_string_length' should be 1, while the max is 254.
  691.  
  692. EXAMPLE:
  693.  
  694.   handle = VList_Init( 40 )
  695.   IF handle = 0
  696.     ? "error"
  697.     QUIT
  698.   ENDIF
  699.  
  700. -------------------------------------------------------------------------------
  701. VList_Is_Init()
  702. -------------------------------------------------------------------------------
  703.  
  704. PROTOTYPE:
  705.  
  706.   FUNCTION LOGICAL Vlist_Is_Init PROTOTYPE
  707.     PARAMETERS VALUE LONG handle
  708.  
  709. RETURN VALUE:
  710.  
  711.   LOGICAL <is_init>
  712.  
  713.   <is_init> is .T. if the list has been initialized using VLIST_INIT() and
  714.   has not been cleared, else it is .F.
  715.  
  716. DESCRIPTION:
  717.  
  718.   This can be used to determine if a list is still or has ever been
  719.   initialized.
  720.  
  721. EXAMPLE:
  722.  
  723.   some_list = VList_Init( 50 )
  724.   IF VList_Is_Init( some_list )
  725.     ? "this guy should be initialized now"
  726.   ELSE
  727.     ? "error, the list didn't init!"
  728.   ENDIF
  729.   VList_Clear( some_list )
  730.   ? "The following should be .F."
  731.   ? VList_Is_Init( some_list )
  732.  
  733. -------------------------------------------------------------------------------
  734. VList_Max()
  735. -------------------------------------------------------------------------------
  736.  
  737. PROTOTYPE:
  738.  
  739.   FUNCTION UINT Vlist_Max PROTOTYPE
  740.     PARAMETERS VALUE LONG handle
  741.  
  742. RETURN VALUE:
  743.  
  744.   UINT <elements>
  745.  
  746.   <elements> is the number of elements in the list pointed to by 'handle'.
  747.  
  748. DESCRIPTION:
  749.  
  750.   Returns the number of elements in a list.  This can return 0 for an
  751.   empty list.  If the list is not initialized, it will cause a run-time
  752.   error.
  753.  
  754. EXAMPLE:
  755.  
  756.   how_many = VList_Max( handle )
  757.   VList_Goto( handle, how_many )
  758.   ? "The last element is:  " + VList_CStr( handle )
  759.  
  760. -------------------------------------------------------------------------------
  761. VList_Number()
  762. -------------------------------------------------------------------------------
  763.  
  764. PROTOTYPE:
  765.  
  766.   FUNCTION UINT Vlist_Number PROTOTYPE
  767.     PARAMETERS VALUE LONG handle
  768.  
  769. RETURN VALUE:
  770.  
  771.   UINT <current_item>
  772.  
  773.   <current_item> is the current item number in the list.
  774.  
  775. DESCRIPTION:
  776.  
  777.   This returns the current item number that the internal list pointer is
  778.   pointing to.  If it is 0, then we are at VLIST_TOL(), if it is past
  779.   VLIST_MAX() then we are at VLIST_BOL().
  780.  
  781. EXAMPLE:
  782.  
  783.   old_element = VList_Number( handle )
  784.   VList_Goto( handle, new_element )
  785.   ? VList_CStr( handle )
  786.   VList_Goto( handle, old_element )
  787.  
  788. -------------------------------------------------------------------------------
  789. VList_Pick()
  790. -------------------------------------------------------------------------------
  791.  
  792. PROTOTYPE:
  793.  
  794.   FUNCTION UINT Vlist_PICK PROTOTYPE
  795.     PARAMETERS VALUE LONG    handle,;                 
  796.                VALUE INT     upper_row,;              
  797.                VALUE INT     upper_col,;
  798.                VALUE INT     lower_row,;
  799.                VALUE INT     lower_col,;
  800.                      UINT    top_element_displayed,;            
  801.                VALUE UINT    initial_element_selected,;        
  802.                VALUE UINT    first_element_allowed,;  
  803.                VALUE UINT    last_element_allowed,;
  804.                VALUE UINT    left_string_marker_for_partial_string,;     
  805.                VALUE UINT    right_string_marker_for_partial_string,;    
  806.                VALUE UINT    number_of_columns,;      
  807.                VALUE UINT    spaces_between_columns,; 
  808.                UNTYPED       keyboard_handler_proc,;       
  809.                VALUE LOGICAL display_only,;           
  810.                VALUE LOGICAL scroll_bar,;             
  811.                VALUE LOGICAL return_on_left_right_keystroke,;
  812.                VALUE LOGICAL is_mouse_present,;
  813.                VALUE LOGICAL allow_embedded
  814.  
  815.  
  816. RETURN VALUE:
  817.  
  818.   UINT <element>
  819.  
  820.   <element> is the element that the cursor was on when the list was exitted.
  821.   Check LASTKEY() to determine if it was a selection (&K_ENTER was LASTKEY)
  822.   or abort (&K_ESC was LASTKEY).
  823.  
  824.   A return value of 0 indicates an error with the list.
  825.  
  826. DESCRIPTION:
  827.  
  828.   Displays a list range in multiple columns (Max 10).  You can also set
  829.   the 'left_string_marker...' and 'right_string_marker...' parameters to
  830.   a start character and end character within the string that will be
  831.   displayed.  Therefore a partial string will be displayed from each
  832.   element.  This can also be used to make the window look to scroll left
  833.   and right when the elements are longer than the window is wide.  To do
  834.   this, set 'return_on_left_right...' to .T., then when the list is
  835.   exitted and the LASTKEY() value was either left or right, increment
  836.   or decrement these markers and then call VLIST_PICK() again.  If these
  837.   markers are set at 0, then the pick-list will execute quicker since
  838.   no sub-string is selected.
  839.  
  840.   You can limit the list elements displayed by using the 
  841.   'first_element_allowed' and 'last_element_allowed' to specify a range
  842.   of elements that can be selected.  If these are set to 0, then they
  843.   will default to 1 and VLIST_MAX() respectively.
  844.  
  845.   The default keyboard handler that can be used is VLIST_DEFAULT_KEY_HANDLER().
  846.  
  847.   If 'display_only' is .T., then the intial view of the list will be displayed
  848.   and then immediately exitted.  If 'scroll_bar' is .T., a scroll bar will
  849.   appear at 'lower_right' + __scroll_offset.  'allow_embedded' decides whether
  850.   VLIST_SAY() is used instead of @SAY for displaying elements.
  851.  
  852. EXAMPLE:  - shows left/right scrolling imitation!
  853.  
  854.   * List <handle> is init to 132 earlier and filled
  855.   * If mouse is present, 'is_mouse' is .T. from earlier code
  856.  
  857.   top_element = 1
  858.   selection   = 1
  859.   left_mark   = 1
  860.   right_mark  = 40
  861.   keep_going  = .T.
  862.   aborted     = .F.
  863.  
  864.   DO WHILE keep_going
  865.     selection = VList_Pick( handle, 5, 5, 23, 44, top_element, selection,;
  866.                             0, 0, left_mark, right_mark, 1, 0,;
  867.                             VList_Default_Key_Handler,;
  868.                             .F., .T., .T., is_mouse, .F. )
  869.     IF selection = 0
  870.       keep_going = .F.
  871.       LOOP
  872.     ENDIF
  873.  
  874.     temp = LASTKEY()
  875.     DO CASE
  876.       CASE temp = &K_LEFT
  877.         IF left_mark > 1
  878.           left_mark  = left_mark + 1
  879.           right_mark = right_mark + 1
  880.         ENDIF
  881.       CASE temp = &K_RIGHT
  882.         IF right_mark < VList_Str_Len( handle )
  883.           left_mark  = left_mark + 1
  884.           right_mark = right_mark + 1
  885.         ENDIF
  886.       CASE temp = &K_ENTER
  887.         keep_going = .F.
  888.       CASE temp = &K_ESC
  889.         selection  = 0
  890.         aborted    = .T.
  891.         keep_going = .F.
  892.     ENDCASE
  893.   ENDDO
  894.  
  895.   IF selection = 0
  896.     IF aborted
  897.       ? "No element selected"
  898.     ELSE
  899.       ? "ERROR!"
  900.     ENDIF
  901.   ELSE
  902.     ? "Element selected: ", selection
  903.   ENDIF
  904.  
  905. -------------------------------------------------------------------------------
  906. VList_Replace()
  907. -------------------------------------------------------------------------------
  908.  
  909. PROTOTYPE:
  910.  
  911.   FUNCTION LOGICAL Vlist_Replace PROTOTYPE
  912.     PARAMETERS VALUE LONG handle,;
  913.                VALUE UINT which_element,;
  914.                VALUE UINT item_status,;
  915.                VALUE INT  item_color,;
  916.                CONST CHAR new_str
  917.  
  918. RETURN VALUE:
  919.  
  920.   LOGICAL <succeeded>
  921.  
  922.   <succeeded> indicates whether the replacement worked (.T.) or failed (.F.)
  923.  
  924. DESCRIPTION:
  925.  
  926.   This is similar to VLIST_EDIT() except that it changes ALL of the element's
  927.   contents including the status, color, and string contents.  This will work
  928.   for the element specified in 'which_element'.  The internal element pointer 
  929.   is not moved to this element, it stays where it was.
  930.  
  931. EXAMPLE:
  932.  
  933.   *- replace element 15 with a new dude.
  934.   VList_Replace( handle, 15, &JL_NORMAL, &JL_DEFAULT, "New Guy!!!" )
  935.  
  936. -------------------------------------------------------------------------------
  937. VList_Set_Color()
  938. -------------------------------------------------------------------------------
  939.  
  940. PROTOTYPE:
  941.  
  942.   FUNCTION LOGICAL Vlist_Set_Color PROTOTYPE
  943.     PARAMETERS VALUE LONG handle,;
  944.                VALUE UINT which_element,;
  945.                VALUE INT  new_color
  946.  
  947. RETURN VALUE:
  948.  
  949.   LOGICAL <succeeded>
  950.  
  951.   <succeeded> indicates whether the SET was successful.
  952.  
  953. DESCRIPTION:
  954.  
  955.   Sets the color contents for the element 'which_element'.  This can either
  956.   be &JL_DEFAULT or any valid FORCE color, such as those in COLORS.HDR.
  957.  
  958.   The current element pointer is not moved to this element.
  959.  
  960. EXAMPLE:
  961.  
  962.   IF LEFT( VList_Str( handle, some_dude ), 5 ) = "<DIR>"
  963.     VList_Set_Color( handle, some_dude, &BLACK_LIGHT_CYAN )
  964.   ELSE
  965.     VList_Set_Color( handle, some_dude, &JL_DEFAULT )
  966.   ENDIF
  967.  
  968. -------------------------------------------------------------------------------
  969. VList_Set_Status()
  970. -------------------------------------------------------------------------------
  971.  
  972. PROTOTYPE:
  973.  
  974.   FUNCTION LOGICAL Vlist_Set_Status PROTOTYPE
  975.     PARAMETERS VALUE LONG handle,;
  976.                VALUE UINT which_element,;   
  977.                VALUE UINT new_status        
  978.  
  979. RETURN VALUE:
  980.  
  981.   LOGICAL <succeeded>
  982.  
  983.   <succeeded> indicates whether or not the SET occured without error.  An
  984.   error usually indicates that the element doesn't exist.
  985.  
  986. DESCRIPTION:
  987.  
  988.   Sets the element pointed to by 'which_element' status contents which 
  989.   can be one of the following macros:
  990.  
  991.    &JL_NORMAL
  992.    &JL_SKIP
  993.    &JL_HIT
  994.    &JL_HIDDEN
  995.  
  996.   The internal list pointer does not move to this element, it stays at the
  997.   current location.
  998.  
  999. EXAMPLE:
  1000.  
  1001.   IF LEFT( VList_Str( handle, which_dude ), 1 ) = "$"
  1002.     VList_Set_Status( handle, which_dude, &JL_SKIP )
  1003.   ELSE
  1004.     VList_Set_Status( handle, which_dude, &JL_NORMAL )
  1005.   ENDIF
  1006.  
  1007. -------------------------------------------------------------------------------
  1008. VList_Simple()
  1009. -------------------------------------------------------------------------------
  1010.  
  1011. PROTOTYPE:
  1012.  
  1013.   FUNCTION UINT Vlist_SIMPLE PROTOTYPE
  1014.     PARAMETERS VALUE LONG    list_handle,;
  1015.                VALUE UINT    upper_row,;
  1016.                VALUE UINT    upper_col,;
  1017.                VALUE UINT    lower_row,;
  1018.                VALUE UINT    lower_col,;
  1019.                VALUE UINT    start_element,;
  1020.                VALUE UINT    first_element_allowed,;
  1021.                VALUE UINT    last_element_allowed,;
  1022.                VALUE LOGICAL display_only,;
  1023.                VALUE LOGICAL return_on_left_or_right_keystroke
  1024.  
  1025. RETURN VALUE:
  1026.  
  1027.   UINT <element>
  1028.  
  1029.   <element> is the element that the cursor was on when the list was exitted.
  1030.   Check LASTKEY() to determine if it was a selection (&K_ENTER was LASTKEY)
  1031.   or abort (&K_ESC was LASTKEY).
  1032.  
  1033.   A return value of 0 indicates an error with the list.
  1034.  
  1035. DESCRIPTION:
  1036.  
  1037.   Displays a list range from 'first_element_allowed' to 'last_element_allowed'
  1038.   and allows one item to be selected by pressing the return key.  If <ESC>
  1039.   was pressed then the pick-list is terminated.  If 'display_only' is .T.,
  1040.   then the list is displayed and then immediately exitted.  If
  1041.   'return_on_left...' is .T. then a <RIGHT> or <LEFT> cursor key will
  1042.   terminate the list.  This can then be used to display parallel lists
  1043.   where these keys move between them.
  1044.  
  1045.   For 'first_element_allowed', if a 0 is sent, it is adjusted to be the
  1046.   first element in the list (1).  For 'last_element_allowed', if a 0
  1047.   is passed as the parameter, it will be set to VLIST_MAX().
  1048.  
  1049. EXAMPLE:
  1050.  
  1051.   handle = VList_Init( 40 )
  1052.   DO WHILE .NOT. A_EOF( my_dbf )
  1053.     VList_Add( handle, my_dbf->name )
  1054.     IF my_dbf->age > 45
  1055.       VList_CSet_Color( handle, over_hill_color )
  1056.     ENDIF
  1057.  
  1058.     !my_dbf SKIP
  1059.   ENDDO
  1060.  
  1061.   FILL( 4, 3, 19, 47, &double_box, " ", border_color, __color_std, 6 )
  1062.   selection = VList_Simple( handle, 5, 5, 17, 44, selection, 1, 0,;
  1063.                             .F., .F. )
  1064.  
  1065. -------------------------------------------------------------------------------
  1066. VList_Skip()
  1067. -------------------------------------------------------------------------------
  1068.  
  1069. PROTOTYPE:
  1070.  
  1071.   PROCEDURE Vlist_Skip PROTOTYPE
  1072.     PARAMETERS VALUE LONG handle,;
  1073.                VALUE UINT which_way    
  1074.  
  1075. RETURN VALUE:
  1076.  
  1077.   - none -
  1078.  
  1079. DESCRIPTION:
  1080.  
  1081.   Moves the internal list pointer either forward or backward 1 element.  If
  1082.   the element is at the end of the list, it is moved past the end of the list
  1083.   and VLIST_BOL() would return .T.  If the element is at the top of the list
  1084.   and it is moved back 1, then it is move to non-existant element 0 and
  1085.   VLIST_TOL() would return .T.
  1086.  
  1087.   For the 'which_way' parameter, you can substitute &JL_FORWARD or
  1088.   &JL_BACKWARD.
  1089.  
  1090. EXAMPLE:
  1091.  
  1092.   last_found = 0
  1093.   DO WHILE SUBSTR( VList_CStr( handle ), 20, 5 ) = "80003"
  1094.     last_found = VList_Number( handle )
  1095.     VList_Skip( handle, &JL_FORWARD )
  1096.   ENDDO
  1097.   IF last_found <> 0
  1098.     VList_GOTO( handle, last_found )
  1099.     ? "The last element using the zipcode 80003 is #" + I_STR( ;
  1100.                 VList_Number( handle ) )
  1101.   ENDIF
  1102.  
  1103. -------------------------------------------------------------------------------
  1104. VList_Sort()
  1105. -------------------------------------------------------------------------------
  1106.  
  1107. PROTOTYPE:
  1108.  
  1109.   PROCEDURE Vlist_Sort PROTOTYPE
  1110.     PARAMETERS VALUE LONG handle,;
  1111.                VALUE UINT start_element,;
  1112.                VALUE UINT end_element
  1113.  
  1114. RETURN VALUE:
  1115.  
  1116.   - none -
  1117.  
  1118. DESCRIPTION:
  1119.  
  1120.   Sorts a list alpha-numerically by using the entire string contents as
  1121.   the key.  This can work on either the entire list by sending either the
  1122.   last element number in 'end_element' or a 0.  A 0 in 'start_element' is 
  1123.   changed to a 1, and in 'end_element' is changed to a VLIST_MAX().
  1124.  
  1125. EXAMPLE:
  1126.  
  1127.   *- sort part of the list
  1128.   VList_Sort( handle, 10, 50 )
  1129.   *- sort the first part
  1130.   VList_Sort( handle, 1, 9 )
  1131.   *- sort to the end
  1132.   VList_Sort( handle, 51, 0 )
  1133.  
  1134. -------------------------------------------------------------------------------
  1135. VList_Sort_SubStr()
  1136. -------------------------------------------------------------------------------
  1137.  
  1138. PROTOTYPE:
  1139.  
  1140.   PROCEDURE Vlist_Sort_SubStr PROTOTYPE
  1141.     PARAMETERS VALUE LONG handle,;
  1142.                VALUE UINT start_element,;
  1143.                VALUE UINT end_element,;
  1144.                VALUE UINT start_sub_string,;
  1145.                VALUE UINT end_sub_string
  1146.  
  1147. RETURN VALUE:
  1148.  
  1149.   - none -
  1150.  
  1151. DESCRIPTION:
  1152.  
  1153.   Sorts a list alpha-numerically by using only a partial string from the
  1154.   element as the key.  This can work on either the entire list by sending
  1155.   either the last element number in 'end_element' or a 0.  A 0 in
  1156.   'start_element' is changed to a 1, and in 'end_element' is changed to
  1157.   a VLIST_MAX().
  1158.  
  1159.   The substring should be the start character and end character in the
  1160.   element.  The start and end of 3 and 8 for the following string would
  1161.   produce "FRED M".
  1162.  
  1163.     "I FRED MACMURRAY BEING OF SOUND MIND"
  1164.  
  1165. EXAMPLE:
  1166.  
  1167.   *- sort the whole list, for the 2nd to 13th character.  This is a
  1168.   *  list containing say, filenames.  The first character is used to
  1169.   *  mark a filename, so I don't want to sort based on it!
  1170.   VList_Sort_SubStr( handle, 0, 0, 2, 13 )
  1171.  
  1172. -------------------------------------------------------------------------------
  1173. VList_Str()
  1174. -------------------------------------------------------------------------------
  1175.  
  1176. PROTOTYPE:
  1177.  
  1178.   FUNCTION CHAR Vlist_Str PROTOTYPE
  1179.     PARAMETERS VALUE LONG handle,;
  1180.                VALUE UINT which_element
  1181.  
  1182. RETURN VALUE:
  1183.  
  1184.   CHAR <contents>
  1185.  
  1186.   <contents> is the string contents of the element.
  1187.  
  1188. DESCRIPTION:
  1189.  
  1190.   Returns the string contents of element 'which_element'.  This does
  1191.   not move the internal list pointer, it remains on the current element.
  1192.  
  1193. EXAMPLE:
  1194.  
  1195.   ? "Current Element:"
  1196.   ? "  " + VList_CStr( handle )
  1197.   ?
  1198.   ? "Element 15:"
  1199.   ? "  " + VList_Str( handle, 15 )
  1200.  
  1201. -------------------------------------------------------------------------------
  1202. VList_TOL()
  1203. -------------------------------------------------------------------------------
  1204.  
  1205. PROTOTYPE:
  1206.  
  1207.   FUNCTION LOGICAL Vlist_TOL PROTOTYPE
  1208.     PARAMETERS VALUE LONG handle
  1209.  
  1210. RETURN VALUE:
  1211.  
  1212.   LOGICAL <at_top>
  1213.  
  1214.   <at_top> is .T. if the internal list pointer is before the first element,
  1215.   actually non-existant element 0.  Else it is set to .F.
  1216.  
  1217. DESCRIPTION:
  1218.  
  1219.   Is similar to the database related A_BOF() and returns a logical .T.
  1220.   if the list's internal pointer is BEFORE the top of the list.
  1221.  
  1222. EXAMPLE:
  1223.  
  1224.   ? "The list in reverse order is:"
  1225.   ?
  1226.   VList_Bottom( handle )
  1227.   DO WHILE .NOT. VList_TOL( handle )
  1228.     ? VList_CStr( handle )
  1229.     VList_Skip( handle, &JL_BACKWARD )
  1230.   ENDDO
  1231.  
  1232. -------------------------------------------------------------------------------
  1233. VList_Top()
  1234. -------------------------------------------------------------------------------
  1235.  
  1236. PROTOTYPE:
  1237.  
  1238.   PROCEDURE Vlist_Top PROTOTYPE
  1239.     PARAMETERS VALUE LONG handle
  1240.  
  1241. RETURN VALUE:
  1242.  
  1243.   - none -
  1244.  
  1245. DESCRIPTION:
  1246.  
  1247.   Moves the internal list pointer to the top (element 1) of the list.
  1248.  
  1249. EXAMPLE:
  1250.  
  1251.   VList_Top( handle )
  1252.   ? "The first element is:  " + Vlist_CStr( handle )
  1253.  
  1254. ==============================================================================
  1255.                       <<<CONTINUED IN VLIST4.DOC>>>
  1256. ==============================================================================
  1257.   
  1258.