Adobe® Flex® 4 Language Reference
Hide Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
mx.collections 
HierarchicalCollectionViewCursor 
Packagemx.collections
Classpublic class HierarchicalCollectionViewCursor
InheritanceHierarchicalCollectionViewCursor Inheritance EventDispatcher Inheritance Object
Implements IHierarchicalCollectionViewCursor

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

The HierarchicalCollectionViewCursor class defines a cursor for a hierarchical view of a standard collection. The collection that this cursor walks across need not be hierarchical - it may be flat. This class delegates to the IHierarchicalData for information regarding the tree structure of the data it walks across.

See also



Public Properties
 PropertyDefined By
  afterLast : Boolean
[read-only] If the cursor is located after the last item in the view, this property is true .
HierarchicalCollectionViewCursor
  beforeFirst : Boolean
[read-only] If the cursor is located before the first item in the view, this property is true.
HierarchicalCollectionViewCursor
  bookmark : CursorBookmark
[read-only] Provides access to a bookmark that corresponds to the item returned by the current property.
HierarchicalCollectionViewCursor
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  current : Object
[read-only] Provides access the object at the location in the source collection referenced by this cursor.
HierarchicalCollectionViewCursor
  currentDepth : int
[read-only] Contains the depth of the node at the location in the source collection referenced by this cursor.
HierarchicalCollectionViewCursor
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  view : ICollectionView
[read-only] A reference to the ICollectionView with which this cursor is associated.
HierarchicalCollectionViewCursor
Public Methods
 MethodDefined By
  
Constructor.
HierarchicalCollectionViewCursor
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
EventDispatcher
 Inherited
Dispatches an event into the event flow.
EventDispatcher
  
Finds an item with the specified properties within the collection and positions the cursor to that item.
HierarchicalCollectionViewCursor
  
Finds the first item with the specified properties within the collection and positions the cursor to that item.
HierarchicalCollectionViewCursor
  
Finds the last item with the specified properties within the collection and positions the cursor on that item.
HierarchicalCollectionViewCursor
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
  
Inserts the specified item before the cursor's current position.
HierarchicalCollectionViewCursor
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
Moves the cursor to the next item within the collection.
HierarchicalCollectionViewCursor
  
Moves the cursor to the previous item within the collection.
HierarchicalCollectionViewCursor
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
  
Removes the current item and returns it.
HierarchicalCollectionViewCursor
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
  
seek(bookmark:CursorBookmark, offset:int = 0, prefetch:int = 0):void
Moves the cursor to a location at an offset from the specified bookmark.
HierarchicalCollectionViewCursor
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
Property Detail

afterLast

property
afterLast:Boolean  [read-only]

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

If the cursor is located after the last item in the view, this property is true . If the ICollectionView is empty (length == 0), this property is true.



Implementation
    public function get afterLast():Boolean

beforeFirst

property 
beforeFirst:Boolean  [read-only]

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

If the cursor is located before the first item in the view, this property is true. If the ICollectionView is empty (length == 0), this property is true.



Implementation
    public function get beforeFirst():Boolean

bookmark

property 
bookmark:CursorBookmark  [read-only]

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Provides access to a bookmark that corresponds to the item returned by the current property. The bookmark can be used to move the cursor to a previously visited item, or to a position relative to that item. (See the seek() method for more information.)



Implementation
    public function get bookmark():CursorBookmark

current

property 
current:Object  [read-only]

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Provides access the object at the location in the source collection referenced by this cursor. If the cursor is beyond the ends of the collection (beforeFirst, afterLast) this will return null.



Implementation
    public function get current():Object

currentDepth

property 
currentDepth:int  [read-only]

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Contains the depth of the node at the location in the source collection referenced by this cursor. If the cursor is beyond the end of the collection, this property contains 0.



Implementation
    public function get currentDepth():int

view

property 
view:ICollectionView  [read-only]

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

A reference to the ICollectionView with which this cursor is associated.



Implementation
    public function get view():ICollectionView
Constructor Detail

HierarchicalCollectionViewCursor

()Constructor
public function HierarchicalCollectionViewCursor(collection:HierarchicalCollectionView, model:ICollectionView, hierarchicalData:IHierarchicalData)

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Constructor.

Parameters
collection:HierarchicalCollectionView — The HierarchicalCollectionView instance referenced by this cursor.
 
model:ICollectionView — The source data collection.
 
hierarchicalData:IHierarchicalData — The data used to create the HierarchicalCollectionView instance.
Method Detail

findAny

()method
public function findAny(values:Object):Boolean

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Finds an item with the specified properties within the collection and positions the cursor to that item. If the item can not be found, the cursor location does not change.

The findAny() method can only be called on sorted views; if the view isn't sorted, a CursorError is thrown.

If the associated collection is remote, and not all of the items have been cached locally, this method begins an asynchronous fetch from the remote collection. If one is already in progress, this method waits for it to complete before making another fetch request.

If multiple items can match the search criteria then the item found is non-deterministic. If it is important to find the first or last occurrence of an item in a non-unique index, use the findFirst() or findLast() method.

If the data is not local and an asynchronous operation must be performed, an ItemPendingError is thrown.

Parameters

values:Object — The search criteria. The values in the Object must be configured as name-value pairs, as in an associative array (or be the actual object to search for). The values of the names specified must match properties specified in the sort. For example, if properties x, y, and z are in the current sort, the values specified should be {x: x-value, y: y-value, z: z-value}.

Returns
Boolean — When all of the data is local this method returns true if the item can be found and false otherwise.

findFirst

