IBaseListBox

The IBaseListBox class creates and manages list box control windows. List boxes always have vertical scroll bars. Optionally, they can have horizontal scroll bars. IBaseListBox contains general list box function except for population capability, such as adding, removing, or replacing list box items. The derived classes IListBox and ICollectionViewListBox supply these functions. IListBox contains the add, remove, and replace functions, while ICollectionViewListBox populates a list box from collection elements via the setItems member function. Typically, you use one of these classes derived from IBaseListBox.

You can enable a list box for the following types of item selection techniques:

single selection
The user can select only one item at a time.
multiple selection
The user can select any number of items or not select any.
extended selection
The user can extend selection to more than one item.
These three techniques are mutually exclusive in one list box.

A list box operates as if it is a 0-based array of items. The item index requested or returned is the 0-based index number of the location of the item in question.

Handlers derived from the following classes handle events for IBaseListBox:

Portability Considerations

Motif does not support owner-draw list boxes. This is because the underlying XmList widget treats the list box entries as an array of textual data. The OS/2 operating system Presentation Manager list box control, on the other hand, accesses each list box entry as a separate item.

AIX Considerations

The Open Class Library implements the IBaseListBox class using the XmList widget. Motif application developers should note that the IBaseListBox member functions use 0-based indexes, unlike the Motif XmList functions, which use 1-based indexes.

The library creates scrolled list box controls using the XmCreateScrolledList convenience function. This convenience function creates a composite control consisting of an XmScrolledWindow parent with an XmList child. The IBaseListBox control's handle is the widget ID of the XmList child, and any application utilizing native Motif functions should reflect this.

Two selection styles, extendedSelect and multipleSelect, are available for IBaseListBox controls. There is no explicit single-selection mode style. In the AIX environment, the default selection style is the Motif XmList default selection policy, XmBROWSE_SELECT. This default selection policy is not forced by the Open Class Library. Therefore, you can use an application resource file to specify your desired XmNselectionPolicy. By using an application resource file, you can specify an XmNselectionPolicy of XmSINGLE_SELECT.

OS/2 Considerations

When you add an IBaseListBox as a child window of a canvas and use ISetCanvas, ISplitCanvas, or IMultiCellCanvas, you must give it the style IBaseListBox::noAdjustPosition.


IBaseListBox - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


[view class]
~IBaseListBox
public:
virtual ~IBaseListBox()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IBaseListBox


Overload 1
public:
IBaseListBox(unsigned long id, IWindow* parent)

You can create a list box control object using the parent window and a list box control ID.

id
The ID of a list box control.
parent
The parent window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IBaseListBox(const IWindowHandle& handle)

You can create a list box control object using the handle of an existing list box control.

handle
A window handle of an existing list box control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IBaseListBox( unsigned long id, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )

You can create a list box control object using the parent window, owner window, optional size and location, and optional style arguments.

id
The ID of a list box control.
parent
The parent window.
owner
The owner window.
initial
A rectangle for the list box control. It specifies the initial position and size of the IBaseListBox you construct. The initial position is the lower-left corner of the list box relative to the lower-left corner of the parent window. The default is the rectangle constructed by the default IRectangle constructor. Optional.
style
The initial style for the list box control. The classDefaultStyle is used if no style is provided. Optional.

Exception

IInvalidParameter The parent window is not valid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Colors

Use these members to access the colors of the IBaseListBox.


[view class]
backgroundColor
public:
virtual IColor backgroundColor() const

Returns the background color value of the list box area. If you have not set the color for the area, the default color is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

This member is overridden in this derived class for specific operating system behavior.


[view class]
setBackgroundColor
public:
virtual IBaseListBox& setBackgroundColor( const IColor& color )

Sets the background color to the specified color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setForegroundColor
public:
virtual IBaseListBox& setForegroundColor( const IColor& color )

Sets the foreground color to the specified color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Content

Use these members to determine the number of items in the list box.


[view class]
count
public:
virtual unsigned long count() const

Returns the number of items in the list box.
Note: You can use IBaseListBox::count and isSelected to process all of the selected list box items. However, it is easier to use the cursor facility provided by IBaseListBox::Cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isEmpty
public:
virtual bool isEmpty() const

If the list box is empty, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event-Handling Implementation

Event-handling implementation members provide the implementation of the event-handling mechanism.


[view class]
passEventToOwner
protected:
virtual bool passEventToOwner(IEvent& event)

Determines whether the event is be passed on to the owner.

Supported Platforms

