ICollectionViewComboBox

The ICollectionViewComboBox template class provides a view of an ordered collection, as items in the list box portion of a combination box. Template class Element is the type of objects in the collection, and template class Collection is the type of collection. The sequence of elements is the same between the ordered collection and list box portion of the combination box. The ICollectionViewComboBox interface consists of the following:

The setItems member populates the list box portion of the combination box from collection elements. The items member returns the collection being viewed.

The collection-reporting protocol refers to the virtual member functions, such as elementsChanged, that handle reported changes in the observed collection. The ICollectionViewComboBox object observes the currently viewed collection (initialized on setItems) and reports collection updates via calls to the collection-reporting members. Then, the collection-reporting members update the list box portion of the combination box.

The string generator object translates collection elements to their IString representations. The default string generator assumes the collection elements natively support operator-> or are Object* objects, where Object has an asString member function. The collection-reporting members use this string-generation mechanism in their processing.

The selection members query and manipulate the selection state of the list box portion of the combination box based on collection elements. This includes the following:

An ICollectionViewComboBox object sends notifications, so observers of the object can monitor the following events and process as needed:

The ICollectionViewComboBox class design supports use primarily by the Visual Builder. It establishes a direct link between a collection and its visual representation in a list control. If using this class outside the Visual Builder pay particular attention to the following design requirements:


ICollectionViewComboBox - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ICollectionViewComboBox


Overload 1
public:
ICollectionViewComboBox( unsigned long identifier, IWindow* parent, const IStringGenerator < Element >& stringGenerator = IStringGenerator < Element > ( ) )

You can construct objects of this class by using the parent window and optional string generator parameters.

id
A combination box control ID.
parent
The parent window.
stringGenerator
The initial string generator for the collection view. Optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
ICollectionViewComboBox( const IWindowHandle& handle, const IStringGenerator < Element >& stringGenerator = IStringGenerator < Element > ( ) )

You can construct objects of this class by using the handle of an existing combination box and optional string generator parameters.

handle
The window handle of an existing combination box control.
stringGenerator
The initial string generator for the collection view. Optional

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 3
public:
ICollectionViewComboBox( unsigned long identifier, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const IBaseComboBox::Style& style = IBaseComboBox::defaultStyle ( ), const IStringGenerator < Element >& stringGenerator = IStringGenerator < Element > ( ) )

You can construct objects of this class by using the parent window, owner window, optional size and location, optional style, and optional string generator parameters.

id
A combination box control ID.
parent
The parent window.
owner
The owner window.
initial
A rectangle for the control. It specifies the initial position and size of the object you are constructing. Optional.
style
The initial style for the control. The default is IBaseComboBox::classDefaultStyle. Optional.
stringGenerator
The initial string generator for the collection view. Optional.

This creates the specified combination box control and an object for it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Collection

Use these members to set and retrieve the collection currently being viewed by the ICollectionViewComboBox object.


[view class]
items
public:
virtual Collection* items() const

Returns the collection currently being viewed. Use it to access the underlying collection.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setItems
public:
virtual ICollectionViewComboBox < Element , Collection >& setItems( Collection* collection )

Changes the underlying viewed collection for the combination box. Effectively, this repopulates the list box portion of the combination box with items corresponding to the elements in the new collection. This is the only direct way to populate the list box portion of an ICollectionViewComboBox object. All other changes to items in the list box portion of the combination box result from changes to the underlying collection elements reported via the collection-reporting protocol.

collection
A pointer to a collection. ICollectionViewComboBox supports collections that are descendents of IPartOrderedCollection.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Collection-Reporting Protocol

Use these members to handle reported changes in the underlying ordered collection. As a set, they are a protocol through which changes in the collection are reported and subsequently processed via updates to the control, in this case, the list box portion of the combination box. ICollectionViewListBox uses this same protocol.
Note: The ordered collection is enabled for notification.


[view class]
collectionReplaced
public:
virtual ICollectionViewComboBox < Element , Collection >& collectionReplaced()

Indicates that a new collection is being observed. Effectively, a call to this member notifies an ICollectionViewComboBox object that all items in the list box portion of the combination box were replaced. The member's default behavior sends the ICollectionViewComboBox::itemsId notification to all observers of this ICollectionViewComboBox object.
Note: The reporting protocol calls this member after updating all items in the list box portion of the combination box. The elementsChanged member handles the actual updates to the list box items.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
elementAdded
public:
virtual ICollectionViewComboBox < Element , Collection >& elementAdded( unsigned long position, const Element& element )