()method 
public function findFirst(values:Object):Boolean

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Finds the first item with the specified properties within the collection and positions the cursor to that item. If the item can not be found, no cursor location does not change.

The findFirst() method can only be called on sorted views; if the view isn't sorted, a CursorError is thrown.

If the associated collection is remote, and not all of the items have been cached locally, this method begins an asynchronous fetch from the remote collection. If one is already in progress, this method waits for it to complete before making another fetch request.

If it is not important to find the first occurrence of an item in a non-unique index, use findAny(), which may be a little faster than the findFirst() method.

If the data is not local and an asynchronous operation must be performed, an ItemPendingError is thrown.

Parameters

values:Object — The search criteria. The values in the Object must be configured as name-value pairs, as in an associative array (or be the actual object to search for). The values of the names specified must match properties specified in the sort. For example, if properties x, y, and z are in the current sort, the values specified should be {x: x-value, y: y-value, z: z-value}.

Returns
Boolean — When all of the data is local this method returns true if the item can be found and false otherwise.

findLast

()method 
public function findLast(values:Object):Boolean

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Finds the last item with the specified properties within the collection and positions the cursor on that item. If the item can not be found, the cursor location does not chanage.

The findLast() method can only be called on sorted views; if the view isn't sorted, a CursorError is thrown.

If the associated collection is remote, and not all of the items have been cached locally, this method begins an asynchronous fetch from the remote collection. If one is already in progress, this method waits for it to complete before making another fetch request.

If it is not important to find the last occurrence of an item in a non-unique index, use the findAny() method, which may be a little faster.

If the data is not local and an asynchronous operation must be performed, an ItemPendingError is thrown.

Parameters

values:Object — The search criteria. The values in the Object must be configured as name-value pairs, as in an associative array (or be the actual object to search for). The values of the names specified must match properties specified in the sort. For example, if properties x, y, and z are in the current sort, the values specified should be {x: x-value, y: y-value, z: z-value}.

Returns
Boolean — When all of the data is local this method returns true if the item can be found and false otherwise.

insert

()method 
public function insert(item:Object):void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Inserts the specified item before the cursor's current position. If the cursor is afterLast, the insertion occurs at the end of the view. If the cursor is beforeFirst on a non-empty view, an error is thrown.

Parameters

item:Object — The item to insert before the cursor's current position.

moveNext

()method 
public function moveNext():Boolean

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Moves the cursor to the next item within the collection. On success the current property is updated to reference the object at this new location. Returns true if the resulting current property is valid, or false if not (the property value is afterLast).

If the data is not local and an asynchronous operation must be performed, an ItemPendingError is thrown. See the ItemPendingError documentation and the collections documentation for more information on using the ItemPendingError.

Returns
Booleantrue if still in the list, false if the current value initially was or now is afterLast.

movePrevious

()method 
public function movePrevious():Boolean

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Moves the cursor to the previous item within the collection. On success the current property is updated to reference the object at this new location. Returns true if the resulting current property is valid, or false if not (the property value is beforeFirst).

If the data is not local and an asynchronous operation must be performed, an ItemPendingError is thrown. See the ItemPendingError documentation and the collections documentation for more information on using the ItemPendingError.

Returns
Booleantrue if still in the list, false if the current value initially was or now is beforeFirst. For example:
      var myArrayCollection:ICollectionView = new ArrayCollection([ "Bobby", "Mark", "Trevor", "Jacey", "Tyler" ]);
      var cursor:IViewCursor = myArrayCollection.createCursor();
      cursor.seek(CursorBookmark.last);
      while (!cursor.beforeFirst)
      {
          trace(current);
          cursor.movePrevious();
      }
      

remove

()method 
public function remove():Object

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Removes the current item and returns it. If the cursor location is beforeFirst or afterLast, throws a CursorError. If you remove any item other than the last item, the cursor moves to the next item. If you remove the last item, the cursor is at the AFTER_LAST bookmark.

If the item after the removed item is not local and an asynchronous operation must be performed, an ItemPendingError is thrown. See the ItemPendingError documentation and the collections documentation for more information on using the ItemPendingError.

Returns
Object — The item that was removed.

seek

()method 
public function seek(bookmark:CursorBookmark, offset:int = 0, prefetch:int = 0):void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Moves the cursor to a location at an offset from the specified bookmark. The offset can be negative, in which case the cursor is positioned an offset number of items prior to the specified bookmark.

If the associated collection is remote, and not all of the items have been cached locally, this method begins an asynchronous fetch from the remote collection.

If the data is not local and an asynchronous operation must be performed, an ItemPendingError is thrown. See the ItemPendingError documentation and the collections documentation for more information on using the ItemPendingError.

Parameters

bookmark:CursorBookmarkCursorBookmark reference to marker information that allows repositioning to a specific location. You can set this parameter to value returned from the bookmark property, or to one of the following constant bookmark values:
  • CursorBookmark.FIRST - Seek from the start (first element) of the collection
  • CursorBookmark.CURRENT - Seek from the current position in the collection
  • CursorBookmark.LAST - Seek from the end (last element) of the collection
 
offset:int (default = 0) — Indicates how far from the specified bookmark to seek. If the specified number is negative, the cursor attempts to move prior to the specified bookmark. If the offset specified is beyond the end of the collection, the cursor is be positioned off the end, to the beforeFirst or afterLast location.
 
prefetch:int (default = 0) — Used for remote data. Indicates an intent to iterate in a specific direction once the seek operation completes. This reduces the number of required network round trips during a seek. If the iteration direction is known at the time of the request, the appropriate amount of data can be returned ahead of the request to iterate it.