Class XbpListBox() Foundation

Class function of the XbpListBox class.

Superclass
Subclass
Description

The XbpListBox class provides the listbox dialog element. Listboxes display a finite number of values as a list (similar to Achoice()). Each list item is a character string and is individually added to the list using the :addItem() method. If there are more items in the list than can be shown in the display window of the listbox, a vertical scroll bar allows navigation through the list. Listboxes can also include an optional horizontal scroll bar. The maximum number of items that can be managed by an XbpListBox object is limited to 32 kB under Windows 95 and OS/2, while it is not limited under Windows NT.

There are three modes for marking and selecting items from the list: single selection mode, multiple selection mode and extended selection mode. The multiple selection mode allows several items to be marked in the list at one time. In the extended mode items can be marked using the mouse or special key combinations. Listboxes process some keys and events differently depending on the selection mode. The following table lists the keys processed in "single selection" mode:

Keys for the single selection mode of a list box
Key Description
Up Arrow Go to previous item
Down Arrow Go to next item
Home Go to beginning of list
End Go to end of list
Page Up Go up one page
Page Down Go down one page
Return Select current item
Letter Go to next item starting with this letter
Left mouse click Mark item, unmark previous
Double click left Mark item and select
Left Arrow *) Scroll four characters to the left
Right Arrow *) Scroll four characters to the right
Ctrl+Page Up *) Scroll one page to the left
Ctrl+Page Down *) Scroll one page to the right
  1. Only processed when a horizontal scroll bar is displayed

In "multiple selection" mode the selection is turned on or off when an item is clicked or by pressing the space bar.

The special keys Shift and Ctrl are supported in the "extended selection" mode. In addition, items are marked when the mouse is moved while the left button is pressed.

Keys for the multiple selection mode of list boxes
Key Description
Shift+Up Arrow Go to previous item and toggle the marking
Shift+Down Arrow Go to next item and toggle the marking
Shift+Home Go to beginning of list and toggle the marking of all items before the current item
Shift+End Go to end of list and toggle the marking of all items after the current item
Shift+Page Up Go one page up and toggle the marking
Shift+Page Down Go one page down and toggle the marking
Return Select all marked items
Shift+Letter Go to next item that begins with this letter
Shift+Blank space Mark items after pressing a letter
Shift+Left mouse click Toggle marking from current item to clicked item
Ctrl+Left mouse click Toggle marking only for the clicked item
Shift+Left Double click Select all marked items

Class methods
:new()
Creates an instance of the XbpListBox class.
Configuration

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

:adjustHeight
Adjusts the height of the listbox so that the items displayed are entirely visible.
:drawMode
Specifies the drawing mode of the listbox object.
:horizScroll
Determines whether to display a horizontal scroll bar.
:markMode
Determines the operating mode for marking and selecting items
:multiColumn
Determines whether items in the list box are displayed in multiple columns
:vertScroll
Determines whether a vertical scroll bar is displayed.
:visualStyle
Specifies the visual style to use for displaying items.
Life cycle
:create()
Requests system resources for the XbpListBox object.
:configure()
Reconfigures the XbpListBox object after :create() has been executed.
:destroy()
Releases the system resources of the XbpListBox object.
Selection
:getData()
Returns the selected items in the list box.
:getItemsHeight()
Returns the height of a single item in a list box
:getTopItem()
Returns the numeric index of the first item visible in the list box.
:getVisibleItems()
Returns the number of visible list box items
:numItems()
Returns the number of items in the list box.
:setData()
Sets which items in the list are selected.
:setItemsHeight()
Sets the display height of each item in the list box.
:setTopItem()
Sets the first item visible at the top of the list box.
Manipulation
:addItem()
Adds an item to the list of the list box.
:clear()
Deletes all the items in the list of the XbpListBox object.
:delItem()
Deletes an item from the list of the XbpListBox object.
:getItem()
Returns the item at the specified position in the list of the XbpListBox object.
:getTabstops()
Queries the tab stops of the listbox.
:insItem()
Inserts an item into the list of the XbpListBox object.
:setColumnWidth()
Sets the column width of a multicolumn listbox.
:setItem()
Changes the text for an item in the list of the XbpListBox object.
:setTabstops()
Sets the tab stops of the listbox.
Events
:hScroll
List has been scrolled horizontally.
:vScroll
List has been scrolled vertically.
:itemMarked
An item has been marked or the selection marking of an item has been removed.
:itemSelected
Marked items have been selected.
:drawItem
Informs the application that an item of an owner-drawn listbox needs to be redrawn.
:measureItem
Compute dimensions of an owner-drawn listbox item.
Examples
Selection using a listbox

// This example shows the basic process for creating a 
// listbox. The DbStruct() array of the database provides 
// the data source for the listbox and allows the selection 
// of one or more field names. Copying the field names from 
// the structure array into the listbox occurs in the UDF 
// ArrayToListBox(). The selected field names are copied from 
// the listbox into an array in the UDF ArrayFromListBox(). 

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

PROCEDURE Main 
   LOCAL nEvent, mp1, mp2, oXbp 
   LOCAL oListBox, aStruct 

   SetColor("N/W") 
   CLS 

   USE Customer NEW 
   aStruct := DbStruct() 
   CLOSE Customer 

   // Create list box that allows multiple selections 
   oListBox := XbpListbox():new() 
   oListBox:markMode := XBPLISTBOX_MM_MULTIPLE 
   oListBox:create( ,, {300, 100}, {200, 150} ) 

   // Copy field names from the DbStruct() array to the list box 
   ArrayToListBox( oListBox, aStruct ) 

   // Code block for list box selection: 
   //   The selected fields from the DbStruct() 
   //   array are displayed using QOut() 
   oListBox:ItemSelected := {|mp1, mp2, obj| ; 
       QOut( "Fields:", ArrayFromListBox( obj ) ) } 

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

************************************************************ 
* Copy array to list box 
************************************************************ 
FUNCTION ArrayToListBox( oListBox, aArray ) 
   LOCAL i := 0, imax := Len(aArray) 

   IF Valtype( aArray[1] ) == "A"    // 2-dim array 
      DO WHILE ++i <= imax           // copy first column 
         oListBox:addItem( aArray[i,1] ) 
      ENDDO 
   ELSE                              // 1-dim array 
      DO WHILE ++i <= imax           // copy array elements 
         oListBox:addItem( aArray[i] ) 
      ENDDO 
   ENDIF 
RETURN oListBox 

*************************************************************** 
* Copy marked items from list box to an array 
*************************************************************** 
STATIC FUNCTION ArrayFromListBox( oListBox ) 
   LOCAL aArray := oListBox:getData() // numeric indexes 
   LOCAL i := 0, imax := Len(aArray) 

   DO WHILE ++i <= imax               // assign character strings 
      aArray[i] := oListBox:getItem( aArray[i] ) 
   ENDDO 
RETURN aArray 
Feedback

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.