IBaseListBox::Cursor

The nested class IBaseListBox::Cursor defines objects that you can use to traverse through the items in a list box. In the same way that you can use a cursor to traverse through the objects in a collection, you can use a cursor to traverse through a list box, one item at a time.

Once you create a cursor, you can set the cursor to the first, last, or a specific item in a list box. You can add, update, get, and delete list box items based on the cursor's location in the list box.
Note: Before you use the cursor, you must use isValid to verify that the cursor is valid. An exception is thrown if you use a cursor that is not valid to manipulate the list box.


IBaseListBox::Cursor - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
Cursor
public:
Cursor( const IBaseListBox& listbox, Filter type = selectedItems )

You can create objects of this class by providing the following:

listbox
Reference to a list box control.
type
A filter type. Use the enumeration Filter to specify this parameter. The default is selectedItems.

Note: When using a selectedItems cursor to navigate through one or more selected items in the list box, note that the cursor is valid for the selection states that exist in the list box at the time the cursor is created. The recommended usage of this cursor is, at some given time, you create the cursor, collect the selection information needed, and then destroy the cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Cursor Movement

Use these members to control cursor movement in the list box.


[view class]
setToFirst
public:
virtual bool setToFirst()

Points to the first list box item and validates the cursor. If the cursor is set successfully, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Points to the specified item and validates the cursor. If the cursor is set to the specified list box item, true is returned. Otherwise, false is returned.

index
A 0-based index indicating the item upon which you want the cursor placed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToLast
public:
virtual bool setToLast()

Points to the last list box item and validates the cursor. If the cursor is set successfully, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToNext
public:
virtual bool setToNext()

Points to the next item in the list box. If the cursor is set to the next list box item, true is returned. If no more items exist, this function invalidates the cursor and false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToPrevious
public:
virtual bool setToPrevious()

Points to the previous item in the list box. If the cursor is set to the previous list box item, true is returned. If no previous item exists, this function invalidates the cursor and false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Cursor Validation and Conversion

Use these members to query or return information about the item to which the cursor is pointing.


[view class]
asIndex
public:
virtual unsigned long asIndex() const

Returns the index of the item the cursor is pointing to.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
invalidate
public:
virtual void invalidate()

Flags this cursor as not valid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isValid
public:
virtual bool isValid() const

Returns a boolean that indicates whether this cursor points to a valid item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IBaseListBox::Cursor - Enumerations


[view class]
Filter
enum Filter { selectedItems, 
              allItems }

Use these enumerators to specify which items you want filtered:

selectedItems
Filters only items that are selected.
allItems
Filters all items.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IBaseListBox::Cursor - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data