Class XbpCombobox()

Class function of the XbpCombobox class.

The XbpCombobox class provides the combo box dialog element. Combo boxes combine an entry field (XbpSLE) with a list box (XbpListBox). The list box makes a limited set of values available to the user. The value selected is entered into the entry field. The list box portion of the combo box can either be permanently displayed or can be dropped down to display available values in response to a mouse click. The user may also choose to input data in the entry field using the keyboard rather than picking from the list box. If a combo box is defined as READONLY, no characters can be entered in the entry field. In this case, the range of values is limited to the items in the list box.

Most of the instance variables and methods of a combo box are described in the discussion of the XbpSLE and XbpListbox classes. This includes discussion of how keyboard and mouse events are processed. The only additional key combination that is processed by a combo box is Alt+Down Arrow. This is used to drop down the list box.

Special characteristics with the combo box

During XbpCombobox object creation, care should be taken in assigning the height of the combo box with the <aSize> parameter. The height includes both the entry field and the list box, even when the list box is hidden and is only opened following a mouse click.

The height of the entry field of the combo box is automatically adjusted to the selected font. The height cannot be set by the user.

Accessing data with a combo box

For all Xbase Parts, the :getData() method retrieves the value (or values) of the edit buffer of the dialog element. Since the combo box is a combination of two dialog elements there are two possible values that can be retrieved. In the class hierarchy XbpListBox comes first. Thus, calling methods that exist in both classes are executed by the XbpListBox by default:

aItems := oCombobox:getData()             // list box values

The method :getData() exists in the XbpSLE as well as the XbpListBox classes and the class XbpCombobox is derived from both of these classes. Because of this, the :getData() method of either part of the resulting combo box must be explicitly called using what is called a "cast". This is done by including the class name. In order to read the value of the entry field or the position of the marked value in the list box, the methods must be called as shown below:

                                           // return value: 
cBuffer := oCombobox:XbpSLE:getData()      // from entry field 
aItems  := oCombobox:XbpListBox:getData()  // from list box

Similar calls must be made for the :setData() method and all other methods with the same identifier in both the XbpSLE and XbpListBox class. The affected methods are those implemented in the DataRef class.

Data access via :dataLink code block

Since the XbpCombobox class inherits the :dataLink member variable from two super classes, the behavior of an XbpCombobox object depends on which :dataLink a data code block is assigned to. The methods :setData(), :getData(), :editbuffer() and :undo()evaluate the :dataLink code block in the same way as in the super classes. Data access via :dataLink code block is then accomplished like in the XbpSLE class or in the XbpListbox class.

Using a combo box as an entry field (XbpSLE)

An XbpCombobox object can be used as an entry field accessing memory or field variables:

oCombobox := XbpCombobox():New():Create( .. ) 
oCombobox:addItem( "Red"   ) 
oCombobox:addItem( "Green" ) 
oCombobox:addItem( "Blue"  ) 

// A database field COLOR of type Character exists 
// The data code block processes a character string 
bData := {|c| IF( c != NIL, FIELD->COLOR := c, FIELD->COLOR ) } 

// Assign data code block to the XbpSLE part of the combo box 
oCombobox:XbpSLE:dataLink := bData 

// :getData() of the XbpSLE class is automatically executed 
? ValType( oCombobox:GetData() ) // --> "C"

Using a combo box as a selection list (XbpListbox)

oCombobox := XbpCombobox():New():Create( .. ) 
oCombobox:addItem( "COM1" ) 
oCombobox:addItem( "COM2" ) 
oCombobox:addItem( "COM3" ) 

// A database field PORT of type Numeric exists 
// The data code block processes an array of numerics 
bData := {|a| IF( !Empty(a), FIELD->PORT := a[1], {FIELD->PORT} ) } 

// Assign data code block to the XbpListbox part of the combo box 
oCombobox:XbpListbox:dataLink := bData 

// :getData() of the XbpListbox class is automatically executed 
? ValType( oCombobox:GetData() ) // --> "A"

Creates an instance of the XbpCombobox class.

The instance variables in this group configure system resources. If changes are made to the default values, they must either be made before the :create() method is executed or the :configure() method must be used to activate the changes.

Specifies the cue banner text displayed by the combobox object.

Specifies the drawing mode of the combobox object.

Determines the combo box type.

Specifies the visual style to use for displaying items.

Requests system resources for the XbpCombobox object.

Reconfigures the XbpCombobox object after :create() has been executed.

Releases the system resources of the XbpCombobox object.

Displays a balloon-like window with information on the combo box.

Sets or returns whether the list box of the combo box currently has input focus.

Sets whether the edit field of the XbpCombobox object is READONLY.

Returns the size of the Listbox part of the Combobox.

Returns the size of the SLE part of the Combobox.

Marked item has been selected.

An item of a combobox object needs to be redrawn.

Compute dimensions of an owner-drawn combobox item.

Selection using a combo box


// This example shows the basic process for creating a combo 
// box. An array with the names of the weekdays is entered into 
// the combo box. A code block is also registered in the instance 
// variable :dataLink that assigns the currently selected item 
// in the entry field of the combo box to a LOCAL variable. 

#include "Appevent.ch" 
#include "Xbp.ch" 

PROCEDURE Main 
   LOCAL nEvent, mp1, mp2, oXbp, bAction 
   LOCAL oCombo, i, aDays, cDay := "Monday" 

   SetColor("N/W") 
   CLS 

   aDays := { "Monday" , "Tuesday"  , "Wednesday", "Thursday", ; 
              "Friday" , "Saturday" , "Sunday" } 

   // Create combo box with drop down list box 
   oCombo      := XbpCombobox():new() 
   oCombo:type := XBPCOMBO_DROPDOWN 
   oCombo:create( ,, {50, 100}, {200, 150} ) 

   // Link data from entry field to LOCAL variable 
   oCombo:XbpSLE:dataLink := {|x| IIf( x==NIL, cDay, cDay := x ) } 
   oCombo:XbpSLE:setData() 

   // Code block for selection: 
   //  - assign to LOCAL variable using :getData() 
   //  - display LOCAL variable using DispoutAt() 
   bAction := {|mp1, mp2, obj| obj:XbpSLE:getData(), ; 
               DispoutAt( MaxRow(), 0, PadR(cDay,20) ) } 

   // Assign code block for selection with Up and Down keys 
   oCombo:ItemMarked := bAction 

   // Assign code block for selection by left mouse click in list box 
   oCombo:ItemSelected := bAction 

   // Copy data from array to combo box, then discard array 
   FOR i := 1 TO 7 
      oCombo:addItem( aDays[i] ) 
   NEXT 
   aDays := NIL 

   // Event loop 
   nEvent := 0 
   DO WHILE nEvent <> xbeP_Close 
      nEvent := AppEvent( @mp1, @mp2, @oXbp ) 
      oXbp:HandleEvent( nEvent, mp1, mp2 ) 
   ENDDO 
RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Class XbpCombobox() Foundation