Windows OS/2 AIX
Yes No Yes


Get and Change Items

Use these members to retrieve or change the text of an item in the list box.


[view class]
elementAt
public:
virtual IString elementAt(const Cursor& cursor) const

Returns the string of the item at the cursor position.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
itemText
public:
virtual IString itemText(unsigned long index) const

Returns the text of the specified item in the list box.

index
Index of the item in a list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setItemText

Changes the text of the specified item in the list box.

index
Index of the item in a list box.
string
The new text.


Overload 1
public:
virtual IBaseListBox& setItemText( unsigned long index, const IResourceId& string )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IBaseListBox& setItemText( unsigned long index, const char* string )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Handle Members

Use these members to set or retrieve a handle of a list box item. A handle is an optional data field that is associated with each list box item.


[view class]
itemHandle
public:
virtual unsigned long itemHandle(unsigned long index) const

Returns the handle of the specified list box item. If the item does not have a handle, 0 is returned.

index
Index of the item in a list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setItemHandle
public:
virtual IBaseListBox& setItemHandle( unsigned long index, unsigned long handle )

Sets the handle of the specified list box item.

index
Index of the item in a list box.
handle
Handle of the list box item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Item Changes

Use these members to set or retrieve the number of changes (add or remove items) that have occurred to the list box. These members help track the validity of IBaseListBox::Cursor objects.


[view class]
changeCount
protected:
unsigned long changeCount() const

Retrieves the number of changes to the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
incrementChangeCount
protected:
void incrementChangeCount()

Increments the count of the number of list box changes. All IBaseListBox-derived classes add and remove functions should call this function because add and remove functions may cause an IBaseListBox::Cursor to become invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Item Height

Use these members to set or retrieve a list box item's height.


[view class]
itemHeight
public:
unsigned long itemHeight(unsigned long index = 0) const

Returns the height, in pixels, of a list box item. This is not the font size. It is the height of the cell within which an item is displayed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

An index can be specified to retrieve the item height for a specific item when the listbox has the style LBS_OWNERDRAWVARIABLE.


[view class]
setItemHeight
public:
virtual IBaseListBox& setItemHeight( unsigned long newHeight )

Sets the height, in pixels, of a list box item. This does not change the font size. It changes the height of the cell within which an item is displayed.

Exception

IAccessError The operating system's request to set the height has failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Layout Support

Use these members to support canvases.


[view class]
minimumCharacters
public:
unsigned long minimumCharacters() const

Returns the maximum number of characters in an item of a minimum size list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
minimumRows
public:
unsigned long minimumRows() const

Returns the number of visible rows of a minimum size list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setLayoutDistorted
public:
virtual IBaseListBox& setLayoutDistorted( unsigned long layoutAttributesOn, unsigned long layoutAttributesOff )

Causes a parent ISetCanvas or IMultiCellCanvas to update the size and position of the list box when it is assigned a new font.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMinimumCharacters
public:
virtual IBaseListBox& setMinimumCharacters( unsigned long minimumCharacters )

Sets the maximum number of characters in an item of a minimum size list box. If you do not call this function, an item width of 25 characters is used.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMinimumRows
public:
virtual IBaseListBox& setMinimumRows( unsigned long minimumRows )

Sets the number of rows in a minimum size list box. If you do not call this function, four rows are shown.

minimumRows
Minimum number of visible rows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
calcMinimumSize
protected:
virtual ISize calcMinimumSize() const

Returns the minimum size of the list box.

The size dimensions are as follows:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

Use these members to identify and enable notifications sent to observer objects.


[view class]
enableNotification
public:
virtual IBaseListBox& enableNotification( bool enable = true )

Enables the list box to send notifications to any observer objects.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enterId
public:
static INotificationId const enterId

Notification identifier provided to observers when the user double-clicks on an item or presses Enter on an item with the cursor in a list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
extendedSelectChangedId
public:
static INotificationId const extendedSelectChangedId

Notification identifier provided to observers when the extended select state of the list box changes.

This ID is only used by collection view list boxes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
itemChangedId
public:
static INotificationId const itemChangedId

Notification identifier provided to observers when a list box item changes due to a change in the underlying collection element.

This ID is only used by collection view list boxes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
itemsId
public:
static INotificationId const itemsId

Notification identifier provided to observers when the collection underlying the collection view list box is changed.

This ID is only used by collection view list boxes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
selectId
public:
static INotificationId const selectId

