IViewCursor - Adobe ActionScript® 3 (AS3 Flex) API 参考

包	mx.collections
接口	public interface IViewCursor extends IEventDispatcher

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

定义双向枚举集合视图的接口。此光标提供查找、搜索和标记为书签的功能，还提供修改方法插入和删除。首次从视图检索光标（通常使用 ICollectionViewcreateCursor() 方法）时，current 属性的值应是该视图中的第一个项目，除非视图为空。

公共属性

	属性		由以下参数定义
		afterLast : Boolean [只读] 如果将光标定位于视图中最后一个项目之后，则此属性为 true。	IViewCursor
		beforeFirst : Boolean [只读] 如果将光标定位于视图中第一个项目之前，此属性为 true。	IViewCursor
		bookmark : CursorBookmark [只读] 可以访问与当前属性返回的项目相对应的书签。	IViewCursor
		current : Object [只读] 可以访问位于此光标引用的源集合中的位置的对象。	IViewCursor
		view : ICollectionView [只读] 对与此光标关联的 ICollectionView 的引用。	IViewCursor

公共方法

隐藏继承的公共方法

显示继承的公共方法

	方法		由以下参数定义
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void 使用 EventDispatcher 对象注册事件侦听器对象，以使侦听器能够接收事件通知。	IEventDispatcher
		dispatchEvent(event:Event):Boolean 将事件调度到事件流中。	IEventDispatcher
		findAny(values:Object):Boolean 查找集合中具有指定属性的项目并将光标定位到该项目。	IViewCursor
		findFirst(values:Object):Boolean 查找集合中具有指定属性的第一个项目，并将光标定位到该项目。	IViewCursor
		findLast(values:Object):Boolean 查找集合中具有指定属性的最后一个项目，并将光标定位到该项目。	IViewCursor
		hasEventListener(type:String):Boolean 检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。	IEventDispatcher
		insert(item:Object):void 在光标的当前位置之前插入指定的项目。	IViewCursor
		moveNext():Boolean 将光标移动到集合中的下一个项目。	IViewCursor
		movePrevious():Boolean 将光标移动到集合中的上一个项目。	IViewCursor
		remove():Object 删除当前项目并返回该项目。	IViewCursor
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void 从 EventDispatcher 对象中删除侦听器。	IEventDispatcher
		seek(bookmark:CursorBookmark, offset:int = 0, prefetch:int = 0):void 将光标移动到与指定书签位置存在一定偏移量的某个位置。	IViewCursor
		willTrigger(type:String):Boolean 检查是否用此 EventDispatcher 对象或其任何祖代为指定事件类型注册了事件侦听器。	IEventDispatcher

事件

单击此处了解有关事件的更多信息

	事件		摘要	由以下参数定义
		cursorUpdate	光标位置更新时调度。	IViewCursor

属性详细信息

afterLast

属性

afterLast:Boolean [只读]

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

如果将光标定位于视图中的最后一个项目之后，则此属性为 true。如果 ICollectionView 为空（长度 == 0），此属性为 true。

此属性可用作数据绑定的源。修改此属性后，将调度 cursorUpdate 事件。

实现
public function get afterLast():Boolean

beforeFirst

属性

beforeFirst:Boolean [只读]

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

如果将光标定位于视图中第一个项目之前，则此属性为 true。如果 ICollectionView 为空（长度 == 0），此属性为 true。

此属性可用作数据绑定的源。修改此属性后，将调度 cursorUpdate 事件。

实现
public function get beforeFirst():Boolean

bookmark

属性

bookmark:CursorBookmark [只读]

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

可以访问与 current 属性返回的项目相对应的书签。该书签可用于将光标移动到先前访问的项目或相对于该项目的位置。（有关详细信息，请参阅 seek() 方法。）

此属性可用作数据绑定的源。修改此属性后，将调度 cursorUpdate 事件。

实现
public function get bookmark():CursorBookmark

相关 API 元素

current
seek()

current

属性

current:Object [只读]

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

