View source for @...GET - Lists

==Purpose==
Create a FoxPro style listbox


==Syntax==
@<expN1>,<expN2> GET <memvar>

FROM <array> [RANGE <expN3> [,<expN4>]] | POPUP <expC1>

FUNCTION <expC2> | PICTURE <expC3>

[COLOR SCHEME <expN5> | COLOR <expC4>]

[DEFAULT <exp>]

[DISABLE | ENABLE]

[FONT <expC5>[, <expN6>]]

[MESSAGE <expC6>]

[PROPERTIES <expC7>]

[SIZE <expN7>,<expN8>]

[STYLE <expC8>]

[VALID <expL1> | <expN9>]

[WHEN <expL2>]


==See Also==
[[@...GET]], [[@...SAY]], [[DECLARE]], [[DEFINE POPUP]], [[DIMENSION]], [[PRIVATE]], [[PUBLIC]], [[READ]], [[SET COLOR]], [[SET COLOR OF]], [[SET COMPATIBLE]], [[SET FILETYPE]]


==Description==
The @...GET command can be used to create FoxPro style listboxes.  Listboxes offer a scrolling list of choices for numeric or character values.  The top left hand corner of the listbox is positioned at row <expN1>, column <expN2>.  When an item is selected from the list, <memvar> is updated.  If the initial value of <memvar> is numeric, the position of the selected item is stored, if it is character, the prompt is stored.  The cursor keys and [PAGE UP], [PAGE DOWN] keys can be used to navigate within the list and the [SPACEBAR] or [RETURN] key or mouse click to select an item.

The list can be based either on the contents of a pre-declared one or two-dimensional array using the FROM <array> clause, or from a predefined popup using the POPUP <expC1> clause.  Popups are defined using the DEFINE POPUP command.

The optional RANGE <expN3> [,<expN4>] clause can be used with array based listboxes to restrict the array elements that appear in the listbox.  The <expN3> defines the number of the first array element to appear in the list and the optional <expN4> defines the number of elements to include.  If <expN4> is not defined, all elements starting from <expN3> are included in the list.

The FUNCTION clause or the PICTURE clause is required.  The ampersand character, '&' signals that the @…GET is a listbox:

<code lang="recital">
@...GET mchoice FUNCTION "&" ...
</code>
or
<code lang="recital">
@...GET mchoice PICTURE "@&" ...
</code>

The following options may also be included, immediately after the "&":


{| class="wikitable"
!Picture/Function Option||Description
|-
|N||READ is not terminated when item is chosen.
|-
|T||READ is terminated when item is chosen.
|-
|}


The following clauses can optionally be used:


{| class="wikitable"
!Keyword||Description
|-
|COLOR SCHEME <expN5>| COLOR <expC4>||The color of @...GET output can be specified by including a set of color pairs in the COLOR clause or specifying a numeric COLOR SCHEME <expN5>.  If you do not specify the COLOR | COLOR SCHEME clause then the @...GET is displayed in the default Color of Fields.  The color that is specified overrides the SET COLOR command, but only for the output of the current @…GET command.
|-
|DEFAULT <expr>||The DEFAULT clause specifies a default value for <memvar>.
|-
|DISABLE | ENABLE||If the DISABLE clause is included, the GET is not active and cannot be selected or modified.  GETs are enabled by default. READ will exit immediately if all GETs are marked DISABLE.
|-
|FONT <expC5>[, <expN6>]||The name of the font is specified in <expC5> and, optionally, the font size in <expN6>.
|-
|MESSAGE <expC6>||Defines a message to be displayed in the message line when the listbox is the active GET.
|-
|PROPERTIES <expC7>||The PROPERTIES clause can be used to specify properties for the listbox.  For information on the available properties, please see The Mirage Object Model in the Recital Mirage documentation.
|-
|SIZE <expN7>,<expN8>||Defines the size of the listbox, <expN7> is the height and <expN8> is the width.  By default, the width and height of the listbox are determined by the width of the widest item and the number of items in the list
|-
|STYLE <expC8>||The STYLE clause can include the following in <expC8>:
B = Bold

I = Italic

U = Underline

- = Strikeout
|-
|VALID <expL1> | <expN9>||The VALID clause does not carry out validation in this case, since the <memvar> has already been updated, but can be used to call a UDF (User Defined Function).  The VALID <expN9> option may be used with a function that returns a numeric value to select a GET for input.  GET numbers are assigned in the order that they appear on the screen.  The GETNO() function returns the number of the currently active get.  The numeric value returned can have three different effects.  When <expN9> is 0, the current GET remains in focus.  When <expN9> is positive, the value is used to advance the GET focus the number of GETS specified.  When <expN7> is negative, the value is used to move back the GET focus the number of GETS specified.
|-
|WHEN <expL2>||The listbox only allows selection when <expL2> evaluates to true (.T.).
|-
|}


==Example==
<code lang="recital">
declare listarray[3]
listarray[1] = "Apple"
listarray[2] = "Banana"
listarray[3] = "Orange"
mchoice = "Banana"
@10,10 get mchoice from listarray function "&"
read
</code>


==Products==
Recital Mirage Server, Recital Terminal Developer
[[Category:Documentation]]
[[Category:Commands]]
[[Category:Screen Forms]]
[[Category:Screen Forms Commands]]