Notification identifier provided to observers when an item is selected in a list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Scrolling Members

Use these members to scroll an item to the top of the list box or to return the item at the top of the list box.


[view class]
scrollToItem
public:
virtual IBaseListBox& scrollToItem(unsigned long index)

Scrolls the specified item into the listbox view. The item is scrolled to the top of the listbox if above the listbox view. If the item is below the view of the listbox, then the item is scrolled to the bottom of the listbox.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setTop
public:
virtual IBaseListBox& setTop(unsigned long index)

Scrolls the specified item to the top of the list box.

Exception

IAccessError There are no items in the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

The system scrolls the list box contents so that either the specified item appears at the top of the list box or the maximum scroll range has been reached.

Windows Considerations

The system scrolls the list box contents so that either the specified item appears at the top of the list box or the maximum scroll range has been reached.


[view class]
top
public:
virtual unsigned long top() const

Returns the item number of the item currently at the top of the list box. If there are no items in the list box, an exception is thrown.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Search List

Use these members to search the list box portion of the combination box for a text string. The data structures aid that effort.


[view class]
locateText
public:
virtual unsigned long locateText( const char* searchString, bool caseSensitive = true, SearchType search = exactMatch, unsigned long index = first ) const

Returns the item number of the list box item matching the search string. You can specify the type of search by using the enumeration SearchType. If no match is found, this function returns notFound. If there is an error, an exception is thrown.

searchString
String to search for.
caseSensitive
Indicator of whether the search is case-sensitive. The default of true means the search is case-sensitive.
search
Use the enumeration SearchType to specify the type of search to perform. The default is exactMatch.
index
Index of where to start the search. The default is first. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the index parameter.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
first
public:
static const unsigned long first

Searches from the beginning of the string. This is a value for the index parameter of IBaseListBox::locateText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
notFound
public:
static const unsigned long notFound

Indicates no match is found. IBaseListBox::locateText returns this value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Selection

Use these members to set or query the list box's selection state.


[view class]
deselect
public:
virtual IBaseListBox& deselect(unsigned long index)

Removes the selection state from an item.

index
The index of the item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
deselectAll
public:
virtual IBaseListBox& deselectAll()

Removes the selection state from all items in the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isSelected
public:
virtual bool isSelected(unsigned long index) const

Returns the selection state of an item. If the item is selected, true is returned. Otherwise, false is returned.
Note: You can use count and isSelected to process all of the selected list box items. However, it is easier to use the cursor facility provided by IBaseListBox::Cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
numberOfSelections
public:
virtual unsigned long numberOfSelections() const

For single-selection list boxes, if no item is selected, 0 is returned. Otherwise, 1 is returned.

For multiple-selection or extended-selection list boxes, the number of selected items in the list box is returned.
Note: In all cases, the current selection does not change.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
select
public:
virtual IBaseListBox& select( unsigned long index, bool select = true )

Sets the selection state of an item based on the specified boolean value.

index
Index of the item.
select
If you specify true for a list box, based on its selection style, the following occurs:
Single selection
The specified item is selected and any previously selected item is deselected.
Multiple selection
The specified item is selected.
Extended selection
The specified item is selected.
The default is true.
Note: In all cases, if you specify false, the item is deselected.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
selectAll
public:
virtual IBaseListBox& selectAll()

Sets the selection state for all items in the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

An exception is thrown on OS/2 and Windows if the listbox is single-selection. On AIX, the last item in the listbox is selected.


[view class]
selection
public:
virtual long selection() const

Returns the 0-based index of the selected item. For single-selection list boxes, the index of the selected item is returned. For multiple-selection or extended-selection list boxes, the index of the first selected item is returned.
Note: If no item is selected, the static constant notFound is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

These style members provide a set of valid styles for the IBaseListBox class. Use these members to set and query list box styles. You can use these styles with the styles in the IWindow Styles class.


[view class]
convertToGUIStyle
public:
virtual unsigned long convertToGUIStyle( const IBitFlag& style, bool extendedOnly = false ) const

Converts a style object into a value appropriate for the presentation system. The default action is to return the base GUI styles for the platform. Extended styles, those defined by the application and the Open Class Library, are returned if you set extendedOnly to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the default style. The default style is classDefaultStyle unless you have changed the style using setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
disableDrawItem
public:
virtual IBaseListBox& disableDrawItem()

Disables the style drawItem for the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The drawItem style is not supported on AIX.


[view class]
disableExtendedSelect
public:
virtual IBaseListBox& disableExtendedSelect()

