ChoiceControl

  + Object
    + Display
      + UIComponent
        + Control
          + ChoiceControl

The ChoiceControl class implements the behaviours common to controls offering a choice of several elements. Its derived classes are List and Popup. This class is not instantiable, derivable or cloneable. The only instances available to the programmer are those automatically generated by HB++ when you place a control on a form.

The majority of the methods of this class manage the element list displayed in the List and Popup controls. The AddItem adds an element whilst the RemoveItem and Clear methods delete one or all the list elements. The Change event is raised when the user modifies the selection. The ListIndex property stores the index of the selected list element.

The Sorted property offers four sorting options. When a sort is active, the order of the list elements do not necessarily correspond to their insertion order. The NewIndex property can be used to find out the index of the last element inserted. The best method for retrieving an element is by associating it a numeric value using the ItemData property.

This numeric value is stored in a variable of type Long value and can be any data necessary for your program to work properly.Typically, it acts as a unique identifier for a list element and can be a record number in a database, an array index, a type identifier, a color etc.

The following example shows how to fill a list with the records from tblCustomer. The UniqueID fields are stored in the ItemData property of each element and allow quick retrieval of the record corresponding to the element chosen by the user.

Private db as New tblCustomer

Private Sub Form_Load()
  db.OpenTable hbModeOpenExisting+hbModeReadOnly
  If db.RecordCount<>0 Then
    List1.Redraw = False
    While Not db.EOF
      List1.AddItem db.Name, db.UniqueID
      db.MoveNext
    Wend
    List1.Redraw = True
    List1.Sorted = hbSortText
  End If
End Sub

Private Sub Form_Unload()
  db.Close
End Sub

Private Sub List1_Change()
  Dim k as Integer

  k = List1.ListIndex
  If k>=0 Then
    db.LookupUniqueID List1.ItemData(k)
    MsgBox "Selected item : " & db.Name
  End If
End Sub

The List and Popup controls are not designed to contain more than a hundred elements. Above this number, performance can significantly degrade and navigation can become difficult for the user. If you want to display a large number of elements, you should use the Grid control instead.

Note: The PenMove event is never sent by objects derived from this class, but intercepted internally.

Members	Description

AddItem	Adds an item to a list.
Change	Event raised when a new item is selected in the list.
Clear	Deletes all the items in a list.
FindItemData	Finds an item in a list from its value.
FindString	Finds an item in a list from its caption.
ItemData	Value associated with a list item.
List	Caption of an item in a list.
ListCount	Number of items in a list.
ListIndex	Item selected in a list.
NewIndex	Index of the last inserted item.
Redraw	Determines whether the control is updated each time the list is modified.
RemoveItem	Deletes an item.
Sorted	List elements sort criteria.
SortItems	Event raised when the control must compare two items.

Inherited from Control	Description

DrawFocusRing	Draws the focus ring.
GotFocus	Event raised when the control gains the focus.
Layer	Layer to which the control belongs.
LostFocus	Event raised when the control loses the focus.
NavFlags	Navigation flags for the control.
RemoveFocusRing	Erase the focus ring.
Tag	String associated with the control.
Visible	Indicates if a control is visible or not.

Inherited from UIComponent	Description

ComponentToScreen	Converts coordinates relative to a component into coordinates relative to the screen.
FiveWayNavigator	Event raised when the user presses one of the 5-way navigator keys.
Height	Element height.
Left	Distance between the left edge of the form and the left edge of the element.
Move	Moves or resizes an element.
PenDown	Event raised when the user touches an UI element with the stylus.
PenMove	Event raised when the user moves the stylus.
PenUp	Event raised when the user releases the stylus.
ScreenToComponent	Converts coordinates relative to the screen into coordinates relative a component.
Top	Distance between the top edge of the form and the top edge of the element.
UIRef	Internal reference to a control.
Width	Element width.

Inherited from Display	Description

Arc	Draws an arc.
BackColor	Background color.
BatchLimit	Size of the graphics instruction buffer.
CoordinateSystem	Coordinates system.
CopyArea	Efficiently copies part of a Display object to another.
DrawFont	Font used to draw the text.
Flush	Empties the graphics instruction buffer.
FontMetrics	Returns a FontMetrics object describing the physical charateristics of the currently active font.
ForeColor	Foreground color.
GetPixel	Queries the color of a given pixel.
hWin	Returns the window handle.
Line	Draws a line.
Oval	Draws a circle or ellipse.
Pattern	Defines the pattern used to fill drawings.
Polygon	Draws a polygon.
PutPixel	Sets the color of a pixel.
Rectangle	Draw a rectangle.
ResID	Identifier of the resource associated with the object.
ScaleFont	Enable or disable font scaling.
TextColor	Text color.
TextOut	Draw text.

Inherited from Object	Description

ClassID	Returns the type identifier corresponding to the actual class of the object.
Implements	Determines whether the object implements the features of a given class.
Iterate	Event raised to iterate over the elements of a container object.
Recipient	Recipient of events sent by the object.
Serialize	Event raised to serialize the object content into a stream.

System	Minimal version	Remarks

Palm OS	Palm OS 3.0	N/A