IListBox

The IListBox class extends the list box function in IBaseListBox to include adding, removing, and replacing list box items. List boxes always have vertical scroll bars. Optionally, they can have horizontal scroll bars.

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 IListBox:

Windows Considerations

When the horizontal scroll bar style is specified, the horizontal scroll bars are shown only if the width of the list box is smaller than the width of the largest list box item. Otherwise, Windows hides the scroll bar.


IListBox - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IListBox


Overload 1
public:
IListBox(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:
IListBox(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:
IListBox( 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 IListBox you construct. 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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Add Items

Use these members to add items to the list box. You can add items to the list box at the following positions:

Represent the new text item by either a resource identifier or the text string itself.


[view class]
add

Inserts the line of text at a specified location in the list box.


Overload 1
public:
virtual unsigned long add( unsigned long index, const char * const* itemList, unsigned long count = 1 )

Inserts items corresponding to the itemList text strings into the list box and returns the index of the first item inserted.

index
Index position of the item in the list. If the index is greater than the number of items, the text is inserted at the end of the list.
itemList
An array of character strings.
count
Number of text items in itemList. The default is 1 item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IListBox& add(const char* item, Cursor& cursor)

Inserts text into the list box at the cursor position and sets the cursor to the inserted item.

item
The text you want to insert.
cursor
A list box cursor object. The cursor's position identifies where to insert the item in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual unsigned long add( unsigned long index, const char* text )

Inserts text into the list box and returns the index of the item.

index
Index position of the item in the list. If the index is greater than the number of items, the text is inserted at the end of the list.
text
The text you want to insert.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
virtual IListBox& add( const IResourceId& text, Cursor& cursor )

Inserts text into the list box at the cursor position and sets the cursor to the inserted item.

text
Resource ID of the text you want to insert into the list.
cursor
A list box cursor object. The cursor's position identifies where to insert the item in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
virtual unsigned long add( unsigned long index, const IResourceId& item )

Inserts the text corresponding to the resource item into the list box and returns the index of the item.

index
Index position of the item in the list. If the index is greater than the number of items, the text is inserted at the end of the list.
item
Resource ID of the text you want to insert in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addAscending

Inserts the line of text in ascending sort order.


Overload 1
public:
virtual unsigned long addAscending(const char* text)

Inserts text into the list box in ascending sort order and returns the index of the inserted item.

text
The text you want to insert.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

Adds on OS/2 and Windows are not case-sensitive, but AIX is case-sensitive where upper case characters appear before lower case when add ascending.


Overload 2
public:
virtual unsigned long addAscending(const IResourceId& item)

Inserts the text, corresponding to the resource identifier, into the list box in ascending sort order and returns the index of the inserted item.

item
Resource ID of the text you want to insert in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

Adds on OS/2 and Windows are not case-sensitive, but AIX is case-sensitive where upper case characters appear before lower case when add ascending.


[view class]
addAsFirst

Inserts the line of text as the first item in the list box.


Overload 1
public:
virtual IListBox& addAsFirst( const char* item, Cursor& cursor )

Inserts the text as the first item in the list box and puts the cursor on the inserted item.

item
The text you want to insert.
cursor
A list box cursor object. The cursor is set to the first item in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual unsigned long addAsFirst(const char* text)

Inserts the text as the first item in the list box.

text
The text you want to insert.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual unsigned long addAsFirst(const IResourceId& item)

Inserts the text, corresponding to the resource identifier, as the first item in the list box.

item
Resource ID of the text you want to insert in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
virtual IListBox& addAsFirst( const IResourceId& text, Cursor& cursor )

Inserts the text, corresponding to the resource identifier, as the last item in the list box and puts the cursor on that item.

text
Resource ID of the text you want to insert in the list.
cursor
A list box cursor object. The cursor is set to the first item in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addAsLast

Inserts the line of text as the last item in the list box.


Overload 1
public:
virtual unsigned long addAsLast(const IResourceId& item)

Inserts the text, corresponding to the resource identifier, as the last item in the list box.

item
Resource ID of the text you want to insert in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IListBox& addAsLast( const char* item, Cursor& cursor )

Inserts the text as the last item in the list box and puts the cursor on that item.

item
The text you want to insert.
cursor
A list box cursor object. The cursor is set to the last item in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual unsigned long addAsLast(const char* text)

Inserts the text as the last item in the list box.

text
The text you want to insert.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
virtual IListBox& addAsLast( const IResourceId& text, Cursor& cursor )

Inserts the text, corresponding to the resource identifier, as the last item in the list box and puts the cursor on that item.

text
Resource ID of the text you want to insert in the list.
cursor
A list box cursor object. The cursor is set to the last item in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addAsNext

Inserts the line of text in the list box after the cursor.


Overload 1
public:
virtual IListBox& addAsNext( const char* item, Cursor& cursor )

Inserts the text after the current cursor position in the list box and places the cursor on that item.

item
The text you want to insert.
cursor
A list box cursor object. The cursor's position identifies where to insert the item in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IListBox& addAsNext( const IResourceId& text, Cursor& cursor )

Inserts a new text item, corresponding to the resource identifier, after the current cursor position in the list box and places the cursor on that item.

text
Resource ID of the text you want to insert in the list.
cursor
A list box cursor object. The cursor's position identifies where to insert the item in the list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addDescending

Inserts the line of text in descending sort order.


Overload 1
public:
virtual unsigned long addDescending(const char* text)

Inserts the line of text in descending sort order and returns the index of the item inserted.

text
The text string to be inserted into the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual unsigned long addDescending( const IResourceId& item )

Inserts the line of text, corresponding to the resource identifier, in descending sort order and returns the index of the item inserted.

item
The resource ID of the text string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Fonts


[view class]
setFont
public:
virtual IWindow& setFont(const IFont& font)

Sets the font of the listbox to the indicated font.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

These INotificationId members define the possible notifications that IListBox provides to its observers. The following events can be observed:


[view class]
addId
public:
static INotificationId const addId

This notification identifier is the notification IListBox objects provide their observers when an item is added to the list box. The number of items added is provided in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeId
public:
static INotificationId const removeId

This notification identifier is the notification IListBox objects provide their observers when an item is removed from the list box. The number of items removed is provided in the INotificationEvent::eventData field of the INotificationEvent. If the value is 0, all items were removed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Remove and Replace Items

Use these members to remove items from or replace items in the list box.


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

Removes the specified item from the list box and returns the count of items that remain.

index
The index of the text string that is removed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeAll
public:
virtual IListBox& removeAll()

Removes all items from the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeAt
public:
virtual IListBox& removeAt(Cursor& cursor)

Removes the item at the cursor and places the cursor at the next available valid item.

cursor
A list box cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
replaceAt

Replaces the list box item at the cursor position. An invalid cursor causes an exception.


Overload 1
public:
virtual IListBox& replaceAt( const char* item, const Cursor& cursor )

Replaces the item's string at the cursor with the new text.

item
The text string.
cursor
A list box cursor object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IListBox& replaceAt( const IResourceId& text, const Cursor& cursor )

Replaces the item's string at the cursor with the text corresponding to the resource identifier.

text
The resource ID of the text string to replace in the list box.
cursor
A list box cursor object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

Use these members to define, set, and retrieve the IListBox default style.
Note: The IListBox class inherits its style behavior from IBaseListBox except for the default style members described here.


[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]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent list boxes.

style
Use the styles provided by IListBox 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]
classDefaultStyle
public:
static const Style classDefaultStyle

Provides the original default style for this class, which is the following: IBaseListBox::horizontalScroll | IBaseListBox::noAdjustPosition | 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


IListBox - Type Definitions


[view class]
Cursor
typedef IBaseListBox::Cursor Cursor

This typedef supports prior use of the IListBox::Cursor class, which now exists in IBaseListBox.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IListBox - Inherited Member Functions and Data

Inherited Public Functions

IBaseListBox
IControl
INotifier
IWindow

Inherited Public Data

IWindow
INotifier
IBaseListBox

Inherited Protected Functions

IWindow
INotifier
IBaseListBox
IControl

Inherited Protected Data