Indicates that an element was added to the collection at the specified position. Effectively, this member notifies ICollectionViewComboBox that an item must be added to the list box portion of the combination box. The default behavior generates a string for the collection element, using the IStringGenerator object, and inserts the generated string into the list box.

position
A 1-based index reference to the added collection element.
element
The new collection element.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
elementChanged
public:
virtual ICollectionViewComboBox < Element , Collection >& elementChanged( unsigned long position, const Element& element )

Indicates that a collection element changed state. The collection element's collection position is the first parameter. Effectively, this member notifies an ICollectionViewComboBox object that the list box item corresponding to the collection element needs updating. The default behavior regenerates the string representation for this collection element and replaces the corresponding item in the list box portion of the combination box.

position
A 1-based index reference to the changed collection element.
element
The collection element that changed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
elementDeleted
public:
virtual ICollectionViewComboBox < Element , Collection >& elementDeleted( unsigned long position )

Indicates that a collection element was deleted at the specified position. Effectively, this member notifies an ICollectionViewComboBox object that the corresponding item must be deleted from the list box portion of the combination box. The default behavior deletes the list box item.

position
A 1-based index that specifies the collection position of the deleted collection element prior to the delete.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
elementsChanged
public:
virtual ICollectionViewComboBox < Element , Collection >& elementsChanged()

Indicates that at least one element and possibly all elements in the viewed collection have changed. Effectively, this member notifies an ICollectionViewComboBox object that all items in the list box portion of the combination box need updating based on the current state of the viewed collection. The default behavior deletes all items from the list box portion of the combination box and repopulates that list box from the collection's contents.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Selection

Use these members to retrieve and manipulate the selection state of an ICollectionViewComboBox object. These members act on the list box portion of the combination box but use the collection as their reference for parameters and return values. The parameters and return values are collection positions or collection elements. The selection actions include the following:


Note: A collection operates as if it is a 1-based array of items. The collection position is such an index.


[view class]
deselect
public:
virtual ICollectionViewComboBox < Element , Collection >& deselect( unsigned long collectionPosition )

Deselects the item in the list box portion of the combination box corresponding to the collection element at collectionPosition.

collectionPosition
A 1-based index reference to a collection element.

Note: In collections, the collection position is a 1-based index (the first item is item 1).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
select
public:
virtual ICollectionViewComboBox < Element , Collection >& select( unsigned long collectionPosition, bool select = true )

Selects or deselects the item in the list box portion of the combination box corresponding to the collection element at collectionPosition.

collectionPosition
A 1-based index reference to a collection element.
select
If you specify true, the item is selected and any previously selected item is deselected. If you specify false, the item is deselected. The default is true.

Note: In collections, the collection position is a 1-based index (the first item is item 1).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
selectedCollectionPosition
public:
virtual unsigned long selectedCollectionPosition()

Returns the collection position (1-based index) corresponding to the selected item in the list box portion of the combination box.
Note: If no item is selected, noSelection is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
selectedElement
public:
virtual Element selectedElement() const

Returns the collection element corresponding to the selected item in the list box portion of the combination box.
Note: If no item is selected, an exception is thrown.

Exception

IInvalidRequest There is no selected list box item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Indicates no item is selected in the list box portion of the combination box. ICollectionViewComboBox::selectedCollectionPosition returns this value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


String Generator

Use these members to set and retrieve the string generator associated with an ICollectionViewComboBox object. The default string generator uses Element asString to return a string. This member assumes that Element natively supports operator-> or is an Object* object, where Object has an asString member function.


[view class]
setStringGenerator
public:
virtual IStringGenerator < Element >& setStringGenerator( const IStringGenerator < Element >& stringGenerator )

Replaces the string generator associated with an ICollectionViewComboBox object. The string generator provides strings for collection elements for use as items in the list box portion of the combination box. Typically, a string generator contains a IStringGeneratorMemberFn, which is an Element member function. The string generator generates strings by calling the contained member function. Thus, use this member to replace the Element member function used to produce strings for the collection view items.

stringGenerator
A string generator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stringGenerator
public:
virtual IStringGenerator < Element >& stringGenerator()

Retrieves the string generator associated with an ICollectionViewComboBox object. The string generator provides strings for collection elements for use in the list box part of the combination box. Use this function to assign one IStringGenerator to another; this increments the use count of the optionally contained IStringGeneratorFn.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ICollectionViewComboBox - 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