You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/cb5de6a6a40abdcb0d9d5af825928dd62dc1ca64/content/spaces/cursors.textile?plain=1#L9-L17) -->
28
-
* The live cursors feature enables you to track the cursors of members within a space in realtime.
27
+
* [Live cursors](https://ably.com/docs/spaces/cursors) enable you to track the cursors of members within a {@link Space | space} in realtime.
29
28
*
30
29
* Cursor events are emitted whenever a member moves their mouse within a space. In order to optimize the efficiency and frequency of updates, cursor position events are automatically batched. The batching interval may be customized in order to further optimize for increased performance versus the number of events published.
31
30
*
32
31
* Live cursor updates are not available as part of the {@link Space.subscribe | space state} and must be subscribed to using {@link Cursors.subscribe | `space.cursors.subscribe()`}.
33
32
*
34
-
* > **Important**
35
-
* >
36
-
* > Live cursors are a great way of providing contextual awareness as to what members are looking at within an application. However, too many cursors moving across a page can often be a distraction rather than an enhancement. As such, Ably recommends a maximum of 20 members simultaneously streaming their cursors in a space at any one time for an optimal end-user experience.
37
-
*
38
-
* <!-- END WEBSITE DOCUMENTATION -->
39
-
*
40
-
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/cb5de6a6a40abdcb0d9d5af825928dd62dc1ca64/content/spaces/cursors.textile?plain=1#L254-L262) -->
41
-
* ## Live cursor foundations
42
-
*
43
-
* The Spaces SDK is built upon existing Ably functionality available in Ably’s Core SDKs. Understanding which core features are used to provide the abstractions in the Spaces SDK enables you to manage space state and build additional functionality into your application.
44
-
*
45
-
* Live cursors build upon the functionality of the Pub/Sub Channels [presence](https://ably.com/docs/presence-occupancy/presence) feature.
46
-
*
47
-
* Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own [channel](https://ably.com/docs/channels). The other features of the Spaces SDK, such as avatar stacks, member locations and component locking all share a single channel. For this same reason, cursor position updates are not included in the {@link Space.subscribe | space state } and may only be subscribed to via the {@link Space.cursors | `cursors` } property.
48
-
*
49
-
* The channel is only created when a member calls `space.cursors.set()`. The live cursors channel object can be accessed through `space.cursors.channel`. To monitor the [underlying state of the cursors channel](https://ably.com/docs/channels#states), the channel object can be accessed through `space.cursors.channel`.
50
-
*
51
-
* <!-- END WEBSITE DOCUMENTATION -->
52
-
*
53
-
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
54
-
* Handles tracking of member cursors within a space. Inherits from {@link EventEmitter}.
* Schedules a cursor update event to be sent that will cause the following events to fire
64
+
* Set the position of a member's cursor and emit an {@link CursorUpdate | `update`} event.
88
65
*
89
-
* @return {void}
90
-
*
91
-
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/cb5de6a6a40abdcb0d9d5af825928dd62dc1ca64/content/spaces/cursors.textile?plain=1#L21-L74) -->
92
-
* Set the position of a member’s cursor using the `set()` method. A position must contain an X-axis value and a Y-axis value to set the cursor position on a 2D plane. Calling `set()` will emit a cursor event so that other members are informed of the cursor movement in realtime.
93
-
*
94
-
* A member must have been { @link Space.enter | entered } into the space to set their cursor position.
95
-
*
96
-
* The `set()` method takes the following parameters:
66
+
* A position must contain an X-axis value and a Y-axis value to set the cursor position on a 2D plane. Data may optionally be passed containing additional information such as the color the cursor should be displayed as, or the ID of the element the member is dragging.
* | position.x | The position of the member’s cursor on the X-axis. | Number |
101
-
* | position.y | The position of the member’s cursor on the Y-axis. | Number |
102
-
* | data | An optional arbitrary JSON-serializable object containing additional information about the cursor, such as a color. | Object |
68
+
* A member must have been {@link Space.enter | entered} into the space to set their cursor position.
103
69
*
104
-
* > **Note**
105
-
* >
106
-
* > The `data` parameter can be used to stream additional information related to a cursor’s movement, such as:
107
-
* >
108
-
* > - The color that other member’s should display a cursor as.
109
-
* > - The ID of an element that a user may be dragging for drag and drop functionality.
110
-
* > - Details of any cursor annotations.
111
-
* >
112
-
* > Be aware that as live cursor updates are batched it is not advisable to publish data unrelated to cursor position in the `data` parameter. Use a [pub/sub channel](https://ably.com/docs/channels) instead.
70
+
* @return {void}
113
71
*
114
72
* The following is an example of a member setting their cursor position by adding an event listener to obtain their cursor coordinates and then publishing their position using the `set()` method:
* The following is an example payload of a cursor event. Cursor events are uniquely identifiable by the `connectionId` of a cursor.
122
-
*
123
-
* ```json
124
-
* {
125
-
* "hd9743gjDc": {
126
-
* "connectionId": "hd9743gjDc",
127
-
* "clientId": "clemons#142",
128
-
* "position": {
129
-
* "x": 864,
130
-
* "y": 32
131
-
* },
132
-
* "data": {
133
-
* "color": "red"
134
-
* }
135
-
* }
136
-
* }
137
-
* ```
138
-
* The following are the properties of a cursor event payload:
139
-
*
140
-
* > **Moved documentation**
141
-
* >
142
-
* > This documentation has been moved to {@link CursorUpdate} and {@link CursorPosition}.
143
-
*
144
-
* <!-- END WEBSITE DOCUMENTATION -->
145
-
*
146
-
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
147
-
* Set the position of a cursor. If a member has not yet entered the space, this method will error.
148
-
*
149
-
* A event payload returned contains an object with 2 properties. `position` is an object with 2 required properties, `x` and `y`. These represent the position of the cursor on a 2D plane. A second optional property, `data` can also be passed. This is an object of any shape and is meant for data associated with the cursor movement (like drag or hover calculation results):
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/cb5de6a6a40abdcb0d9d5af825928dd62dc1ca64/content/spaces/cursors.textile?plain=1#L78-L90) -->
220
-
* Subscribe to cursor events by registering a listener. Cursor events are emitted whenever a member moves their cursor by calling `set()`. Use the `subscribe()` method on the `cursors` object of a space to receive updates.
139
+
* Subscribe to cursor events by registering a listener. Cursor events are emitted whenever a member {@link Cursors.set | sets} their cursor position.
221
140
*
222
141
* > **Note**
223
142
* >
224
-
* > The rate at which cursor events are published is controlled by the `outboundBatchInterval` property set in the {@linkCursorsOptions | cursor options } of a space.
143
+
* > The rate at which cursor events are published is controlled by the {@link CursorsOptions.outboundBatchInterval | `outboundBatchInterval`} property set in the `CursorsOptions` of a space.
225
144
*
226
145
* The following is an example of subscribing to cursor events:
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/cb5de6a6a40abdcb0d9d5af825928dd62dc1ca64/content/spaces/cursors.textile?plain=1#L126-L211) -->
402
-
* Cursor positions can be retrieved in one-off calls. These are local calls that retrieve the latest position of cursors retained in memory by the SDK.
287
+
* Retrieve the cursor position of all members in a one-off call. This is useful for retrieving the initial position of members's cursors.
403
288
*
404
-
* The following is an example of retrieving a member’s own cursor position:
405
-
*
406
-
* ```javascript
407
-
* const myCursor = await space.cursors.getSelf();
408
-
* ```
409
-
* The following is an example payload returned by `space.cursors.getSelf()`:
410
-
*
411
-
* ```json
412
-
* {
413
-
* “clientId”: “DzOBJqgGXzyUBb816Oa6i”,
414
-
* “connectionId”: “__UJBKZchX”,
415
-
* "position": {
416
-
* "x": 864,
417
-
* "y": 32
418
-
* }
419
-
* }
420
-
* ```
421
-
* The following is an example of retrieving the cursor positions for all members other than the member themselves:
* The following is an example payload returned by `space.cursors.getOthers()`:
427
-
*
428
-
* ```json
429
-
* {
430
-
* "3ej3q7yZZz": {
431
-
* "clientId": "yyXidHatpP3hJpMpXZi8W",
432
-
* "connectionId": "3ej3q7yZZz",
433
-
* "position": {
434
-
* "x": 12,
435
-
* "y": 3
436
-
* }
437
-
* },
438
-
* "Z7CA3-1vlR": {
439
-
* "clientId": "b18mj5B5hm-govdFEYRyb",
440
-
* "connectionId": "Z7CA3-1vlR",
441
-
* "position": {
442
-
* "x": 502,
443
-
* "y": 43
444
-
* }
445
-
* }
446
-
* }
447
-
* ```
448
-
* The following is an example of retrieving the cursor positions for all members, including the member themselves. `getAll()` is useful for retrieving the initial position of members’ cursors.
289
+
* The following is an example of retrieving the cursor positions for all members:
0 commit comments