You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@royale.apache.org by GitBox <gi...@apache.org> on 2018/04/10 20:35:22 UTC
[GitHub] aharui closed pull request #156: IViewCursor and ICollectionView
aharui closed pull request #156: IViewCursor and ICollectionView
URL: https://github.com/apache/royale-asjs/pull/156
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/frameworks/projects/MXRoyale/src/main/royale/MXRoyaleClasses.as b/frameworks/projects/MXRoyale/src/main/royale/MXRoyaleClasses.as
index d246fdeb9..cfda2948f 100644
--- a/frameworks/projects/MXRoyale/src/main/royale/MXRoyaleClasses.as
+++ b/frameworks/projects/MXRoyale/src/main/royale/MXRoyaleClasses.as
@@ -37,6 +37,9 @@ internal class MXRoyaleClasses
import mx.containers.ControlBar; ControlBar;
import mx.controls.ToolTip; ToolTip;
import mx.controls.beads.ToolTipBead; ToolTipBead;
+ import mx.collections.CursorBookmark; CursorBookmark;
+ import mx.collections.ICollectionView; ICollectionView;
+ import mx.collections.IViewCursor; IViewCursor;
import mx.events.SandboxMouseEvent; SandboxMouseEvent;
import mx.events.ResizeEvent; ResizeEvent;
import mx.utils.StringUtil; StringUtil;
diff --git a/frameworks/projects/MXRoyale/src/main/royale/mx/collections/CursorBookmark.as b/frameworks/projects/MXRoyale/src/main/royale/mx/collections/CursorBookmark.as
new file mode 100644
index 000000000..59b1b7afe
--- /dev/null
+++ b/frameworks/projects/MXRoyale/src/main/royale/mx/collections/CursorBookmark.as
@@ -0,0 +1,164 @@
+////////////////////////////////////////////////////////////////////////////////
+//
+// 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
+{
+
+/**
+ * Encapsulates the positional aspects of a cursor in an
+ * <code>ICollectionView</code>. Bookmarks are used to return a cursor to
+ * an absolute position within the <code>ICollectionView</code>.
+ *
+ * @see mx.collections.IViewCursor#bookmark
+ * @see mx.collections.IViewCursor#seek()
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+public class CursorBookmark
+{
+/* include "../core/Version.as";
+ */
+ private static var _first:CursorBookmark;
+ private static var _last:CursorBookmark;
+ private static var _current:CursorBookmark;
+
+ /**
+ * A bookmark for the first item in an <code>ICollectionView</code>.
+ *
+ * @return The bookmark to the first item.
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ public static function get FIRST():CursorBookmark
+ {
+ if (!_first)
+ _first = new CursorBookmark("${F}");
+ return _first;
+ }
+
+ /**
+ * A bookmark for the last item in an <code>ICollectionView</code>.
+ * If the view has no items, the cursor is at this bookmark.
+ *
+ * @return The bookmark to the last item.
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ public static function get LAST():CursorBookmark
+ {
+ if (!_last)
+ _last = new CursorBookmark("${L}");
+ return _last;
+ }
+
+ /**
+ * A bookmark representing the current item for the <code>IViewCursor</code> in
+ * an <code>ICollectionView</code>.
+ *
+ * @return The bookmark to the current item.
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ public static function get CURRENT():CursorBookmark
+ {
+ if (!_current)
+ _current = new CursorBookmark("${C}");
+ return _current;
+ }
+
+ /**
+ * Creates a new instance of a bookmark with the specified value.
+ *
+ * @param value The value of this bookmark.
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ public function CursorBookmark(value:Object)
+ {
+ super();
+ _value = value;
+ }
+
+ //--------------------------------------------------------------------------
+ //
+ // Properties
+ //
+ //--------------------------------------------------------------------------
+
+ //----------------------------------
+ // value
+ //----------------------------------
+
+ private var _value:Object;
+
+ /**
+ * The underlying marker representation of the bookmark.
+ * This value is generally understood only by the <code>IViewCursor</code>
+ * or <code>ICollectionView</code> implementation.
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ public function get value():Object
+ {
+ return _value;
+ }
+
+ //--------------------------------------------------------------------------
+ //
+ // Methods
+ //
+ //--------------------------------------------------------------------------
+
+ /**
+ * Classes that extend CursorBookmark override this method to
+ * return the approximate index of the item represented by this
+ * bookmark in its view.
+ *
+ * @return -1
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ public function getViewIndex():int
+ {
+ return -1;
+ }
+}
+
+}
diff --git a/frameworks/projects/MXRoyale/src/main/royale/mx/collections/ICollectionView.as b/frameworks/projects/MXRoyale/src/main/royale/mx/collections/ICollectionView.as
new file mode 100644
index 000000000..6d193ff5e
--- /dev/null
+++ b/frameworks/projects/MXRoyale/src/main/royale/mx/collections/ICollectionView.as
@@ -0,0 +1,296 @@
+////////////////////////////////////////////////////////////////////////////////
+//
+// 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;
+ */
+ import org.apache.royale.events.IEventDispatcher;
+ import mx.events.CollectionEvent;
+
+/**
+ * Dispatched when the ICollectionView has been updated in some way.
+ *
+ * @eventType mx.events.CollectionEvent.COLLECTION_CHANGE
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+[Event(name="collectionChange", type="mx.events.CollectionEvent")]
+
+/**
+ * An <code>ICollectionView</code> is a view onto a collection of data.
+ * The view can be modified to show the data sorted according to various
+ * criteria or reduced by filters without modifying the underlying data.
+ * An IViewCursor provides to access items within a
+ * collection. You can modify the collection by using the IViewCursor
+ * interface <code>insert()</code> and <code>remove()</code> methods.
+ *
+ * <p>An <code>ICollectionView</code> may be a view onto data that has been
+ * retrieved from a remote location.
+ * When Implementing this interface for data
+ * that may be remote it is important to handle the case where data
+ * may not yet be available, which is indicated by the
+ * <code>ItemPendingError</code>.</p>
+ *
+ * <p>The <code>IList</code> interface is an alternative to the
+ * <code>ICollectionView</code> interface.</p>
+ *
+ * @see mx.collections.IViewCursor
+ * @see mx.collections.errors.ItemPendingError
+ * @see mx.collections.IList
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+public interface ICollectionView extends IEventDispatcher
+{
+ //--------------------------------------------------------------------------
+ //
+ // Properties
+ //
+ //--------------------------------------------------------------------------
+
+ //----------------------------------
+ // length
+ //----------------------------------
+
+ /**
+ * The number of items in this view.
+ * 0 means no items, while -1 means that the length is unknown.
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ function get length():int;
+
+ //----------------------------------
+ // filterFunction
+ //----------------------------------
+
+ /**
+ * A function that the view will use to eliminate items that do not
+ * match the function's criteria.
+ * A filterFunction is expected to have the following signature:
+ *
+ * <pre>f(item:Object):Boolean</pre>
+ *
+ * where the return value is <code>true</code> if the specified item
+ * should remain in the view.
+ *
+ * <p>If a filter is unsupported, Flex throws an error when accessing
+ * this property.
+ * You must call <code>refresh()</code> after setting the
+ * <code>filterFunction</code> property for the view to update.</p>
+ *
+ * <p>Note: The Flex implementations of ICollectionView retrieve all
+ * items from a remote location before executing the filter function.
+ * If you use paging, apply the filter to the remote collection before
+ * you retrieve the data.</p>
+ *
+ * @see #refresh()
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ function get filterFunction():Function;
+
+ /**
+ * @private
+ */
+ function set filterFunction(value:Function):void;
+
+ //----------------------------------
+ // sort
+ //----------------------------------
+
+ /**
+ * The ISort that will be applied to the ICollectionView.
+ * Setting the sort does not automatically refresh the view,
+ * so you must call the <code>refresh()</code> method
+ * after setting this property.
+ * If sort is unsupported an error will be thrown when accessing
+ * this property.
+ *
+ * <p>Note: The Flex implementations of ICollectionView retrieve all
+ * items from a remote location before executing a sort.
+ * If you use paging with a sorted list, apply the sort to the remote
+ * collection before you retrieve the data.</p>
+ *
+ * @see #refresh()
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ function get sort():ISort;
+
+ /**
+ * @private
+ */
+ function set sort(value:ISort):void;
+
+ //--------------------------------------------------------------------------
+ //
+ // Methods
+ //
+ //--------------------------------------------------------------------------
+
+ /**
+ * Creates a new IViewCursor that works with this view.
+ *
+ * @return A new IViewCursor implementation.
+ *
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ function createCursor():IViewCursor;
+
+ /**
+ * Returns whether the view contains the specified object.
+ * Unlike the <code>IViewCursor.find<i>xxx</i></code> methods,
+ * this search is succesful only if it finds an item that exactly
+ * matches the parameter.
+ * If the view has a filter applied to it this method may return
+ * <code>false</code> even if the underlying collection
+ * does contain the item.
+ *
+ * @param item The object to look for.
+ *
+ * @return true if the ICollectionView, after applying any filter,
+ * contains the item; false otherwise.
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ function contains(item:Object):Boolean;
+
+ /**
+ * Prevents changes to the collection itself and items within the
+ * collection from being dispatched by the view.
+ * Also prevents the view from updating the positions of items
+ * if the positions change in the collection.
+ * The changes will be queued and dispatched appropriately
+ * after <code>enableAutoUpdate</code> is called.
+ * If more events than updates to a single item occur,
+ * the view may end up resetting.
+ * The <code>disableAutoUpdate</code> method acts cumulatively;
+ * the same number of calls to <code>enableAutoUpdate</code>
+ * are required for the view to dispatch events and refresh.
+ * Note that <code>disableAutoUpdate</code> only affects the
+ * individual view; edits may be detected on an individual
+ * basis by other views.
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ function disableAutoUpdate():void;
+
+ /**
+ * Enables auto-updating.
+ * See <code>disableAutoUpdate</code> for more information.
+ *
+ * @see #disableAutoUpdate()
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ function enableAutoUpdate():void;
+
+ /**
+ * Notifies the view that an item has been updated.
+ * This method is useful if the contents of the view do not implement
+ * <code>IPropertyChangeNotifier</code>.
+ * If the call to this method includes a <code>property</code> parameter,
+ * the view may be able to optimize its notification mechanism.
+ * Otherwise it may choose to simply refresh the whole view.
+ *
+ * @param item The item within the view that was updated.
+ *
+ * @param property The name of the property that was updated.
+ *
+ * @param oldValue The old value of that property. (If property
+ * was null, this can be the old value of the item.).
+ *
+ * @param newValue The new value of that property. (If property
+ * was null, there's no need to specify this as the item is assumed
+ * to be the new value.)
+ *
+ * @see mx.events.CollectionEvent
+ * @see mx.core.IPropertyChangeNotifier
+ * @see mx.events.PropertyChangeEvent
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ function itemUpdated(item:Object, property:Object = null,
+ oldValue:Object = null, newValue:Object = null):void;
+
+ /**
+ * Applies the sort and filter to the view.
+ * The ICollectionView does not detect changes to a sort or
+ * filter automatically, so you must call the <code>refresh()</code>
+ * method to update the view after setting the <code>sort</code>
+ * or <code>filterFunction</code> property.
+ * If your ICollectionView implementation also implements
+ * the IMXMLObject interface, you should to call the
+ * <code>refresh()</code> method from your <code>initialized()</code>
+ * method.
+ *
+ * <p>Returns <code>true</code> if the refresh was successful
+ * and <code>false</code> if the sort is not yet complete
+ * (e.g., items are still pending).
+ * A client of the view should wait for a CollectionEvent event
+ * with the <code>CollectionEventKind.REFRESH</code> <code>kind</code>
+ * property to ensure that the <code>refresh()</code> operation is
+ * complete.</p>
+ *
+ * @return <code>true</code> if the refresh() was complete,
+ * <code>false</code> if the refresh() is incomplete.
+ *
+ * @langversion 3.0
+ * @playerversion Flash 9
+ * @playerversion AIR 1.1
+ * @productversion Royale 0.9.3
+ */
+ function refresh():Boolean;
+}
+
+}
diff --git a/frameworks/projects/MXRoyale/src/main/royale/mx/collections/IViewCursor.as b/frameworks/projects/MXRoyale/src/main/royale/mx/collections/IViewCursor.as
new file mode 100644
index 000000000..24a6e7d18
--- /dev/null
+++ b/frameworks/projects/MXRoyale/src/main/royale/mx/collections/IViewCursor.as
@@ -0,0 +1,466 @@
+////////////////////////////////////////////////////////////////////////////////
+//
+// 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;
+ */
+ import org.apache.royale.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 Royale 0.9.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 Royale 0.9.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 Royale 0.9.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 Royale 0.9.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 Royale 0.9.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 Royale 0.9.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 Royale 0.9.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 cannot 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 Royale 0.9.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 cannot 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 Royale 0.9.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 cannot 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 Royale 0.9.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 Royale 0.9.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 Royale 0.9.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 Royale 0.9.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 Royale 0.9.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 Royale 0.9.3
+ */
+ function seek(bookmark:CursorBookmark, offset:int = 0, prefetch:int = 0):void;
+}
+
+}
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services