xHarbour Reference Documentation > Command Reference

@...GET LISTBOX

Creates a Get object as list box and displays it to the screen.

Syntax

@ <nTop>, <nLeft>, <nBottom>, <nRight> ;
      GET <nVar>|<cVar> ;
  LISTBOX <aListItems> ;
 [CAPTION <cCaption>] ;
 [MESSAGE <cMessage>] ;
    [WHEN <lWhen>] ;
   [VALID <lValid>] ;
   [COLOR <cColor>] ;
   [FOCUS <bFocus>] ;
   [STATE <bState>] ;
    [SEND <msg>] ;
 [GUISEND <guimsg>] ;
[DROPDOWN] ;
[SCROLLBAR]

Arguments

@ <nTop>, <nLeft>, <nBottom>, <nRight>

Numeric values indicating the screen coordinates for the upper left and the lower right corner of the list box output. The range for rows on the screen is 0 to MaxRow(), and for columns it is 0 to MaxCol(). The coordinate 0,0 is the upper left corner of the screen.

GET <nVar>|<cVar>

This is the edited variable. It must be initialized either with a numeric value or as a character string. If it is numeric, the variable receives the ordinal position of the selected item held in <aListItems> when editing ends. When it is a character string, the selected item of <aListItems> is assigned.

LISTBOX <aListItems>

A one dimensional array holding character strings defines the list box items a user can select from.

CAPTION <cCaption>

This is a character string displayed as caption of the list box. The caption string may include an ampersand character (&) which marks the next character as accelerator key. Pressing the accelerator key allows the user to jump directly to the list box.

MESSAGE <cMessage>

This is an optional character string displayed in the message row when the list box has input focus. The message row is defined with the MSG AT option of the READ command.

WHEN <lWhen>

This is a logical expression or a code block returning a logical value. If specified, <lWhen> must result in .T. (true) to allow editing. If the expression yields .F. (false), the list box cannot receive input focus.

VALID <lValid>

This is a logical expression or a code block returning a logical value. If specified, <lValid> must result in .T. (true) to end list box selection. When the result is .F. (false), the currently selected item is invalid and the user cannot leave the list box unless the selection is cancelled.

COLOR <cColor>

The parameter <cColor> is an optional character string defining the colors for the display of the list box and its caption. It defaults to the current SetColor() setting. <cColor> must have up to eight color values (see ColorSelect()). They are used as follows:

Color values for list boxes

Color value	Description
1	Color for unselected list box items when the list box does not have input focus
2	Color for the selected list box item when the list box does not have input focus
3	Color for unselected list box items when the list box has input focus
4	Color for the selected list box item when the list box has input focus
5	Color for the list box's border
6	Color for the list box's caption
7	Color for the list box's accelerator key
8	Color for the list box's drop down button

FOCUS <bFocus>

This is an optional code block which is evaluated when the list box receives input focus. The code block is evaluated without parameters.

STATE <bState>

This is an optional code block which is evaluated when the list box's selection is changed by the user. The code block is evaluated without parameters.

SEND <msg>

This is an optional message to be sent to the Get object before it is displayed. Refer to the Get class for possible messages that can be sent to the Get object.

GUISEND <guimsg>

This is an optional message to be sent to the HbListbox() object associated with the Get() object before both are displayed. Refer to the HbListbox class for possible messages that can be sent to the list box object.

DROPDOWN

If this option is specified, the list box is initially displayed in one row and can be dropped down by pressing the Space key when the list box has input focus, or clicking the dowp down button.

SCROLLBAR

This option displays a scroll bar in the right border of the list box.

Description

The @...GET LISTBOX command creates a Get() object and assigns a HbListbox() object to the oGet:control instance variable. The HbListbox() object displays a list box in text mode and allows a user to select an item from a list of items within the READ command. The variable <aListItems> must be initialized with an array before READ is called.

The Get object created with @...GET LISTBOX is stored in the current Getlist array. The Get object communicates with the associated HbListBox object while the READ command is active. This communication ensures that focus and selection changes are properly displayed on the screen.

Info

See also:	@...GET, Get(), HbListbox(), HbScrollbar()
Category:	Get system , Input commands
Source:	rtl\listbox.prg
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example creates a normal and a drop down list box.

   #include "HbLang.ch"
   #include "Inkey.ch"

   PROCEDURE Main
      LOCAL aDays[7]
      LOCAL aHours[24]
      LOCAL cDay := "", nHour := 1
      LOCAL cColor := "N/BG,W+/BG,W+/BG,W+/R,GR+/BG,N/BG,GR+/BG,N/R"

      FOR i:=1 TO 7
         aDays[i] := HB_LangMessage( HB_LANG_ITEM_BASE_DAY + i-1 )
      NEXT

      FOR i:=1 TO 24
         aHours[i] := Padl( i-1, 2, "0" ) + ":00"
      NEXT

      SET EVENTMASK TO INKEY_ALL
      SET COLOR TO ( cColor )
      CLS
      @  3, 15,  7, 25 GET cDay ;
                   LISTBOX aDays ;
                   CAPTION "Select &day " ;
                     COLOR cColor

      @ 10, 15, 20, 25 GET nHour ;
                   LISTBOX aHours ;
                   CAPTION "Select &hour" ;
                     COLOR cColor ;
                  DROPDOWN SCROLLBAR
      READ

      ? "Day :", cDay
      ? "Hour:", aHours[nHour], nHour-1
   RETURN