C!T ROM 2/ctrom_ii_b.zip/ctrom_ii_b/PROGRAM/FOXPRO/VLIST110/VLIST1.DOC

Text File | 1992-09-25 | 24KB | 619 lines

          VList Library V1.1 -- (c) 1992, Jayson R. Minard
                                          P.O. Box 1306
                                          Westminster, CO 80030-1306 (USA)
===============================================================================
INTRODUCTION
-------------------------------------------------------------------------------

Welcome to the VList "Virtual List" library for FORCE.  This library has
grown from a simple PICK_LIST replacement to a full-scale dynamic string
management system.  There are now over 80 functions in the library.  If
you do not find documentation for a function in these files then print out
the header file (VLIST.HDR and VMOUSE.HDR) and some of the functions
have documentation within those files.  These are ones that I have not
yet had time to add to the .DOC files.

The library is divided into two parts, core functions and meta-functions.
Core functions make up the list management system to control list creation,
additions, deletion, insertion, and editting.  The meta-functions use groups of
core library functions to form larger functions such as menus and pick-list
routines.  The core functions are mostly Assembler and the meta-functions are
written in FORCE.  This allows easy changes to the more logically complex
meta-functions.

The core functions consist of the following:

VList_Add()
VList_Append()
VList_Bol()
VList_Bottom()
VList_CCopy()
VList_CDelete()
VList_CEdit()
VList_CGet_Color()
VList_CGet_Status()
VList_CInsert()
VList_Clear()
VList_Copy()
VList_CReplace()
VList_CSet_Color()
VList_CSet_Status()
VList_CStr()
VList_Delete()
VList_Edit()
VList_Empty()
VList_Get_Color()
VList_Get_Status()
VList_Get_StrLen()
VList_Goto()
VList_Init()
VList_Insert()
VList_Is_Init()
VList_Max()
VList_Number()
VList_Replace()
VList_Set_Color()
VList_Set_Status()
VList_Skip()
VList_Str()
VList_Tol()
VList_Top()
VMouse_Col()
VMouse_Cursor()
VMouse_Get_Position()
VMouse_Init()
VMouse_Left_Button()
VMouse_Save()
VMouse_Set_RowCol()
VMouse_Reset()
VMouse_Restore()
VMouse_Right_Button()
VMouse_Row()


The meta-functions consist of:

VList_1_FPick()
VList_Copy()
VList_Count_Elements()
VList_Default_Key_Handler()
VList_Default_Menu_Handler()
VList_Default_Prompt_Handler()
VList_Embed_Caps()
VList_Find_First_Good()
VList_Find_Last_Good()
VList_Fix_Path()
VList_FPick()
VList_Free_Screen()
VList_FullView()
VList_Get_Last_Good()
VList_Get_Next_Good()
VList_Locate()
VList_Locate_SubStr()
VList_Pick()
VList_PopUp()
VList_Prompt()
VList_PullDown()
VList_Restore()
VList_Restore_Append()
VList_Save()
VList_Save_Append()
VList_Say()
VList_Short_Path()
VList_Simple()
VList_Skip_Last()
VList_Skip_Next()
VList_SmallView()
VList_Sort()
VList_Sort_SubStr()
VList_What_Color()

-------------------------------------------------------------------------------
Methods for using Core Functions
-------------------------------------------------------------------------------

The core functions in the VList library can be used to access a VList
either by an index (like an array) or like a database, skipping forward and
backward.  To say, 'goto element 100', the VLIST_GOTO() function will determine
which is the best path to follow to get to the element:  start at front, start
at current, or start at end.  Therefore it does an internal skipping from
element to element, but quickly in Assembler.

The first thing you must do when wanting to use a VList is to initialize
the list.  The VLIST_INIT() command accomplishes this by returning a pointer to
the list structure and accepting 1 parameter which is the number of characters
each element will consist of.  Each element will be the same width.  A return
value of 0 represents a failure to allocate enough memory for the list header.

ex.

     VARDEF
       LONG   handle
     ENDDEF

     handle = VList_Init( 40 )
     IF handle = 0
       ? "Error initializing list"
       QUIT
     ENDIF

