### Using Cursor Classes

Window classes that can contain one or more items generally provide a nested cursor class. The cursor classes provide member functions to move through the items, either forward or backward.

Note: | The Open Class Library cursor classes are designed to have the same look and feel as the collection class cursors.

A cursor must be in a valid state to access the items in a list. A cursor is generally created in an invalid state. Any cursor function that causes the cursor to point to an item in the list validates the cursor. For example, the function setToFirst causes the cursor to be valid if there are items in the list. If the contents of the list that the cursor is iterating through change by the addition or removal of items, the cursor becomes invalid. It cannot be used to access items in the list until it is validated again by a function that points the cursor at a valid item.

Note: | IWindow::ChildCursor is an exception to this.

Some cursors support iteration over items in a collection that match a particular property. For example, the constructor for a list box cursor can have a second parameter that determines whether the cursor returns all items in the list box or just the selected items.

The following example, from the Hello World version 5 ahellow5.cpp file, shows how to set text from the first selected item in a multiple-selection list box:

    AHelloWindow &
      AHelloWindow :: setTextFromListBox()
    {
      /*---------------------- Set Hello Text from ListBox ---------------------|
      |  Create a cursor to the list box.  Using the default filter for a       |
      |    list box cursor, selectedItems, causes the setToFirst() function     |
      |    to position the cursor to the first selected item.                   |
      |  Set the hello IStaticText control text value.                          |
      |------------------------------------------------------------------------*/
      IListBox::Cursor lbCursor(listBox);
      lbCursor.setToFirst();
      hello.setText(listBox.elementAt(lbCursor));

      return (*this);                       //Return a reference to the frame
    }

Windows

Adding Styles

IListBox::Cursor
IWindow::ChildCursor