ICollectionViewListBox

The ICollectionViewListBox template class provides a view of an ordered collection, as items in a list 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. The ICollectionViewListBox interface consists of the following:

The setItems member populates the list 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. ICollectionViewListBox objects observe the currently viewed collection (initialized on setItems) and report collection updates via calls to the collection-reporting members. Then, the collection-reporting members update the list box.

The string generator object translates collection elements to their IString representations. The default string generator assumes that 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 based on collection elements. This includes the following:

An ICollectionViewListBox object sends notifications so that observers can monitor, and process the following events:

The ICollectionViewListBox 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:


ICollectionViewListBox - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ICollectionViewListBox


Overload 1
public:
ICollectionViewListBox( 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 list 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 Yes


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

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

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
ICollectionViewListBox( unsigned long identifier, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const IBaseListBox::Style& style = IBaseListBox::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 list 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 IBaseListBox::classDefaultStyle. Optional.
stringGenerator
The initial string generator for the collection view. Optional.

This creates the specified list 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 ICollectionViewListBox object.


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

Returns the collection currently being viewed. Typically, items is used by the collection-reporting members to retrieve the collection that this control is responsible for viewing.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

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

collection
A pointer to a collection. ICollectionViewListBox 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. ICollectionViewComboBox uses this same protocol.
Note: The ordered collection is enabled for notification.


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

Indicates that a new collection is being observed. Effectively, a call to this member notifies an ICollectionViewListBox object that all items in the list box were replaced. The member's default behavior sends the ICollectionViewListBox::itemsId notification to all observers of this ICollectionViewListBox object.
Note: The collection-reporting protocol calls this member after updating all items in the list 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 ICollectionViewListBox < 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 ICollectionViewListBox that an item must be added to the list 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 ICollectionViewListBox < Element , Collection >& elementChanged( unsigned long position, const Element& element )

Indicates that a collection element at the specified position changed its state. Effectively, this member notifies an ICollectionViewListBox 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.

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 ICollectionViewListBox < Element , Collection >& elementDeleted( unsigned long position )

Indicates that a collection element was deleted at the specified position. Effectively, this member notifies an ICollectionViewListBox object that the corresponding item must be deleted from the list 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 ICollectionViewListBox < Element , Collection >& elementsChanged()

Indicates that at least one element and possibly all elements in the viewed collection have changed. Effectively, this member notifies an ICollectionViewListBox object that all items in the list box need updating based on the current state of the viewed collection. The default behavior deletes all items from the list 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 ICollectionViewListBox object. These members act on the list 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 ICollectionViewListBox < Element , Collection >& deselect( unsigned long collectionPosition )

Deselects the item in the list 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]
enableExtendedSelect
public:
virtual ICollectionViewListBox < Element , Collection >& enableExtendedSelect( bool extended = true )

Enables or disables the style IBaseListBox::extendedSelect for the list box and sends the IBaseCollectionListBox::extendedSelectChangedId notification.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


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

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

collectionPosition
A 1-based index reference to a collection element.
select
If you specify true, based on the list box's 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.

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. 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, 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. For single-selection list boxes, the element corresponding to the selected item is returned. For multiple-selection or extended-selection list boxes, the element corresponding to the first selected item is returned.
Note: If no item is selected, an exception is thrown.

Exception

IInvalidRequest There are no list box items selected.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
selectedElements
public:
virtual ICollectionViewListBox < Element , Collection >& selectedElements( Collection& elements )

Returns a collection of elements corresponding to the selected list box items. It deletes all items from the collection parameter before filling it with the elements corresponding to the selected list box items. Thus, if no items are selected, an empty collection is returned.

elements
A collection for returning elements corresponding to the selected list box items.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Indicates no list box item is selected. ICollectionViewListBox::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 the ICollectionViewListBox 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 ICollectionViewListBox 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 ICollectionViewListBox object. The string generator provides strings for collection elements for use as list box items.
Note: IStringGenerator supports copying or assigning IStringGenerator objects; it handles the proper reference-counting of the optionally contained IStringGeneratorFn.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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