Click above to get retro games delivered to your door ever month!

 C_PICK()

 DESCRIPTION

 C_PICK() displays a specified character array in a window and
 allows scrolling to select or view an option.  The display can be
 based on the entire array or can be limited to a certain maximum
 element.  The window display can scroll up, down, left, and right
 and is completely configurable.  All keyboard and display activity
 is controlled by a specified user-defined function (UDF) or by
 default options if a UDF is not supplied.  Searching options and
 the ability to resize and move the display window can also be
 controlled by the UDF.

 SYNTAX

 C_PICK(st_row, st_col, end_row, end_col, array [,box] [,color] [,shadow]
 [,title] [,footer] [,first_item] [,last_item] [,udf] [,wrap] [,markarr])

 PARAMETERS

 st_row (N), st_col (N), end_row (N), and end_col (N) define the
 upper left and lower right coordinates for the window.

 array (A) is the character array to display in the window.  The
 array should be specified with no quotes.

 box (N) is the box type (0 - 5) to draw for the window.  If box is
 not specified, box type 2 (double box) is used.  The box types are
 as follows:

 BOX TYPE     DESCRIPTION
 --------     -----------
 0            No box
 1            Single top/bottom, single sides
 2            Double top/bottom, double sides
 3            Double top/bottom, single sides
 4            Single top/bottom, double sides
 5            Solid graphics characters

 color (C) is the color of the window and highlight bar.  The first
 part of the color parameter is the window color and the second part
 is the highlight bar color ("W/B,W+/R").

 shadow (N) is the type of shadow to display around the window.  The
 shadow types are as follows:  0 = no shadow, 1 = left side/bottom
 shadow, 2 = right side/bottom shadow.  If shadow is not specified,
 no shadow is displayed.

 title (C) is the title line for the window.  The title is automatically
 centered at the top of the window and remains stationary.

 footer (C) is the footer line.  The footer line is automatically
 centered at the bottom of the window and remains stationary.

 first_item (N) is the element number of the first item to highlight
 in the array.  If first_item is not specified, the default of 1 is used.

 last_item (N) is the element number of the last item to highlight
 in the array.  last_item provides the ability to limit what is
 displayed in the array.  If the last_item is not specified, all
 array elements are displayed.

 udf (C) is the name of the user-defined function (UDF) to maintain
 a dialog with during the C_PICK() call.  The UDF is called
 continuously to allow access and control of the function.  udf
 should be passed in quotes and without parenthesis, for example,
 "PICK_UDF".  If udf is not specified, the default key control
 options are used.  (Refer to file UDF_PICK.PRG on the ClipOn
 diskette for a functional UDF.)

 wrap (L) indicates whether the highlight bar should wrap when the
 last or first array items are highlighted.  Note that the wrap
 option only effects the display when the number of array elements
 is equal to the size of the window.  If wrap is not specified, the
 default of true (.T.) is used.

 markarr (C) is the name of the array to use to store array item
 numbers "marked" for selection when the user toggles item marking
 on or off.  The selection of a single item is always available in
 C_PICK(), but this option allows one, many, or all items to be
 selected by the user as in a check-off type list.  The markarr
 array must be declared before calling C_PICK() to the same size as
 the display array and passed without quotes.   The markarr array
 specified will be filled with the array element numbers selected by
 the user.  Additionally, the markarr can be filled with array
 element numbers before calling C_PICK() to indicate items have
 already been selected.  The presence or absence of the array in the
 argument list indicates whether item marking is enabled or
 disabled.  If a UDF is specified it also controls the marking and
 unmarking of items by controlling the key definitions.  If markarr
 is not specified, the default of no item marking is used.

 DEFAULT KEY DEFINITIONS AND ACTIONS (with no UDF)

 KEY PRESSED     ACTION TAKEN
 -----------     ------------
 ENTER           Exit C_PICK(), return current element number
 ESC             Exit C_PICK(), return zero
 SPACE           Toggle item mark on/off
 HOME            Display first full page, highlight first item
 END             Display last full page, highlight last item
 PGUP            Display previous page, highlight first item
 PGDN            Display next full page, highlight first item
 UP-ARROW        Highlight previous item, scroll window up if at top
 DN-ARROW        Highlight next item, scroll window down if at end
 RT-ARROW        Pan right 10 characters (if text wider than window)
 LT-ARROW        Pan left 10 characters (if text wider than window)
 CTRL-RT-ARROW   Pan right, all the way (if text wider than window)
 CTRL-LT-ARROW   Pan left, all the way (if text wider than window)
 A-Z, a-z, 0-9   Search for first item matching last key pressed

 PARAMETERS AND RETURN VALUES FOR THE UDF

 The user-defined function for C_PICK() receives the following
 parameters when called:

 Mode - current mode state of C_PICK(), where:
   0 = Startup
   1 = Request action
   2 = Report previous action
 Prev_action - the previous action taken by C_PICK()
 Scrn_pos - current screen row for highlighted item
 Index - current array index for highlighted item
 Max_index - maximum array index
 Pan_offset - current offset of position left and right (1 is startup)
 Max_offset - maximum offset for panning

 The following codes can be returned to C_PICK() to tell it what
 action to perform:

 -1 = Ignore key, continue
 0  = Exit C_PICK(), return 0
 1  = Exit C_PICK(), return current element number
 2  = Perform default action based on last key pressed (automatic mode)
 3  = Request character search based on last key pressed
 4  = Redisplay current screen in window
 5  = Toggle item mark on/off
 6  = Toggle item mark for ALL on/off
 10 = Top of list
 11 = Bottom of list
 12 = Page up
 13 = Page down
 14 = Scroll up one
 15 = Scroll down one
 20 = Pan right - all the way
 21 = Pan left - all the way
 22 = Pan right - 10 columns
 23 = Pan left - 10 columns
 28 = Pan left - 5 columns
 29 = Pan left - 10 columns

 C_PICK() FUNCTIONS CALLED FROM THE UDF (SEEK, MOVE, RESIZE WINDOW)

 FUNCTION: _pseek(seek_first, string)

 seek_first (N) indicates whether the search should begin at the top
 or continue from the current position.  Specify zero (0) to begin
 at the top or one (1) to continue from the current position.
 string (C) is the character string or single character to find.

 Returns:  _pseek() returns true (.T.) if the string was found or
 false (.F.) if not found.

 FUNCTION: _pmove(dir, count)

 dir (C) is the direction to move the window. (U=Up, D=Down, R=Right, L=Left)
 count (N) is the number of rows or columns to move the window in
 the direction specified by dir.

 Returns:  _pmove() returns true (.T.) if the window was
 successfully moved or false (.F.) if the window could not be moved.

 FUNCTION: _psize(dir, count)

 dir (C) is the direction to resize the window starting from the
 bottom going up and down or from the right going left and right.
 (U=Up, D=Down, R=Right, L=Left)
 count (N) is the number of rows or columns to resize the window in
 the direction specified by dir.

 Returns:  _psize() returns true (.T.) if the window was
 successfully resized or false (.F.) if the window could not be resized.

 RETURNS

 C_PICK() returns the currently highlighted array element.  Use
 Clipper's LASTKEY() function to determine the keystroke used to exit.

 EXAMPLES

 private arr[4]
 arr[1] = "Item 1"
 arr[2] = "Item 2"
 arr[3] = "Item 3"
 arr[4] = "Item 4"

 setcolor("W/B")
 clear

 ** Call using all defaults
 c_pick(5,5,10,14,arr)


 ** Call using other options and mark array.
 private amark[len(arr)]
 t1 = "Options"
 c_pick(5,5,10,14,arr,3,"W/R,N/BG",2,t1,"",0,0,"PICK_UDF",.f.,AMARK)


 ** Call again starting at item 3 instead of 1
 private amark[len(arr)]
 t1 = "Options"
 xstart = 3
 c_pick(5,5,10,14,arr,3,"W/R,N/BG",2,t1,"",xstart,0,"PICK_UDF",.f.,AMARK)


 Note that in the examples above, the code for the callable UDF
 "PICK_UDF" is contained in the file UDF_PICK.PRG on the ClipOn diskette.