Flex 2 Developer's Guide > Building User Interfaces for Flex Applications > Using Data Providers and Collections > Using ICollectionView interface methods and properties > Using the IViewCursor interface

Using the IViewCursor interface

The ICollectionView interface includes a createCursor() method that returns an IViewCursor object, also called a cursor, that you can use to traverse the items in the view and to access and modify data in the collection. A cursor is a position indicator; it points to a particular item in the collection. You can use IViewCursor methods and properties to perform the following operations:

• Move the cursor backward or forward.
• Move the cursor to specific items.
• Get the item at a cursor location.
• Add, remove, and change items.
• Save a cursor position by using a bookmark, and return to it later.

When you use standard Flex collection classes, ArrayCollection and XMLListCollection, you use the IViewCursor interface directly, you do not reference an object instance, as shown in the following code snippet:

public var myAC:ICollectionView = new ArrayCollection(myArray); 
public var myCursor:IViewCursor;
.
.
myCursor=myAC.createCursor();

Subtopics

Manipulating the view cursor

The IViewCursor interface includes the following methods and properties for moving the cursor:

• The moveNext() and movePrevious() methods move the cursor forward and backward by one item. Use the beforeFirst and afterLast properties to check whether you've reached the bounds of the view. The following example moves the cursor to the last item in the view:

  while (! myCursor.afterLast) {
          myCursor.moveNext();
  }
  

• The findAny(), findFirst(), and findLast(), methods move the cursor to an item that matches the parameter. Before you can use these methods, you must apply a Sort to the ICollectionView implementation (because the functions use Sort methods).

  If it is not important to find the first occurrence of an item or last occurrence of an item in a non-unique index, the findAny() method can be somewhat more efficient than either the findFirst() or the findLast() method.

  If the associated collection is remote, and not all of the items are cached locally, the find methods begin an asynchronous fetch from the remote collection; if a fetch is already in progress, they wait for it to complete before making another fetch request.

  The following example finds an item inside a collection of simple objects, in this case, an ArrayCollection of state ZIP Code strings. It creates a default Sort object, applies it to an ArrayCollection object, and finds the first instance of the string "MZ" in a simple array of strings:

  var sortD:Sort = new Sort();
  // The null first parameter on the SortField constructor specifies a
  // collection of simple objects (String, numeric, or Boolean values).
  // The true second parameter specifies a case-insensitive sort.
  sortD.fields = [new SortField(null, true)];
  myAC.sort=sortD;
  myAC.refresh();
  myCursor.findFirst("MZ");
  

  To find a complex object, the findFirst() method can search on multiple sort fields. You cannot, however, skip fields in the parameter of any of the find methods. If an object has three fields, for example, you can specify any of the following field combinations in the parameter: 1, 1,2, 1,2,3, but you cannot specify only fields 1 and 3.

  Both of the following lines will find an object with the label value "ME" and data value "Augusta":

  myCursor.findFirst({label:"ME"});

  myCursor.findFirst({label:"ME", data:"Augusta"});
  

• The seek() method moves the cursor to a position relative to a bookmark. You use this method to move the cursor to the first or last item in a view, or to move to a bookmark position that you have saved. For more information on using bookmarks and the seek() method, see Using bookmarks

Getting, adding and removing items

The IViewCursor interface includes the following methods and properties for accessing and changing data in the view:

• The current property is a reference to the item at the current cursor location.
• The insert() method inserts an item before the current cursor location. Note, however, that if the collection is sorted, (for example, to do a find()) the sort moves the item to the sorted order location, not the cursor location.
• The remove() method removes the item at the current cursor location; if the removed item is not the last item, the cursor then points to the location after the removed item.

