////////////////////////////////////////////////////////////////////////////////
//
// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
////////////////////////////////////////////////////////////////////////////////
package mx.collections
{
import flash.events.IEventDispatcher;
/**
* Dispatched whenever the cursor position is updated.
*
* @eventType mx.events.FlexEvent.CURSOR_UPDATE
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
[Event(name="cursorUpdate", type="mx.events.FlexEvent")]
/**
* Defines the interface for enumerating a collection view bi-directionally.
* This cursor provides find, seek, and bookmarking capabilities along
* with the modification methods insert and remove.
* When a cursor is first retrieved from a view, (typically by the ICollectionView
* createCursor()
method) the value of the
* current
property should be the first
* item in the view, unless the view is empty.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public interface IViewCursor extends IEventDispatcher
{
//--------------------------------------------------------------------------
//
// Properties
//
//--------------------------------------------------------------------------
//----------------------------------
// afterLast
//----------------------------------
[Bindable("cursorUpdate")]
/**
* 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
.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function get afterLast():Boolean;
//----------------------------------
// beforeFirst
//----------------------------------
[Bindable("cursorUpdate")]
/**
* 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
.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function get beforeFirst():Boolean;
//----------------------------------
// bookmark
//----------------------------------
[Bindable("cursorUpdate")]
/**
* 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.)
*
* @see #current
* @see #seek()
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function get bookmark():CursorBookmark;
//----------------------------------
// current
//----------------------------------
[Bindable("cursorUpdate")]
/**
* 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
.
*
* @see #moveNext()
* @see #movePrevious()
* @see #seek()
* @see #beforeFirst
* @see #afterLast
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function get current():Object;
//----------------------------------
// view
//----------------------------------
/**
* A reference to the ICollectionView with which this cursor is associated.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function get view():ICollectionView;
//--------------------------------------------------------------------------
//
// Methods
//
//--------------------------------------------------------------------------
/**
* 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.
* * @param values 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 propertiesx
, y
, and
* z
are in the current sort, the values specified should be
* {x: x-value, y: y-value, z: z-value}
.
*
* @return When all of the data is local this method returns
* true
if the item can be found and false
* otherwise.
*
* @see #findFirst()
* @see #findLast()
* @see mx.collections.errors.ItemPendingError
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function findAny(values:Object):Boolean;
/**
* 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.
* * @param values 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 propertiesx
, y
, and
* z
are in the current sort, the values specified should be
* {x: x-value, y: y-value, z: z-value}
.
*
* @return When all of the data is local this method returns
* true
if the item can be found and false
* otherwise.
*
* @see #findAny()
* @see #findLast()
* @see mx.collections.errors.ItemPendingError
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function findFirst(values:Object):Boolean;
/**
* 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.
* * @param values 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 propertiesx
, y
, and
* z
are in the current sort, the values specified should be
* {x: x-value, y: y-value, z: z-value}
.
*
* @return When all of the data is local this method returns
* true
if the item can be found and false
* otherwise.
*
* @see #findAny()
* @see #findFirst()
* @see mx.collections.errors.ItemPendingError
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function findLast(values:Object):Boolean;
/**
* 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.
*
* @param item The item to insert before the cursor's current position.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function insert(item:Object):void;
/**
* 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.
* * @returntrue
if still in the list,
* false
if the current
value initially was
* or now is afterLast
.
*
* @see #current
* @see #movePrevious()
* @see mx.collections.errors.ItemPendingError
*
* @example
* * var myArrayCollection:ICollectionView = new ArrayCollection([ "Bobby", "Mark", "Trevor", "Jacey", "Tyler" ]); * var cursor:IViewCursor = myArrayCollection.createCursor(); * while (!cursor.afterLast) * { * trace(cursor.current); * cursor.moveNext(); * } ** * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ function moveNext():Boolean; /** * 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.
* * @returntrue
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(); * } ** * @see #current * @see #moveNext() * @see mx.collections.errors.ItemPendingError * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ function movePrevious():Boolean; /** * 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.
* * @return The item that was removed. * * @see mx.collections.errors.ItemPendingError * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ function remove():Object; /** * 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 * anoffset
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.
* * @param bookmarkCursorBookmark
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 collectionCursorBookmark.CURRENT
-
* Seek from the current position in the collectionCursorBookmark.LAST
-
* Seek from the end (last element) of the collectionbeforeFirst
or afterLast
location.
*
* @param prefetch 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.
*
* @see mx.collections.errors.ItemPendingError
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function seek(bookmark:CursorBookmark, offset:int = 0, prefetch:int = 0):void;
}
}