DCHOICE.PRG
Version 1.0 : Copyright Rik Hess, July 1 1988
Version 1.1 : Copyright Rik Hess, August 21 1988
All Rights Reserved

DCHOICE is an effort to create a flexible, easy to use way to display
and choose from array items on screen. The routines 'dbedit' and 'achoice'
which are supplied with Clipper have deficiencies in their key-value
handling that prompted the development of DCHOICE.

One of the biggest differences between this utility and the others mentioned
is that the user can supply an array of "inkey()" values which will cause
the routine to exit for further processing by the calling routine. This means
that ANY key can have special significance and be responded to by DCHOICE.

Other significant points in DCHOICE are its ability to size the display to
fit the information given; the ability to choose a highlighted or normal
color; the ability to choose an optional shadow; and the ability to start
the highlight selection bar at a predetermined starting point in the array.

The first three paramaters are the window control parameters. The calling
routine supplies the top row, left column and max bottom row. The right
column is determined by the length of the first item in the array (this
assumes all items in the array are the same length). If there are fewer
items in the array than the max bottom column would hold, the bottom of
the box is "floated" up to eliminate the blank space.

The fourth and fifth parameters are the data array name and the number of
entries when DCHOICE is called. Upon return the fifth parameter contains
the index to the active array entry selected.

The sixth and seventh parameters control the exit value processing. The name
of the exit value array is the sixth parameter and the number of values in
this array is the seventh. On return the seventh parameter contains the index
of the exit key value.

The eighth and nineth parameters are logical values that control shadowing
or highlighing of the box. The tenth and eleventh parameters are optional
title and footer lines for the box. The twelveth parameter is the index
number of the array entry to be highlighted as active when DCHOICE is called.

Unless overridden by supplying the inkey() value an exit value, the following
keys have the indicated meaning:
Return - Select the indicated item
Esc - Abort DCHOICE
Up Arrow - Move up 1 item
Down Arrow - Move down 1 item
Home - Move to the first array entry
End - Move to the last array entry
PgUp - Move up 1 screen full
PgDn - Move down 1 screen full

The sample program "DTEST.PRG" shows two examples of calling DCHOICE with the
same information in different fashions. The sample data file has a few entries
composed of Name and Balance. The first display shows them in Name order while
the second is in Balance order.


VERSION UPDATES

Version 1.1 - Adds a check for HELP. Because "inkey()" is not a system "wait
state, the system does not recognize the key if pressed.
DCHOICE now checks for a call to HELP and calls it directly
with appropriate paramaters.
- Minor bugs fixed and some code streamlined.

If you have any comments on this technique, please contact me at:
Rik Hess
2237 Quail Run Rd.
Arlington, Texas 76014