The list is now ready to be accessed.  The list can also be checked to see if
it is allocated using the VLIST_IS_INIT() function which returns a logical .T.
if the list has a valid structure in memory.  If the list is empty, you can use
the VLIST_EMPTY() function to determine so.

ex.

    handle = VList_Init( 40 )
    IF .NOT. VList_Is_Init( handle )
      ? "Error initializing list"
      QUIT
    ENDIF

    Call_Some_Weird_Proc( handle )
    IF VList_Empty( handle )
      ? "List is still empty!"
    ENDIF

The VLIST_EMPTY() is basically the same as asking if there are 0 elements in
the list or...

    IF VList_Max( handle ) = 0
      ? "List is still empty!"
    ENDIF

These are the basic initialization functions to get a list going.  A list can
be completely removed from memory by using VLIST_CLEAR() which free's each
element and clears the header from memory.

    VList_Clear( handle )

Now that we have a list to work with, we can start adding elements.  This is
similar to a APPEND in xBASE dialect except you provide the information that is
contained in the element instead of just getting a blank 'record'.  An element
contains three pieces of information, the element status, the color, and the
string contents.  VLIST_ADD() asks only for the handle of the list to add an
element to, and the string contents.  The status and color are set to default
values (&jl_normal and &jl_default respectively) which are explained later.  A
logical value is returned which signifies if the addition was successful.  A
.F. will be returned when there is no more memory available.

   temp_str = "New Dude"
   IF .NOT. VList_Add( handle, temp_str )
     ? "Memory problem!"
     VList_Clear( handle )
     RETURN
   ENDIF

NOTE that I cleared the list so that the program can continue with all
available memory that the list previously held.  In this example that was the
case, in others you may wish to keep the list and continue with a limited list.

VLIST_APPEND() asks for all of the three items an element can contain.

   IF .NOT. VList_Add( handle, &jl_normal, &jl_default, temp_str )
     {...}
   ENDIF

The first parameter is the list handle, which will be the case for most of the
VList core functions.  The second is the item status.  This is used by menus
and pick-list routines to decide if an element is 'normal', 'skipped', 'hit',
or 'hidden'.  They are explained as follows:

   NORMAL:    the element is displayed in __color_std and can be selected.
              This is represented by the macro &JL_NORMAL.

   SKIPPED:   the element is displayed in __color_skip but the cursor will
              jump the element and cannot select it. (&JL_SKIP)

   HIT:       the element is displayed in __color_hit and the cursor can move
              onto the element but cannot be selected. (&JL_HIT)

   HIDDEN:    the element is NOT displayed and therefore not selectable.
              (&JL_HIDDEN)

The third parameter is the item color.  If a specific color is noted then that
will be the color the item is displayed in rather than the normal global
variable (ie. __color_std, __color_hit...).  If the macro &JL_DEFAULT is
specified then the normal default variable is used for that item's status.

When an item is added, the internal list pointer for that list is moved to the
item therefore any 'current' access functions will correspond to this element.

With items in the list, you can now call some of the meta-functions
described later.  But first, we will cover accessing and changing the items.
To alter a specific item, you can do one of two things, either 'GOTO' the item
and then do a 'current' access, or do a remote access by specifying the item
index (like an array).  If you do a current access, the internal pointer will
remain on the record.  For a remote access, the pointer is moved to the correct
element, the access made, and then the pointer is moved back to the original
element.

To change all of the item's parameters at one time you can use VLIST_REPLACE()
for a remote access or VLIST_CREPLACE() for a current access.  NOTE that
the C is prepended to the word replace;  this will be the same for all of the
access functions.

Ex.
     *- current access
     VList_Goto( handle, 20 )
     VList_CReplace( handle, &jl_skip, &jl_default, "Editted Value" )

     *- remote access
     VList_Replace( handle, 20, &jl_skip, &jl_default, "Editted Value" )

Both of the previous examples have the same functionality.  The first will
stay on the editted element while the second will return to the element it
was on before the VList_Replace call was made.

You can also just edit individual element parameters using the other functions.
VLIST_EDIT() and VLIST_CEDIT() will alter the string contents.

Ex.
     *- current access
     VList_Goto( handle, 20 )
     VList_CEdit( handle, "Editted Value" )

     *- remote access
     VList_Edit( handle, 20, "Editted Value" )

