Working with ICollectionViewListBox Parts

The following tasks are associated with using an ICollectionViewListBox* part in visual composition. Tasks that are common to many parts are described in related topics.

Setting the collection type
To specify the type of collection containing the objects, select Change Template Arguments from the part pop-up menu. Then, in the Change Template Arguments window, set the class Collection property. Enter the type you want in the value column. The default collection type is IVSequence.

Setting the collection object type
To specify the type of objects in the collection, select Change Template Arguments from the part pop-up menu. Then, in the Change Template Arguments window, set the class Element property. Enter a pointer to the part type (part type and *) in the value column.

Defining strings for collection objects
To produce strings that represent collection objects in the list box, specify a string generator that provides the strings. To specify the string generator, open the ICollectionViewListBox* property sheet. Then, enter code in the code prompter for the value column of the stringGenerator property.

Setting initial contents
To define initial selection choices for the list box, connect a collection containing the choices to the list box. The list box provides a view of the collection. The contents of the collection determine the contents of the list box.

Specifically, connect the this attribute of the collection part to the items attribute of the ICollectionViewListBox* part. You must use a collection part that has one template argument, such as an IVSequence* part.

Defining selection
To specify the selection mode for the list box, open the style property in the ICollectionViewListBox* property sheet. Then, specify one of the following selection modes:

Single selection
Allows the user to select only one choice. Ensure that neither the extendedSelect style nor the multipleSelect style is on.

Multiple selection
Allows the user to individually select multiple choices. Set the multipleSelect style to on.

Extended selection
Allows the user to select multiple choices by dragging the mouse over them or by pressing either the Shift key or the Ctrl key during selection. Set the extendedSelect style to on.

The class default style is shipped with single selection as the default mode. Neither of the selection styles is set onin the default style, so the <default> choice for these styles has the same effect as selecting off.

Getting the selected choice
To copy the selected object to a target that expects an object of the type listed in the list box, connect the ICollectionViewListBox* selectedElement attribute to the target's this attribute. For example, if you are listing ICustomer* objects, connect the ICollectionViewListBox* selectedElement attribute to an ICustomer* attribute or parameter.

To copy the text string for the selected object to an entry field, do the following:

For example, if you are listing ICustomer* objects by customer name, connect the ICollectionViewListBox* selectedElement attribute to a Variable part that holds an ICustomer* part. Then, connect the Variable name attribute to the IEntryField* text attribute.

Adding a choice
To add a new object to the list box, add the object to the collection part that contains the objects. Use an add action for the collection type.

For example, if you are using an IVSequence* collection, you can use the IVSequence* add, addAsFirst, addAsLast or addAtPosition action to add the object to the collection. If you want to add the object at the position of the currently selected object, connect the ICollectionViewListBox* selection attribute to the connection or action requiring the position parameter.

Removing a choice
To remove an object from the list box, remove the object from the collection part that contains the objects. Use a remove action for the collection type.

For example, if you are using an IVSequence* collection, you can use the IVSequence* removeFirst, removeLast or removeAtPosition action to remove the object from the collection. If you want to remove the currently selected object, connect the ICollectionViewListBox* selection attribute to the connection or action requiring the position parameter.


Related procedures
Setting Template Arguments
Common Tasks for Control Parts
Setting Part Style Properties
Setting Part Color Properties
Setting Part Font Properties
Setting Part Handlers Properties
Setting Part Framing Properties
Working with VisualAge User Interface Parts

Related references
ICollectionViewListBox
Property Settings -- ICollectionViewListBox
Portability -- ICollectionViewListBox