可以访问位于此光标引用的源集合中的位置的对象。如果光标超出了集合末端（beforeFirst 和 afterLast），这将返回 null。

此属性可用作数据绑定的源。修改此属性后，将调度 cursorUpdate 事件。

实现
public function get current():Object

view

属性

view:ICollectionView [只读]

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

对与此光标关联的 ICollectionView 的引用。

实现
public function get view():ICollectionView

方法详细信息

findAny

()

方法

public function findAny(values:Object):Boolean

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

查找集合中具有指定属性的项目并将光标定位到该项目。如果无法找到该项目，光标位置不会更改。

仅可对排序后的视图调用 findAny() 方法；如果视图未排序，将引发 CursorError。

如果相关联的集合是远程集合，而且并非所有项目都已在本地缓存，则此方法将开始从远程集合异步获取。如果正在执行某个获取请求，此方法将等待其完成，然后才发出另一获取请求。

如果有多个项目与该搜索条件匹配，则找到的项目具有不确定性。如果必须在非唯一索引中找到第一个出现的项目或最后个一出现的项目，请使用 findFirst() 或 findLast() 方法。

如果不是本地数据，并且必须执行异步操作，则会引发 ItemPendingError。

参数

values:Object — 搜索条件。Object 中的值必须配置为名称-值对，就像关联数组中那样（或者是要搜索的实际对象）。指定的名称值必须与排序中指定的属性相匹配。例如，如果属性 x、y 和 z 位于当前排序中，则指定的值应为 {x: x-value、y: y-value 和 z: z-value}。

Boolean — 所有数据都是本地数据时，如果可以找到该项目，此方法将返回 true，否则返回 false。

findFirst

()

方法

public function findFirst(values:Object):Boolean

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

查找集合中具有指定属性的第一个项目，并将光标定位到该项目。如果无法找到该项目，所有光标位置都会更改。

仅可对排序后的视图调用 findFirst() 方法；如果视图未排序，则会引发 CursorError。

如果没有必要查找非唯一索引中第一个出现的项目，可使用 findAny()，它可以比 findFirst() method 稍快些。

如果不是本地数据，并且必须执行异步操作，则会引发 ItemPendingError。

参数

Boolean — 所有数据都是本地数据时，如果可以找到该项目，此方法将返回 true，否则返回 false。

findLast

()

方法

public function findLast(values:Object):Boolean

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

查找集合中具有指定属性的最后一个项目，并将光标定位到该项目。如果无法找到该项目，光标位置不会更改。

仅可对排序后的视图调用 findLast() 方法；如果视图未排序，则会引发 CursorError。

如果没有必要查找非唯一索引中最后一个出现的项目，可使用 findAny() 方法，该方法的速度可以稍微快些。

如果不是本地数据，并且必须执行异步操作，则会引发 ItemPendingError。

参数

Boolean — 所有数据都是本地数据时，如果可以找到该项目，此方法将返回 true，否则返回 false。

insert

()

方法

public function insert(item:Object):void

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

在光标的当前位置之前插入指定的项目。如果光标为 afterLast，将在视图的末尾执行插入。如果光标为非空视图上的 beforeFirst，将引发错误。

参数

item:Object — 要插入光标当前位置之前的项目。

moveNext

()

方法

public function moveNext():Boolean

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

将光标移动到集合中的下一个项目。只有成功更新 current 属性，才能引用此新位置上的对象。如果生成的 current 属性有效，则返回 true，否则返回 false（属性值为 afterLast）。

如果不是本地数据，并且必须执行异步操作，则会引发 ItemPendingError。有关使用 ItemPendingError 的详细信息，请参阅 ItemPendingError 文档和集合文档。

Boolean — 如果仍在列表中，则为 true；如果 current 值原来或现在为 afterLast，则为 false。

示例
如何使用本示例

      var myArrayCollection:ICollectionView = new ArrayCollection([ "Bobby", "Mark", "Trevor", "Jacey", "Tyler" ]);
      var cursor:IViewCursor = myArrayCollection.createCursor();
      while (!cursor.afterLast)
      {
          trace(cursor.current);
          cursor.moveNext();
      }