You can change the color with VLIST_SET_COLOR() or VLIST_CSET_COLOR() and set
the status with VLIST_SET_STATUS() or VLIST_CSET_STATUS().

To do the opposite and get the current values within an element, you will use
individual functions for each parameter.  VLIST_CSTR() and VLIST_STR() will
return the string contents of the element.

Ex.

    *- current access
    VList_Goto( handle, 20 )
    temp_str = VList_CStr( handle )

    *- remote access
    temp_str = VList_Str( handle, 20 )

For colors and status use VLIST_GET_COLOR(), VLIST_CGET_COLOR(),
VLIST_GET_STATUS(), and VLIST_CGET_STATUS().

To find the maximum width of elements in a list, you can use the
VLIST_GET_STRLEN() function.

Once you have a list, you need to know how to move around within the list.
The VList_Goto() function has already been used and is pretty simple to see.
The following text will print all of the items in a list using the VLIST_MAX()
function to determine the number of items in a list.

   FOR loop_var = 1 TO VList_Max( handle )
     VList_Goto( handle, loop_var )
     ? VList_CStr( handle )
   NEXT

This would be decently quick since the VLIST_GOTO() function is smart and will
always start at the current element to find the next instead of going all the
way to the start of the list to find an element in the middle.  DO NOT do the
following since the internal pointer would go from the current, to the selected,
back to the current, then to the next selected and so on.

   FOR loop_var = 1 TO VList_Max( handle )
     ? VList_Str( handle, loop_var )
   NEXT

