home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / FOXPRO / VLIST110 / VLIST2.DOC < prev    next >
Text File  |  1992-03-20  |  23KB  |  505 lines
  1.           VList Library V1.1 -- (c) 1992, Jayson R. Minard
  2.                                           P.O. Box 1306
  3.                                           Westminster, CO 80030-1306 (USA)
  4. ===============================================================================
  5. META-Functions <CONTINUED>
  6. -------------------------------------------------------------------------------
  7.  
  8. VList_SmallView()
  9. VList_FullView()
  10. -------------------------------------------------------------------------------
  11.  
  12. These two functions have almost the same functionality of viewing a text
  13. file with the exception of VLIST_FULLVIEW() provides mouse support and 
  14. VLIST_SMALLVIEW() does not.  Mouse support can be turned on and off
  15. for VLIST_FULLVIEW().
  16.  
  17. Internally VLIST_FULLVIEW() calls VLIST_PICK() to handle the displaying of
  18. the text file while VLIST_SMALLVIEW() calls VLIST_SIMPLE().  Therefore if you
  19. are already using VLIST_PICK() or any of the META-functions that calls it
  20. then you should continue to use it here since you do not want to include
  21. extra code that isn't needed.  The menu functions all use VLIST_PICK() and
  22. the only time VLIST_SIMPLE() is used is if it is called by you.
  23.  
  24. ===============================================================================
  25. VList_1_FPick()
  26. VList_FPick()
  27. -------------------------------------------------------------------------------
  28.  
  29. These two functions are used to display a list of files from a specific
  30. directory and then have the user select either 1 file (VLIST_1_FPICK)
  31. or many (VLIST_FPICK).  A parameter can be passed to allow the user
  32. to change directories and also one to have VLIST_FPICK() retain ALL marked
  33. files even if the directory IS changed.
  34.  
  35. ===============================================================================
  36. VList_Simple()
  37. VList_Pick()
  38. -------------------------------------------------------------------------------
  39.  
  40. To display a list and have an element selected, these are the two choices.
  41. VLIST_PICK() allows for multiple columns and full mouse support.  On the
  42. other hand VLIST_SIMPLE() is similar to the old FORCE pick_list routine.
  43. It is short with little code and just does the job.  VLIST_PICK() handles
  44. hidden, skipped, normal, and hit elements with different elements having
  45. different colors along with multiple columns.  VLIST_SIMPLE() supports 
  46. only single columns, but does allow elements of different colors. With
  47. VLIST_PICK() you can also have embedded characters within an element 
  48. so that characters are highlighted with.
  49.  
  50. For VLIST_PICK() you can provide (actually MUST) a user-defined keystroke
  51. handler.  If you just want to use the standard defaul, you can pass
  52. VLIST_DEFAULT_KEY_HANDLER() as the parameter.  The keyboard handlers
  53. are covered in the next section.  They provide redefinition of what
  54. keys have what activity and also how the mouse reacts with the list.
  55.  
  56. On <ESC> the selected element number is set to the last item the
  57. cursor was on.  Check LASTKEY() to determine how the list was exitted.
  58. This allows for re-entry into the list so that the user cannot tell
  59. you ever left.
  60.  
  61. ===============================================================================
  62. ===============================================================================
  63.                             MENU SYSTEMS
  64. -------------------------------------------------------------------------------
  65.  
  66. Now we get to be complex.  We will cover the three different VLIST menu systems
  67. and how the VList must be built in order to use a system.
  68.  
  69. Basically a VLIST can contain multiple menu 'systems'.  Each is assigned a
  70. number and that is used to reference the individual system from all of the
  71. others.  A list containing more than one menu system must have an unique
  72. number for each system and a system must be continuous within the list.
  73.  
  74. -------------------------------------------------------------------------------
  75. Prompt Menus -- VLIST_PROMPT()
  76. -------------------------------------------------------------------------------
  77.  
  78. These menus can either be selections scattered across the screen or they can
  79. be push-button type selections.  VLIST_PROMPT() is used to display and
  80. execute a prompted menu.
  81.  
  82. A menu list must be build as follows for a PROMPT menu.  This can be
  83. a seperate list or a segment of an existing list.
  84.  
  85.     <SYSTEM>.<ITEM> @<ROW>,<COL> |<TEXT>
  86.     {...}
  87.  
  88. Where:
  89.  
  90.   <SYSTEM>      - The menu system number
  91.  
  92.   <ITEM>        - The item number.  This is the number returned upon
  93.                   selecting the item.
  94.  
  95.   <ROW>,<COL>   - The screen coordinates to display this item.
  96.  
  97.   <TEXT>        - The text to display.
  98.  
  99. NOTE!!!  The '|' within each element of a PROMPT system MUST be aligned so
  100. that they are in the same character position within each element.  This
  101. helps the PROMPT system know where to find the text to display AND find
  102. it very quickly.  The text starts immediately after the '|' so any
  103. spaces before or after WILL be displayed within the highlighted area.
  104.  
  105. A PROMPT system can have hidden, skipped, hit, and normal elements.  At
  106. least ONE should be normal.  You can also edit an element within the
  107. keyboard handler so that it acts like a push-button.  The keyboard
  108. handler used for PROMPT systems is VLIST_DEFAULT_PROMPT_HANDLER().
  109.  
  110. Example list:
  111.  
  112.    VList_Add( handle, "1.1 @23,2  | Add " )
  113.    VList_Add( handle, "1.2 @23,7  | Delete " )
  114.    VList_Add( handle, "1.3 @23,15 | Rename " )
  115.    VList_Add( handle, "1.4 @23,23 | Exit " )
  116.    VList_Add( handle, "2.1 @23,2  | Next " )
  117.    VList_Add( handle, "2.2 @23,8  | Previous " )
  118.    VList_Embed_Caps( handle, 1, VList_Max( handle ) )
  119.    selection = 1   && starting guy
  120.    selection = VList_Prompt( handle, 1, selection,;
  121.                              VList_Default_Prompt_Handler,;
  122.                              is_mouse_on, .T. )
  123.  
  124. A few notes about the above example:
  125.  
  126.   1.  We created a list with 2 menu systems in it.
  127.  
  128.   2.  Even on <ESC> the prompt routine will return the element number
  129.       that the cursor was on, therefore allowing you to re-enter where
  130.       you left off later.
  131.  
  132.   3.  The 'is_mouse_on' variable is just an example saying whether or
  133.       not I have the mouse initialized.
  134.  
  135.   4.  VLIST_EMBEDD_CAPS() will add the __EMBED_CHAR before the first
  136.       capital letter in each of the the elements 'text'.  If this letter
  137.       is pressed, the cursor will jump to that element and select it.
  138.       Therefore, each should be unique.
  139.  
  140.   5.  The final .T. signifies to highlight the embedded characters.
  141.  
  142. -------------------------------------------------------------------------------
  143. PopUp Menus -- VLIST_POPUP()
  144. -------------------------------------------------------------------------------
  145.  
  146. Another menu system commonly used is the pop-up menu.  This is a window
  147. that appears magically on the screen with a few selections in it.  This
  148. sometimes has a title.
  149.  
  150. As implemeneted in the VLIST system, you create a list or segment of
  151. a list similar to the PROMPT system except with the following
  152. structure.  Keep in mind that the structure is designed to make
  153. the code scan it quicker therefore there may seem to be some
  154. unneccessary aligning and so on, but it is neccessary!
  155.  
  156.    <SYSTEM>.0   |<TITLE>
  157.    <SYSTEM>.<ITEM>  |<TEXT>
  158.    {...}
  159.  
  160. Note that the first line is the TITLE line and has an item number of 0.  This
  161. must always be included, yet the '|' can be immediately followed by the
  162. terminating quote so that it is blank and therefore not displayed.
  163.  
  164. Ex.
  165.  
  166.    VList_Add( handle, "1.0  | Select " )
  167.    VList_Add( handle, "1.1  | Option 1 " )
  168.    VList_Add( handle, "1.2  | Choice 2 " )
  169.    VList_Append( handle, &jl_skip, &jl_default,;
  170.                       "1.?  |─..." )
  171.    VList_Add( handle, "1.3  | Selection 3 " )
  172.    VList_Embed_Caps( handle, 2, 4 )
  173.  
  174. Also note that the '|' must line up again!  This helps with processing
  175. speed.
  176.  
  177. The call to the VLIST_POPUP() function has many important parameters.
  178. They are all described in the reference section.  Some notes generally
  179. about a few...
  180.  
  181.    1.  The default keyboard handler is VLIST_DEFAULT_MENU_HANDLER()
  182.  
  183.    2.  The screen can be saved to a variable that you either restore
  184.        or allow the function to restore for you.  This means that
  185.        you can keep the menu on the screen after a selection is made,
  186.        do an activity, and then clear the menu.  This is where
  187.        VLIST_FREE_SCREEN() comes in handy if you want to clear the
  188.        saved screen but not restore it.
  189.  
  190.    3.  If you select 'allow_embedded' then the character following
  191.        the __embed_char will be highlighted.  Also if you use
  192.        embedded characters, and a key is pressed, the cursor moves
  193.        to the corresponding element and selects it.
  194.  
  195.    4.  Notice the element "1.?" line.  This line has a character followed
  196.        by '...' in the <TEXT> area.  This character will be repeated across
  197.        the width of the menu window.  This means that you do not have to
  198.        calculate the width yourself.  Also it is marked as skipped so it
  199.        will be jumped when the cursor moves to it.  The '?' is just a place
  200.        holder so that no <ITEM> number is used.
  201.  
  202.  
  203. -------------------------------------------------------------------------------
  204. PullDown Menus -- VLIST_PullDown()
  205. -------------------------------------------------------------------------------
  206.  
  207. Pulldown menus are basically a group of horizontal pop-up menus.  Therefore
  208. most of the same internal routines are used.  This means that some information
  209. you must place in the list probably will never be used but it allows for
  210. smaller and quicker coding of the menu routines.
  211.  
  212. The menu structure has three parts...
  213.  
  214.      <SYSTEM>.<SUBMENU> @<COL> |<HEADER>
  215.      <SYSTEM>.<SUBMENU>.0      |<BOX TITLE>
  216.      <SYSTEM>.<SUBMENU>.<ITEM> |<TEXT>
  217.      {...}
  218.  
  219. The first part is the sub-menu column position and the header.  The header
  220. is displayed on the menu line, sent as a parameter, and the sub-menu is
  221. placed according to a different parameter.  This means you can have a line
  222. or a blank space between the header and menu.
  223.  
  224. The second part is the box title.  This is the same as for pop-up menus
  225. but most pull-down menus do NOT have a title on the actual menu box.  This
  226. is there only to allow for use of identical internal code.  You MUST have
  227. this line, yet the title should be left blank after the '|' if you do
  228. not want a title.
  229.  
  230. The last (third) part is a group of items to display as the sub-menu lines.
  231.  
  232. NOTE that you must align the '|' for all of the menus within a pull-down
  233. system.
  234.  
  235. Ex.
  236.  
  237.       __EMBED_CHAR = "^"
  238.       VList_Add( handle, "1.1 @2    | ^File " )
  239.       VList_Add( handle, "1.1.0     |" )
  240.       VList_Add( handle, "1.1.1     | ^Save " )
  241.       VList_Add( handle, "1.1.2     | ^Open " )
  242.       VList_Add( handle, "1.1.3     | ^Close " )
  243.       VList_Append( handle, &jl_skip, &jl_default,;
  244.                          "1.1.?     |─..." )
  245.       VList_Add( handle, "1.1.4     | C^apture " )
  246.       VList_Add( handle, "1.1.5     | ^Quit " )
  247.       VList_Add( handle, "1.2 @8    | ^Utilities " )
  248.       VList_Add( handle, "1.2.0     |" )
  249.       VList_Add( handle, "1.2.1     | ^Pack " )
  250.       VList_Add( handle, "1.2.2     | ^ReIndex " )
  251.  
  252. Now you can call VLIST_PULLDOWN() and have it display the menu.  This
  253. example contains one skipped line that will be jumped when the cursor
  254. gets to it.  This line is displayed using the color __COLOR_SKIP.
  255.  
  256. This example does not use VLIST_EMBED_CAPS() since there would be
  257. duplicate embedded characters across different elements, 'Close' and
  258. 'Capture' would both have the 'C' highlighted.  Instead I set the
  259. __EMBED_CHAR variable to something easy to work with and directly
  260. placed it into the element myself.  The embedded code in the header
  261. line is independent from the elements within the sub-menu.  The headers,
  262. when the menus are pulled up, can be moved to by pressing their letter.
  263. When the menu is down, then you can press the highlighted selection
  264. letter.
  265.  
  266. Some notes about certain parameters:
  267.  
  268.     1.  The 'menu_processing_proc' is called when ever an element is
  269.         selected.  Therefore you process from within the menu rather
  270.         than outside of it as in the PROMPT and POPUP menus.  This
  271.         UDF function should be created as follows:
  272.  
  273.           FUNCTION UINT pulldown_selector   && or whatever name
  274.             PARAMETERS VALUE LONG handle,;
  275.                        VALUE UINT system,;
  276.                        VALUE UINT over,;
  277.                        VALUE UINT down
  278.             VARDEF
  279.               UINT ret_val
  280.             ENDDEF
  281.  
  282.             ret_val = 0   && continue processing
  283.  
  284.             DO CASE
  285.               CASE system = 1
  286.                 DO CASE
  287.                   CASE over = 1
  288.                     DO CASE
  289.                       CASE down = 1
  290.                       CASE down = 2
  291.                       CASE down = 3
  292.                     ENDCASE
  293.                   CASE over = 2
  294.                     DO CASE
  295.                       CASE down = 1
  296.                       CASE down = 2
  297.                     ENDCASE
  298.                   CASE over = 3
  299.                     DO CASE
  300.                       CASE down = 1
  301.                       CASE down = 2
  302.                     ENDCASE
  303.                 ENDCASE
  304.               CASE system = 2
  305.                 {...}
  306.             ENDCASE
  307.  
  308.             RETURN ret_val  && a ret_val of 1 will stop the pulldown menu!
  309.           ENDPRO
  310.  
  311.         Therefore all of your pulldown menus can call the same routine OR
  312.         you can have one for each system...  NOTE that the return value
  313.         can stop the pulldown menu and exit back to whatever called
  314.         VLIST_PULLDOWN if it is 1.  A 0 signifies that the menu should
  315.         be continued.
  316.  
  317.     2.  The keyboard handler should be VLIST_DEFAULT_MENU_HANDLER().
  318.  
  319.     3.  The 'column_offset' parameter adjusts the horizontal position
  320.         of the sub-menu in relation to the header.
  321.  
  322.     4.  The 'always_down' parameter can be used so that the menu is
  323.         always pulled down and the <ESC> key will not pull it up to
  324.         show ONLY the headers.  If this is .F. then the menus can
  325.         be pulled up to have the cursor move only among the headers.
  326.  
  327. -------------------------------------------------------------------------------
  328. Combining list systems to form a limitted 'dialog' box
  329. -------------------------------------------------------------------------------
  330.  
  331. The example programs show the combining of the different VLIST functions
  332. to form a dialog system.  Basically a loop is run that circulates and
  333. enters a case statement.  The case statement checks a variable which is
  334. the current 'state' of the system.  This state determines which menu
  335. system we are wanting to look at.  That particular system is activated
  336. and if the cursor leaves the system and hits another, then in the keyboard
  337. handler we detect this, set the 'state' (a global variable), and exit
  338. our system.  The loop then goes back throught the case statement and
  339. enters the new 'state'.
  340.  
  341. ===============================================================================
  342. ===============================================================================
  343.                             KEYBOARD HANDLERS
  344. -------------------------------------------------------------------------------
  345.  
  346. The following functions are the defualt keyboard handlers for differnt VLIST
  347. functions:
  348.     
  349.      VList_Default_Key_Handler()
  350.           - for VList_Pick()
  351.  
  352.      VList_Default_Menu_Handler()
  353.           - for VList_Popup()
  354.           - for VList_Pulldown()
  355.  
  356.      VList_Default_Prompt_Handler()
  357.           - for VList_Prompt()
  358.  
  359. These can be replaced by your own by changing the source and placing it
  360. into the VLIST library or linking it before the library.  OR you can
  361. create your own version and send the its' name to the function instead
  362. of the default name.  This is the preferred method.  
  363.  
  364. The keyboard handler receives information on the state of the mouse
  365. or the key that was pressed.  If the mouse state is non-zero then the
  366. mouse is what activated the handler, else it was a key-stroke.
  367.  
  368. If you have the mouse return a key value, then you should use the 'set_key'
  369. variable in the keyboard handler so that the LASTKEY() value will be equal
  370. to the key value.  This way the mouse can return LASTKEY() = 27 when
  371. the right button is hit and so on.
  372.  
  373. The source code for the keyboard handlers is as follows:
  374.  
  375.   VLIST35.PRG   -- VLIST_DEFAULT_KEY_HANDLER()
  376.   VLIST70.PRG   -- VLIST_DEFAULT_MENU_HANDLER()
  377.   VLIST79.PRG   -- VLIST_DEFAULT_PROMPT_HANDLER()
  378.  
  379. You can copy this file, rename the function name, and then change the
  380. contents so that it acts the way you wish.  This includes how the mouse
  381. scrolls the window, and also how it uses the scroll-bar.  You can remap
  382. keys so that they become something altogether differnt.
  383.  
  384. The keyboard handler will receive the following codes which are defined
  385. as macros in VLIST.HDR along with the current key value in the variable
  386. 'pick_key'.
  387.  
  388.     &JL_MOUSE_IGNORE      - no mouse activity, check the value of PICK_KEY
  389.  
  390.     &JL_MOUSE_RIGHT       - the right mouse button was pressed
  391.  
  392.     &JL_MOUSE_XRIGHT      - the right mouse button was released.  This usually
  393.                             sets PICK_KEY to 27 using the 'set_key' variable.
  394.  
  395.  
  396.     &JL_MOUSE_LEFT        - the left mouse button was pressed
  397.  
  398.     &JL_MOUSE_XLEFT       - the left mouse button was released
  399.  
  400.     &JL_MOUSE_BOTH        - both buttons pressed together
  401.  
  402.     &JL_MOUSE_UP          - the left mouse button was pressed while the
  403.                             mouse cursor was on the UP-tab on the scroll-bar.
  404.                             This usually sets PICK_KEY to some cursor up
  405.                             value.
  406.  
  407.     &JL_MOUSE_XUP         - the left mouse button was released while the
  408.                             mouse cursor was on the UP-tab on the scroll-bar.
  409.  
  410.     &JL_MOUSE_DOWN        - the left mouse button was pressed while the
  411.                             mouse cursor was on the DOWN-tab on the scroll-bar.
  412.                             This usually sets PICK_KEY to some cursor down
  413.                             value.
  414.  
  415.     &JL_MOUSE_XDOWN       - the left mouse button was released while the
  416.                             mouse cursor was on the DOWN-tab on the scroll-bar.
  417.  
  418.     &JL_MOUSE_SCROLL      - the left mouse button was pressed while the
  419.                             mouse cursor was somewhere on the scroll-bar.
  420.                             The value of PICK_KEY is set depending on where
  421.                             the cursor is according to the relative marker
  422.                             on the scroll-bar.
  423.  
  424.                                  Mouse cursor at top line of scroll-bar
  425.                                      PICK_KEY = &K_C_PG_UP
  426.                                  Mouse cursor at bottom line of scroll-bar
  427.                                      PICK_KEY = &K_C_PG_DOWN
  428.                                  Mouse cursor above relative position
  429.                                      PICK_KEY = &K_PG_DOWN
  430.                                  Mouse cursor below relative position
  431.                                      PICK_KEY = &K_PG_UP
  432.  
  433.                             Therefore you should check this case AND the
  434.                             value of PICK_KEY, then you can alter PICK_KEY
  435.                             to what you wish it to be.
  436.  
  437.     &JL_MOUSE_XSCROLL     - Mouse released on scroll-bar (usually ignored)
  438.  
  439.     &JL_MOUSE_NEW         - the left mouse button was pressed while the
  440.                             cursor was on a new element.  This usually sets
  441.                             the return value to &JL_GOTO_MOUSE which will
  442.                             cause the cursor to move to this element.  A
  443.                             new element is defined as one that the highlight
  444.                             bar is not currently on.
  445.  
  446.     &JL_MOUSE_XNEW        - the left button was released on a new element.
  447.  
  448.     &JL_MOUSE_SELECT      - the left mouse button was pressed on the
  449.                             current element.  This is usually ignored.
  450.  
  451.     &JL_MOUSE_XSELECT     - the left mouse button was released on the
  452.                             current element.  This usually returns the
  453.                             value of &JL_SELECT.  You should also set
  454.                             the PICK_KEY to 13 and use 'set_key' to do
  455.                             this so that LASTKEY() will be correct.
  456.  
  457. The keyboard handler can return the following codes which are defined
  458. as macros in VLIST.HDR and can also return information in the variable
  459. 'pick_key'.
  460.  
  461.    &JL_CONTINUE         - continue and check the value of PICK_KEY and
  462.                           respond as normal for that key-stroke.
  463.  
  464.    &JL_IGNORE           - ignore PICK_KEY and wait for another action.
  465.  
  466.    &JL_REPAINT          - ignore PICK_KEY and repaint the pick area.
  467.  
  468.    &JL_SELECT           - select the current element and exit
  469.  
  470.    &JL_ABORT            - exit
  471.  
  472.    &JL_PAINT_KEY        - continue and check PICK_KEY, then repaint the
  473.                           pick area.
  474.  
  475.    &JL_BAD_ELEMENT      - the current element is now either set as SKIP,
  476.                           or HIDDEN so please move to another valid element
  477.                           and repaint the erea.  In case you either delete,
  478.                           or change the status of an element in the key
  479.                           handler.
  480.  
  481.    &JL_REPAINT_ELEMENT  - redraw the current element and then evaluate
  482.                           PICK_KEY.  This is in case you do a VLIST_EDIT
  483.                           within the key handler.
  484.  
  485.    &JL_REPAINT_IGNORE   - redraw the current element but ignore PICK_KEY.
  486.  
  487.    &JL_GOTO_MOUSE       - goto the element that the mouse cursor is on.
  488.  
  489.    ** this is for PULL-DOWN menus ONLY!
  490.  
  491.    &JL_RESCAN_MENU      - the mouse cursor is somewhere on the header line,
  492.                           please find out which header it is pointing to
  493.                           and pull that menu down.
  494.  
  495. Using these values and the source for the default keyboard handlers you can
  496. alter the library to suite your needs easily.
  497.  
  498. Another technique instead of replacing the complete handler, is to have
  499. yours called, filter what you don't want, then call the default, then return
  500. its return value as your own.
  501.  
  502. ==============================================================================
  503.                       <<<CONTINUED IN VLIST3.DOC>>>
  504. ==============================================================================
  505.