The following example shows the results of using the insert() and remove() on the current property:

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
        initialize="initData();">
    <mx:Script>
        <![CDATA[
            import mx.collections.*;
            public var myArray:Array = [{label:"MA", data:"Massachusetts"}, 
            {label:"MN", data:"Minnesota"}, {label:"MO", data:"Missouri"}];
            [Bindable]
            public var myAC:ArrayCollection; 
            public var myCursor:IViewCursor;

            // Initialize the ArrayCollection when you initialize the
            // application.
            public function initData():void {
                myAC = new ArrayCollection(myArray); 
            }

            // The function to change the collection, and therefore the Array.
            public function testCollection():void {
                // Get an IViewCursor object for accessing the collection data.
                myCursor=myAC.createCursor();
                ta1.text="At start. cursor is at: " + myCursor.current.label;
                var removedItem:String=String(myCursor.remove());
                ta1.text+="\nAfter removing the current item, the cursor is at: " 
                    + myCursor.current.label;
                myCursor.insert({label:"ME", data:"Augusta"});
                ta1.text+="\nAfter adding an item, the cursor is at: " 
                    + myCursor.current.label;
            }
        ]]>
    </mx:Script>

    <mx:ComboBox id="myCB" rowCount="7" dataProvider="{myAC}"/>
    <mx:TextArea id="ta1" height="75" width="350"/> 
    <mx:Button label="run test" click="testCollection();"/>

</mx:Application>

Using bookmarks

You use a bookmark to save a cursor location for later use. You can also use the built-in FIRST and LAST bookmark properties to move the cursor to the first or last item in the view.

To create and use a bookmark:

1. Move the cursor to a desired location in the view.
2. Assign the current value of the bookmark property to a variable, as in the following line:

   var myBookmark:CursorBookmark=myIViewCursor.bookmark;
   

3. Do some operations that might move the cursor.
4. When you must return to the bookmarked cursor location (or to a specific offset from the bookmarked location), call the IViewCursor seek() method, as in the following line:

   myIViewCursor.seek(myBookmark);
   

The following example counts the number of items in a collection between the selected item in a ComboBox and the end of the collection, and then returns the cursor to the initial location:

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
        initialize="run();">
    <mx:Script>
        <![CDATA[
            import mx.collections.*;
            private var myCursor:IViewCursor;

            // Initialize variables.
            public function run():void {
                // Initialize the cursor.
                myCursor=myAC.createCursor();
                // The findFirst() method, used in countFromSelection() requires a
                // sorted view.
                var sort:Sort = new Sort();
                sort.fields=[new SortField("label")];
                myAC.sort=sort;
                //You must refresh the view to apply the sort.
                myAC.refresh();
            }

            // Count the items following the current cursor location.
            public function countLast(theCursor:IViewCursor):int {
                var counter:int=0;
                // Set a bookmark at the current cursor location.
                var mark:CursorBookmark=theCursor.bookmark;
                // Move the cursor to the end of the Array.
                // The moveNext method returns false when the cursor is after the
                // last item.
                    while (theCursor.moveNext()) {
                    counter++;
                }
                // Return the cursor to the initial location.
                theCursor.seek(mark);
                return counter;
            }

            // Function triggered by ComboBox change event.
            // Calls the countLast() function to count the number of items to the 
            // end of the collection.
            public function countFromSelection():void {
                myCursor.findFirst(myCB.selectedItem);
                var count:int = countLast(myCursor);
                ta1.text += myCursor.current.label + " is " + count +
                                " from the last item.\n";
            }
        ]]>
    </mx:Script>

    <!-- The data provider, an ArrayCollection with an array of objects. --> 
    <mx:ArrayCollection id="myAC">
        <mx:Object label="MA" data="Boston"/>
        <mx:Object label="ME" data="Augusta"/>
        <mx:Object label="MI" data="Lansing"/>
        <mx:Object label="MN" data="Saint Paul"/>
        <mx:Object label="MO" data="Jefferson City"/>
        <mx:Object label="MS" data="Jackson"/>
        <mx:Object label="MT" data="Helena"/>
    </mx:ArrayCollection>

    <mx:ComboBox id="myCB" rowCount="7" dataProvider="{myAC}" change="countFromSelection();"/>
    <mx:TextArea id="ta1" height="200" width="175"/>
</mx:Application>

Flex 2

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flex/2/docs/00000505.html

Add Comment