You can also access the list like it was a database using the VLIST_TOP()
function to go to the top element (#1) and the VLIST_BOTTOM() to go to the
last element.  To determine if you are at the top, you can use VLIST_TOL()
which asks 'are we at the Top Of List?' and VLIST_BOL() for the bottom.
The VLIST_SKIP() function will move the 'current' pointer from one element
to another.

   *- forward:
   VList_Top( handle )
   DO WHILE .NOT. VList_Bol( handle )
     ? VList_CStr( handle )
     VList_Skip( handle, &JL_FORWARD )
   ENDDO

   *- backward
   VList_Bottom( handle )
   DO WHILE .NOT. VList_Tol( handle )
     ? VList_CStr( handle )
     VList_Skip( handle, &JL_BACKWARD )
   ENDDO

Notice the use of the macros &JL_FORWARD and &JL_BACKWARD to determine which
direction SKIP will move.  If you want to know what the current element pointer
is, then try VLIST_NUMBER().

   VList_Bottom( handle )
   DO WHILE .NOT. VList_Tol( handle )
     ? VList_Number( handle )
     VList_Skip( handle, &JL_BACKWARD )
   ENDDO

This should count backwards printing the element number.

You can also Insert and Delete elements either using the current position
or going to a 'remote' position.  Inserting will create a new element, like
VLIST_APPEND() you must specify all 3 items, and move the current pointer to
that position when using VLIST_CINSERT().  VLIST_INSERT() will return the
current pointer to the element that you inserted the new one before.

ex.

   *- this example doesn't do error checking which is bad!!!
   handle = VList_Init( 50 )
   VList_Add( handle, "element 1" )
   VList_Add( handle, "element 3" )

   *- now to add element 2, we could either:
   VList_Insert( handle, 2, &jl_normal, &jl_default, "element 2" )
   *- which means insert BEFORE element 2 this new guy, OR we could:
   VList_Goto( handle, 2 )
   VList_CInsert( handle, &jl_normal, &jl_default, "element 2" )
   *- if we wanted to stay on the new element.

The opposite of insert is delete.  VLIST_CDELETE will delete the current
element and move the current pointer to the element that was following it
unless it WAS the last element, then it moves 1 backward.  Therefore the
element number will be the same in the first case, 1 less in the second.
VLIST_DELETE() will delete the SPECIFIED element and return to the current
unless it was the one deleted...

The LAST core function that does not deal with the mouse is VLIST_COPY() and
VLIST_CCOPY() which can be used to make a copy of an items elements from
one to another.


-------------------------------------------------------------------------------
                          MOUSE Core Functions
-------------------------------------------------------------------------------

Some of the meta-functions use the mouse functions to provide mouse support.
You will need to initialize the mouse in order for these to use it.  Some of
the meta-functions also ask for a parameter which specifies whether or not
to use the mouse.  A good way to deal with this is to do the following...

   *- VMouse_Init returns the number of buttons on the mouse, else 0 for no
   *  mouse.

   IF VMouse_Init() <> 0
     is_mouse = .T.
     VMouse_Reset()
     *- clean up the mouse drivert
   ELSE
     is_mouse = .F.
   ENDIF

   VList_Pick( handle, {...}, is_mouse, is_mouse, {...} )

   IF is_mouse
     VMouse_Reset()
     VMouse_Cursor( .F. )
   ENDIF

   QUIT

This example basically starts the mouse up if there is one present, then passes
the 'is_mouse' logical value to the VLIST_PICK() routine in the parameter spot
for 'provide-mouse-support' and 'show-scroll-bar'.  The second use of 'is_mouse'
is there since some people do not want a scroll bar if no mouse is present.
Therefore the 'is_mouse' variable provides the answer.  At the end of the
program, the mouse driver is reset and the cursor is ensured to be off.  The
reset is done to make sure that the driver is in the correct state.

The other mouse functions are listed:

   VMOUSE_COL           - return the character column of the mouse
   VMOUSE_CURSOR        - set the cursor on (.T.) or off (.F.)
   VMOUSE_GET_POSITION  - returns the PIXEL position of the mouse
   VMOUSE_INIT          - initialize the mouse driver
   VMOUSE_LEFT_BUTTON   - is the left button pressed?
   VMOUSE_RESET         - reset the mouse driver
   VMOUSE_RESTORE       - restore the 'saved' mouse driver state
   VMOUSE_RIGHT_BUTTON  - is the right button pressed?
   VMOUSE_ROW           - return the character row of the mouse
   VMOUSE_SAVE          - save the mouse driver state to a buffer
   VMOUSE_SET_ROWCOL    - set the character position of the mouse cursor

Most of these will only be used by the meta-functions but are prototyped for
your use to create NEW meta-functions.

===============================================================================
===============================================================================
                             META-Functions
-------------------------------------------------------------------------------

The meta-functions provide already-programmed usefulness from the VList
library.  They provide pick-lists, prompted menus, pull-down menus,
pop-up menus, file-list picking, text-file viewing, and list searching.
I have even written a TEXT/MEMO editor using this library that took 3 days
instead of months.  It is available in another library (VEDIT.LIB).

Many of the meta-functions receive a list as a parameter.  The list contains
a defined structure which will allow for variable-length parameters.  These
parameters are covered here under each function topic instead of in the
reference section since they require much text.

The functions will be covered with the simple routines near the front and
the more complex to the rear.  This is a text description and the prototype
with parameter list can be found in the reference section.

===============================================================================
VList_Count_Elements()
VList_Find_First_Good()
VList_Find_Last_Good()
VList_Get_Last_Good()
VList_Get_Next_Good()
VList_Skip_Next()
VList_Skip_Last()
-------------------------------------------------------------------------------

The above elements are designed to help the other meta-functions deal with
hidden and skipped elements.  Therefore you can determine if there is a
valid 'next' element to go to, or how many there are between here and there.

ex.

    num_elements = VList_Count_Elements( handle, min, max )

VLIST_COUNT_ELEMENTS(), VLIST_SKIP_NEXT(), and VLIST_SKIP_LAST() will only
ignore hidden elements since they deal with what can be displayed.  The
others deal with hidden AND skipped since they deal with what can be
selected.

Their exact definition is covered in the function reference section.


===============================================================================
VList_Fix_Path()
VList_Short_Path()
-------------------------------------------------------------------------------

These two are pretty much unrelated to a list, except they are needed by the
VLIST_1_FPICK() and VLIST_FPICK() functions when displaying the file-path
being listed.

VLIST_FIX_PATH() standardizes paths by expanding paths that start with ..
and . and making sure the path always ends with a \.

VLIST_SHORT_PATH() takes a long path name and alters it to fit within a
set width.

Ex.

     C:\PROGRAM\SOURCE\VLIST\LIB\DEMO\

  would become (when placed under a width of 25 )

     C:\...\VLIST\LIB\DEMO\


==============================================================================
VList_Restore()
VList_Restore_Append()
VList_Save()
VList_Save_Append()
------------------------------------------------------------------------------

To save a VList to disk is simple using these 4 functions.  VLIST_SAVE() will
store a list along with the max width, and number of elements to a text file.
This can be encrypted by sending a .T. as one of the parameters.
VLIST_SAVE_APPEND() will add to an already saved list.  If the list is
encrypted, so will this one.  If this list has a longer or shorter width then
it will be altered as saved.

VLIST_RESTORE() will init a new list and read a list file into memory.  If
you want to add to a current list in memory then use VLIST_RESTORE_APPEND().


==============================================================================
VList_Free_Screen()
------------------------------------------------------------------------------

This routine will free a screen saved by SAVE_SCREEN() without restoring it
to the screen.  Therefore the memory is regained, but you do not have to
bring up the wrong screen.

==============================================================================
VList_What_Color()
------------------------------------------------------------------------------

VLIST_WHAT_COLOR() is called by a majority of the meta-functions to set the
color that the element should be.

The parameters are the list handle and the value that __color_std should
represent for this element if &JL_DEFAULT is used.

ex.

   old_std = __color_std
   old_enh = __color_enhcd

   *- element not highlighted
   VList_What_Color( handle, old_std )
   ? VList_CStr( handle )

   *- element highlighted
   VList_What_Color( handle, old_enh )
   ? VList_Cstr( handle )


==============================================================================
VList_Sort()
VList_Sort_Substr()
------------------------------------------------------------------------------

To place a list in computer-alphanumeric order (sort-of alphabetical) then
you can sort the list using either the entire string contents or a partial
section.  The Substr sort is nice when you are using the first character
for say a marker and do not want it looked at during the sort.  VLIST_SORT()
is quicker than VLIST_SORT_SUBSTR() since it does not have to break the
string down.  They both use the same internal VLIST function but it is
smart to determine whether or not it has to do extra string functions.

You can specify a start element and end element for sorting between.  The
QUICK-SORT method is used here.


==============================================================================
VList_Locate()
VList_Locate_Substr()
------------------------------------------------------------------------------

These act similar to the LOCATE command in the xBASE standard.  You can either
search for a string looking at the entire string or for a substr.  If you
set 'exact match' to .T. then the strings must compare exactly in length and
from first to last character.  The non-exact match will look for a string
that matches up to the length of the user defined search string.  To do
a logical CONTINUE (such as in xBASE), you can call with almost the same
parameters except set the 'continue from current' parameter to .T.

==============================================================================
VList_Say()
------------------------------------------------------------------------------

This routine is similar to the @SAY command except that it displays an
element with any highlighted characters in their different color.  Therefore
to display embedded color codes, call this routine.  It is not as quick
as @SAY so should only be used when you know that embedded codes are used.

An embedded code is a character preceded by the special character in
__EMBED_CHAR which means to display this single character in the color
__COLOR_HI_STD or __COLOR_HI_ENHCD depending on whether the highlight
bar is over the element or not.

Ex.

    __EMBED_CHAR = "^"
    temp_str = "save ^File"
    VList_Add( handle, temp_str )

Now in any list that you have 'allow_embedded' turned on OR if using
VLIST_SAY() then the character 'F' will be displayed in __COLOR_HI_STD
or __COLOR_HI_ENHCD.  NOTE that the embedded character can be changed
to whatever value you wish and should be set at the beginning of your
program.

==============================================================================
VList_Embed_Caps()
------------------------------------------------------------------------------

This routine will take a list range and add the __EMBED_CHAR before the
FIRST capital letter found within a list.  This makes it easier for you
to highlight elements for menus and such especially if you have selected
an __EMBED_CHAR that you cannot display or use in your editor.

Ex.

    __EMBED_CHAR = CHR( 27 )
    VList_Add( handle, "Jayson was here" )
    VList_Add( handle, "was It right?" )
    VList_Add( handle, "vList is cool..." )
    VList_Embed_Caps( handle, 1, 3 )

Now the 'J', 'I', and 'L' will have a CHR( 27 ) placed before them.

==============================================================================
                      <<<CONTINUED IN VLIST2.DOC>>>
==============================================================================