| //////////////////////////////////////////////////////////////////////////////// |
| // |
| // 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 |
| * <code>createCursor()</code> method) the value of the |
| * <code>current</code> 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 <code>true</code> . |
| * If the ICollectionView is empty (length == 0), |
| * this property is <code>true</code>. |
| * |
| * @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 <code>true</code>. |
| * If the ICollectionView is empty (length == 0), |
| * this property is <code>true</code>. |
| * |
| * @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 <code>current</code> 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 <code>seek()</code> 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 |
| * (<code>beforeFirst</code>, <code>afterLast</code>) |
| * this will return <code>null</code>. |
| * |
| * @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. |
| * |
| * <p>The <code>findAny()</code> method can only be called on sorted views; |
| * if the view isn't sorted, a <code>CursorError</code> is thrown.</p> |
| * |
| * <p>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.</p> |
| * |
| * <p>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 <code>findFirst()</code> or |
| * <code>findLast()</code> method.</p> |
| * |
| * <p>If the data is not local and an asynchronous operation must be |
| * performed, an ItemPendingError is thrown.</p> |
| * |
| * @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 properties <code>x</code>, <code>y</code>, and |
| * <code>z</code> are in the current sort, the values specified should be |
| * <code>{x: <i>x-value</i>, y: <i>y-value</i>, z: <i>z-value</i>}</code>. |
| * |
| * @return When all of the data is local this method returns |
| * <code>true</code> if the item can be found and <code>false</code> |
| * 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. |
| * |
| * <p>The <code>findFirst()</code> method can only be called on sorted views; |
| * if the view isn't sorted, a <code>CursorError</code> is thrown.</p> |
| * |
| * <p>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.</p> |
| * |
| * <p>If it is not important to find the first occurrence of an item |
| * in a non-unique index, use <code>findAny()</code>, which may be |
| * a little faster than the <code>findFirst() method</code>.</p> |
| * |
| * <p>If the data is not local and an asynchronous operation must be |
| * performed, an ItemPendingError is thrown.</p> |
| * |
| * @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 properties <code>x</code>, <code>y</code>, and |
| * <code>z</code> are in the current sort, the values specified should be |
| * <code>{x: <i>x-value</i>, y: <i>y-value</i>, z: <i>z-value</i>}</code>. |
| * |
| * @return When all of the data is local this method returns |
| * <code>true</code> if the item can be found and <code>false</code> |
| * 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. |
| * |
| * <p>The <code>findLast()</code> method can only be called on sorted views; |
| * if the view isn't sorted, a <code>CursorError</code> is thrown.</p> |
| * |
| * <p>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.</p> |
| * |
| * <p>If it is not important to find the last occurrence of an item |
| * in a non-unique index, use the <code>findAny()</code> method, which |
| * may be a little faster.</p> |
| * |
| * <p>If the data is not local and an asynchronous operation must be |
| * performed, an ItemPendingError is thrown.</p> |
| * |
| * @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 properties <code>x</code>, <code>y</code>, and |
| * <code>z</code> are in the current sort, the values specified should be |
| * <code>{x: <i>x-value</i>, y: <i>y-value</i>, z: <i>z-value</i>}</code>. |
| * |
| * @return When all of the data is local this method returns |
| * <code>true</code> if the item can be found and <code>false</code> |
| * 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 <code>afterLast</code>, |
| * the insertion occurs at the end of the view. |
| * If the cursor is <code>beforeFirst</code> 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 <code>current</code> property is updated |
| * to reference the object at this new location. |
| * Returns <code>true</code> if the resulting <code>current</code> |
| * property is valid, or <code>false</code> if not |
| * (the property value is <code>afterLast</code>). |
| * |
| * <p>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.</p> |
| * |
| * @return <code>true</code> if still in the list, |
| * <code>false</code> if the <code>current</code> value initially was |
| * or now is <code>afterLast</code>. |
| * |
| * @see #current |
| * @see #movePrevious() |
| * @see mx.collections.errors.ItemPendingError |
| * |
| * @example |
| * <pre> |
| * var myArrayCollection:ICollectionView = new ArrayCollection([ "Bobby", "Mark", "Trevor", "Jacey", "Tyler" ]); |
| * var cursor:IViewCursor = myArrayCollection.createCursor(); |
| * while (!cursor.afterLast) |
| * { |
| * trace(cursor.current); |
| * cursor.moveNext(); |
| * } |
| * </pre> |
| * |
| * @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 <code>current</code> property is updated |
| * to reference the object at this new location. |
| * Returns <code>true</code> if the resulting <code>current</code> |
| * property is valid, or <code>false</code> if not |
| * (the property value is <code>beforeFirst</code>). |
| * |
| * <p>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.</p> |
| * |
| * @return <code>true</code> if still in the list, |
| * <code>false</code> if the <code>current</code> value initially was or |
| * now is <code>beforeFirst</code>. |
| * |
| * For example: |
| * <pre> |
| * 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(); |
| * } |
| * </pre> |
| * |
| * @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 <code>beforeFirst</code> or |
| * <code>afterLast</code>, 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. |
| * |
| * <p>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.</p> |
| * |
| * @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 |
| * an <code>offset</code> number of items prior to the specified bookmark. |
| * |
| * <p>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.</p> |
| * |
| * <p>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.</p> |
| * |
| * @param bookmark <code>CursorBookmark</code> reference to marker |
| * information that allows repositioning to a specific location. |
| * You can set this parameter to value returned from the |
| * <code>bookmark</code> property, or to one of the following constant |
| * bookmark values: |
| * <ul> |
| * <li><code>CursorBookmark.FIRST</code> - |
| * Seek from the start (first element) of the collection</li> |
| * <li><code>CursorBookmark.CURRENT</code> - |
| * Seek from the current position in the collection</li> |
| * <li><code>CursorBookmark.LAST</code> - |
| * Seek from the end (last element) of the collection</li> |
| * </ul> |
| * |
| * @param offset 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 |
| * <code>beforeFirst</code> or <code>afterLast</code> 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; |
| } |
| |
| } |