Disables the style extendedSelect for the list box.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

Windows Considerations

An IBaseListBox::Style is used to control this behavior. This platform does not support dynamic change of behavior.


[view class]
disableMultipleSelect
public:
virtual IBaseListBox& disableMultipleSelect()

Disables the style multipleSelect for the list box.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

Windows Considerations

An IBaseListBox::Style is used to control this behavior. This platform does not support dynamic change of behavior.


[view class]
disableNoAdjustPosition
public:
virtual IBaseListBox& disableNoAdjustPosition()

Disables the style noAdjustPosition for the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The noAdjustPosition style is ignored on AIX.


[view class]
enableDrawItem
public:
virtual IBaseListBox& enableDrawItem(bool enable = true)

Enables or disables the style drawItem for the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The drawItem style is not supported on AIX.


[view class]
enableExtendedSelect
public:
virtual IBaseListBox& enableExtendedSelect( bool enable = true )

Enables or disables the style extendedSelect for the list box.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

Windows Considerations

An IBaseListBox::Style is used to control this behavior. This platform does not support dynamic change of behavior.


[view class]
enableMultipleSelect
public:
virtual IBaseListBox& enableMultipleSelect( bool enable = true )

Enables or disables the style multipleSelect for the list box.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

Windows Considerations

An IBaseListBox::Style is used to control this behavior. This platform does not support dynamic change of behavior.


[view class]
enableNoAdjustPosition
public:
virtual IBaseListBox& enableNoAdjustPosition( bool enable = true )

Enables or disables the style noAdjustPosition for the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The noAdjustPosition style is ignored on AIX.


[view class]
isDrawItem
public:
bool isDrawItem() const

If the style drawItem is set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The drawItem style is not supported on AIX.


[view class]
isExtendedSelect
public:
bool isExtendedSelect() const

If the style extendedSelect is set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isHorizontalScroll
public:
bool isHorizontalScroll() const

If the style horizontalScroll is set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isMultipleSelect
public:
bool isMultipleSelect() const

If the style multipleSelect is set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isNoAdjustPosition
public:
bool isNoAdjustPosition() const

If the style noAdjustPosition is set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The noAdjustPosition style is ignored on AIX. This function always returns false.


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent list boxes.

style
Use the styles provided by IBaseListBox Styles to specify the default list box style.

This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default style on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.

When you create a window class and do not specifically specify window styles in the constructor, the Open Class Library queries the default style. Therefore, the only safe place to call this member function is when no other application threads that create windows are active.

Another way to avoid a conflict in a multithreaded application is to specifically specify window styles on window construction, rather than calling this member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
border3D
public:
static const Style border3D

Adds an etched 3D border to the control.

Supported Platforms

Windows OS/2 AIX
Yes Ignored Ignored


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Provides the original default style for this class, which is the following: IBaseListBox::horizontalScroll | IBaseListBox::noAdjustPosition | IBaseListBox::border3D | IWindow::visible.

If you do not specify either the extendedSelect or multipleSelect style, the list box is a single-selection list box by default.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
drawItem
public:
static const Style drawItem

Draws list box items. It is typically used to display bitmaps.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
extendedSelect
public:
static const Style extendedSelect

Extends selection to more than one object. This style is a type of selection optimized for the selection of a single object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
horizontalScroll
public:
static const Style horizontalScroll

Allows horizontal scrolling of the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
multipleSelect
public:
static const Style multipleSelect

Specifies that the user can select any number of objects at a time in the list box or not select any.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
noAdjustPosition
public:
static const Style noAdjustPosition

Draws the list box control at the size specified. This can cause an item to be only partially shown.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


Window Painting

Use these members to display a window.


[view class]
show
public:
virtual IWindow& show(bool showList = true)

Makes the window visible.
Note: Another window occurring earlier in the Z-order might still obscure this window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IBaseListBox - Enumerations


[view class]
SearchType
enum SearchType { prefix, 
                  substring, 
                  exactMatch }

Use these enumerators to specify the type of search to perform:

prefix
Matching occurs if the leading characters of the item contain the specified characters.
substring
Matching occurs if the item contains a substring of the specified characters.
exactMatch
Matching occurs if the item is an exact match for the specified characters.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IBaseListBox - Inherited Member Functions and Data

Inherited Public Functions

IControl
INotifier
IWindow

Inherited Public Data

IWindow
INotifier

Inherited Protected Functions

IWindow
INotifier
IControl

Inherited Protected Data