movePrevious

()

方法

public function movePrevious():Boolean

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

将光标移动到集合中的上一个项目。只有成功更新 current 属性，才能引用此新位置上的对象。如果生成的 current 属性有效，则返回 true，否则返回 false（属性值为 beforeFirst）。

如果不是本地数据，并且必须执行异步操作，则会引发 ItemPendingError。有关使用 ItemPendingError 的详细信息，请参阅 ItemPendingError 文档和集合文档。

Boolean — 如果仍在列表中，则为 true；如果 current 值原来或现在为 beforeFirst，则为 false。例如：

      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

()

方法

public function remove():Object

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

删除当前项目并返回该项目。如果光标位置为 beforeFirst 或 afterLast，则会引发 CursorError。如果删除最后一个项目之外的任何项目，光标会移动到下一个项目。如果删除最后一个项目，光标将位于 AFTER_LAST 书签处。

如果已删除项目后面的项目不是本地项目，并且必须执行异步操作，则会引发 ItemPendingError。有关使用 ItemPendingError 的详细信息，请参阅 ItemPendingError 文档和集合文档。

Object — 被删除的项目。

相关 API 元素

mx.collections.errors.ItemPendingError

seek

()

方法

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

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

将光标移动到与指定书签位置存在一定偏移量的某个位置。偏移值可以为负，在这种情况下，光标将定位在位于指定书签前的项目的 offset 量处。

如果相关联的集合是远程集合，而且并非所有项目都已在本地缓存，则此方法将开始从远程集合异步获取。

如果不是本地数据，并且必须执行异步操作，则会引发 ItemPendingError。有关使用 ItemPendingError 的详细信息，请参阅 ItemPendingError 文档和集合文档。

参数

	`bookmark:CursorBookmark` — `CursorBookmark` 引用允许重新定位到特定位置的标记信息。可将此参数设置为从 `bookmark` 属性返回的值，或设置为以下常量书签值之一： `CursorBookmark.FIRST` — 从集合的开始位置（第一个元素）搜索 `CursorBookmark.CURRENT` — 从集合的当前位置搜索 `CursorBookmark.LAST` — 从集合的结束位置（最后一个元素）搜索

	`offset:int` (default = `0`) — 指示从距指定书签多远的位置搜索。如果指定的数字为负，则光标尝试向指定书签的前面移动。如果指定的偏移超出了集合的末尾，光标将定位在末尾之外的 `beforeFirst` 或 `afterLast` 位置。

	`prefetch:int` (default = `0`) — 用于远程数据。指示打算在完成搜索操作后在特定方向上遍历。这会减少搜索期间所需的网络往返次数。如果遍历方向在请求时已知，则可在请求遍历数据之前返回适量的数据。

相关 API 元素

mx.collections.errors.ItemPendingError

事件详细信息

cursorUpdate

事件

事件对象类型: mx.events.FlexEvent
属性 FlexEvent.type = mx.events.FlexEvent.CURSOR_UPDATE

语言版本:

ActionScript 3.0

产品版本:

Flex 3

运行时版本:

Flash Player 9, AIR 1.1

光标位置更新时调度。

FlexEvent.CURSOR_UPDATE 常量可为 cursorUpdate 事件定义事件对象的 type 属性值。

事件对象的属性有下列值：

属性	值
`bubbles`	false
`cancelable`	false
`currentTarget`	用于定义处理该事件的事件侦听器的对象。例如，如果您使用 `myButton.addEventListener()` 注册某个事件侦听器，则 myButton 为 `currentTarget` 的值。
`target`	调度该事件的 Object；它不一定是侦听该事件的 Object。使用 `currentTarget` 属性始终可以访问侦听事件的 Object。

法律声明 | 在线隐私策略

IViewCursor - AS3 Flex

类 x

afterLast

beforeFirst

bookmark

current

view

findAny

findFirst

findLast

insert

moveNext

movePrevious

remove

seek

cursorUpdate