IComboBox

The IComboBox class extends the IBaseComboBox combination box's control window creation and management to include adding, removing and replacing items in the combination box list box.

Handlers derived from the following classes handle events for IComboBox objects:

AIX Considerations

Handlers derived from IEditVerifyHandler can be attached to IComboBox objects.


IComboBox - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IComboBox


Overload 1
public:
IComboBox(const IWindowHandle& handle)

You can construct objects of this class using the handle of an existing combination box window.

handle
The window handle of an existing combination box control.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

You can construct objects of this class using the ID, parent, owner, size, position, and style parameters.

id
A combination box control ID.
parent
The parent window.
owner
The owner window.
initial
The initial position and size of the combination box you construct. The default is the rectangle constructed by the default IRectangle constructor. Optional.
style
The combination box's characteristics. Optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IComboBox(unsigned long id, IWindow* parent)

You can construct objects of this class using the parent window and a combination box ID.

id
A combination box control ID.
parent
The parent window.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Add Items

Use these members to add items to the list box portion of the combination 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 portion of the combination 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 portion of the combination 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 IComboBox& add(const char* text, Cursor& cursor)

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

text
The text you want to insert.
cursor
A combination 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 portion of the combination box and returns the index of the item.

text
The text you want to insert.
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
virtual IComboBox& add( const IResourceId& item, Cursor& cursor )

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

item
Resource ID of the text you want to insert in the list.
cursor
A combination 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 text corresponding to the resource item into the list box portion of the combination 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 portion of the combination 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


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

Inserts the text, corresponding to the resource identifier, into the list box portion of the combination 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


[view class]
addAsFirst

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


Overload 1
public:
virtual IComboBox& addAsFirst( const char* text, Cursor& cursor )

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

text
The text you want to insert.
cursor
A combination 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 portion of the combination 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 portion of the combination 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 IComboBox& addAsFirst( const IResourceId& item, Cursor& cursor )

Inserts the text, corresponding to the resource identifier, as the first item in the list box portion of the combination box and puts the cursor on that item.

item
Resource ID of the text you want to insert in the list.
cursor
A combination 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 portion of the combination 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 portion of the combination 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 IComboBox& addAsLast( const char* text, Cursor& cursor )

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

text
The text you want to insert.
cursor
A combination 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 portion of the combination box.

text
The text you want to insert.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
virtual IComboBox& addAsLast( const IResourceId& item, Cursor& cursor )

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

item
Resource ID of the text you want to insert in the list.
cursor
A combination 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 portion of the combination box after the cursor.


Overload 1
public:
virtual IComboBox& addAsNext( const char* text, Cursor& cursor )

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

text
The text you want to insert.
cursor
A combination 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 IComboBox& addAsNext( const IResourceId& item, Cursor& cursor )

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

item
Resource ID of the text you want to insert in the list.
cursor
A combination 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 text into the list box portion of the combination box in descending 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


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

Inserts the text, corresponding to the resource identifier, into the list box portion of the combination box in descending 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


Notification Members

These INotificationId members define the possible notifications that IComboBox provides to its observers. The following events can occur:


[view class]
addId
public:
static INotificationId const addId

This notification identifier is the notification IComboBox objects provide their observers when an item is added to the list box portion of the combination 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 IComboBox objects provide their observers when an item is removed from the list box portion of the combination 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 portion of the combination box.


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

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

index
The index of the text item to remove.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Removes all items from the list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Removes the item at the cursor position and sets the cursor to the item following the removed item.

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 IComboBox& replaceAt( const char* text, const Cursor& cursor )

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

text
The text string.
cursor
A combination box cursor object. It must be valid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IComboBox& replaceAt( const IResourceId& item, const Cursor& cursor )

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

item
The resource ID of the text string to replace in the list box portion of the combination box.
cursor
A combination box cursor object. It must be valid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

Use these members to define, set, and retrieve the IComboBox default style.
Note: The IComboBox class inherits its style behavior from IBaseComboBox 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 it 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 combination boxes.

style
Use the styles provided by IComboBox Styles to specify the default 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: IComboBox::simpleType | IComboBox::anyData | IWindow::visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

For Windows, IBaseComboBox::autoScroll and IBaseComboBox::border3D are also part of the default style.


IComboBox - Type Definitions


[view class]
Cursor
typedef IBaseComboBox::Cursor Cursor

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IComboBox - Inherited Member Functions and Data

Inherited Public Functions

IBaseComboBox
IControl
IEntryField
INotifier
ITextControl
IWindow

Inherited Public Data

IWindow
INotifier
IBaseComboBox
IEntryField
ITextControl

Inherited Protected Functions

IWindow
INotifier
IBaseComboBox
IControl
IEntryField
ITextControl

Inherited Protected Data