# ProposedChangesCollection

class

A set of proposed changes for one or multiple documents. Keeps and manages these changes' current state.

The changes inside one set are logically related and can be thought as one "review". They are a result of one "processing cycle": one set of changes, all proposed together at once, for one or multiple documents, to be reviewed and accepted or rejected.

The proposed changes are given an index and are addressed by their index in the set. A change never leaves the set, and its index does not change. An accepted or rejected change is still kept in the set at its original index, and can be rendered for preview purposes.

Create the set from the proposed changes, then pass it to [create a controller](module_ai_toolkit_proposedchanges-ProposedChanges.md#function-createController), which binds the set with related editor instance(s) and optionally a view component. Read the set directly, but modify it through the controller API.

The set is owned by the integrator and outlives the controller. It can be passed to a new controller, for example to keep the review when the controller is re-created for a new editor instance. A set must be bound with one controller at a time.

<a id="methods"></a>

## Methods

<a id="function-constructor"></a>

### `constructor( changes )`

#### Parameters

* `changes: Array<DocumentChange & object>`

  The changes to review, in the order they should be reviewed in. A change may state its [decision](module_ai_toolkit_proposedchange-ProposedChange.md#member-state), to restore a review. Defaults to `'pending'`.

  Defaults to `[]`

<a id="function-delegate"></a>

### `delegate( events ) → EmitterMixinDelegateChain` _(inherited)_

Delegates selected events to another [`Emitter`](module_utils_emittermixin-Emitter.md). For instance:

```typescript
emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
```

then `eventX` is delegated (fired by) `emitterB` and `emitterC` along with `data`:

```typescript
emitterA.fire( 'eventX', data );
```

and `eventY` is delegated (fired by) `emitterC` along with `data`:

```typescript
emitterA.fire( 'eventY', data );
```

#### Parameters

* `events: Array<string>`

  Event names that will be delegated to another emitter.

#### Returns

* `EmitterMixinDelegateChain`

<a id="function-fire"></a>

### `fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]` _(inherited)_

Fires an event, executing all callbacks registered for it.

The first parameter passed to callbacks is an [`EventInfo`](module_utils_eventinfo-EventInfo.md) object, followed by the optional `args` provided in the `fire()` method call.

#### Type parameters

* `TEvent: extends BaseEvent`

  The type describing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### Parameters

* `eventOrInfo: GetNameOrEventInfo<TEvent>`

  The name of the event or `EventInfo` object if event is delegated.

* `args: TEvent[ 'args' ]`

  Additional arguments to be passed to the callbacks.

#### Returns

* `GetEventInfo<TEvent>[ 'return' ]`

  By default the method returns `undefined`. However, the return value can be changed by listeners through modification of the [`evt.return`](module_utils_eventinfo-EventInfo.md#member-return)'s property (the event info is the first param of every callback).

<a id="function-getActionableSibling"></a>

### `getActionableSibling( index, direction ) → number | null`

The position of the nearest [actionable](#function-isActionable) change in the given direction, or `null` when there is none.

It is cyclic: "next" from the last change is the first one. `null` is returned only once there are no actionable changes in the set.

#### Parameters

* `index: number`

  The index to step away from.

* `direction: 'next' | 'previous'`

  Which way to step.

#### Returns

* `number | null`

<a id="function-getChange"></a>

### `getChange( index ) → ProposedChange | undefined`

Returns the proposed change at `index`, or `undefined` when the set holds none there.

#### Parameters

* `index: number`

#### Returns

* `ProposedChange | undefined`

<a id="function-getChanges"></a>

### `getChanges() → readonly Array<ProposedChange>`

Returns the proposed changes.

#### Returns

* `readonly Array<ProposedChange>`

<a id="function-hasWritableChanges"></a>

### `hasWritableChanges() → boolean`

Whether there is any writable ("applicable") change in the collection.

#### Returns

* `boolean`

<a id="function-isActionable"></a>

### `isActionable( index ) → boolean`

Whether the user can make an action (accept or reject) for the change at `index`.

Actionable change must be in pending state (not accepted or rejected yet), it must yield actual change, it cannot be outdated (the related content must not be removed), and the related document must be available.

If the change affects a read-only content, it is still actionable. Such a change cannot be accepted, but it can be rejected.

An actionable change that can still be accepted [is writeable](#function-isWritable).

#### Parameters

* `index: number`

#### Returns

* `boolean`

<a id="function-isWritable"></a>

### `isWritable( index ) → boolean`

Whether the change at `index` can be accepted by the user.

It must [be actionable](#function-isActionable) and affect content that is not read-only.

#### Parameters

* `index: number`

#### Returns

* `boolean`

<a id="function-listenTo:BASE_EMITTER"></a>

### `listenTo( emitter, event, callback, options? ) → void` _(inherited)_

Registers a callback function to be executed when an event is fired in a specific (emitter) object.

Events can be grouped in namespaces using `:`. When namespaced event is fired, it additionally fires all callbacks for that namespace.

```typescript
// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );
```

An event callback can [stop the event](module_utils_eventinfo-EventInfo.md#member-stop) and set the [return value](module_utils_eventinfo-EventInfo.md#member-return) of the [`fire`](#function-fire) method.

#### Type parameters

* `TEvent: extends BaseEvent`

  The type describing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### Parameters

* `emitter: Emitter`

  The object that fires the event.

* `event: TEvent[ 'name' ]`

  The name of the event.

* `callback: GetCallback<TEvent>`

  The function to be called on event.

* `options?: GetCallbackOptions<TEvent>`

  Additional options.

#### Returns

* `void`

<a id="function-off"></a>

### `off( event, callback ) → void` _(inherited)_

Stops executing the callback on the given event. Shorthand for [`this.stopListening( this, event, callback )`](#function-stopListening:BASE_STOP).

#### Parameters

* `event: string`

  The name of the event.

* `callback: Function`

  The function to stop being called.

#### Returns

* `void`

<a id="function-on"></a>

### `on( event, callback, options? ) → void` _(inherited)_

Registers a callback function to be executed when an event is fired.

Shorthand for [`this.listenTo( this, event, callback, options )`](#function-listenTo:BASE_EMITTER) (it makes the emitter listen on itself).

#### Type parameters

* `TEvent: extends BaseEvent`

  The type descibing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### Parameters

* `event: TEvent[ 'name' ]`

  The name of the event.

* `callback: GetCallback<TEvent>`

  The function to be called on event.

* `options?: GetCallbackOptions<TEvent>`

  Additional options.

#### Returns

* `void`

<a id="function-once"></a>

### `once( event, callback, options? ) → void` _(inherited)_

Registers a callback function to be executed on the next time the event is fired only. This is similar to calling [`on`](#function-on) followed by [`off`](#function-off) in the callback.

#### Type parameters

* `TEvent: extends BaseEvent`

  The type descibing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### Parameters

* `event: TEvent[ 'name' ]`

  The name of the event.

* `callback: GetCallback<TEvent>`

  The function to be called on event.

* `options?: GetCallbackOptions<TEvent>`

  Additional options.

#### Returns

* `void`

<a id="function-stopDelegating"></a>

### `stopDelegating( event?, emitter? ) → void` _(inherited)_

Stops delegating events. It can be used at different levels:

* To stop delegating all events.
* To stop delegating a specific event to all emitters.
* To stop delegating a specific event to a specific emitter.

#### Parameters

* `event?: string`

  The name of the event to stop delegating. If omitted, stops it all delegations.

* `emitter?: Emitter`

  (requires `event`) The object to stop delegating a particular event to. If omitted, stops delegation of `event` to all emitters.

#### Returns

* `void`

<a id="function-stopListening:BASE_STOP"></a>

### `stopListening( emitter?, event?, callback? ) → void` _(inherited)_

Stops listening for events. It can be used at different levels:

* To stop listening to a specific callback.
* To stop listening to a specific event.
* To stop listening to all events fired by a specific object.
* To stop listening to all events fired by all objects.

#### Parameters

* `emitter?: Emitter`

  The object to stop listening to. If omitted, stops it for all objects.

* `event?: string`

  (Requires the `emitter`) The name of the event to stop listening to. If omitted, stops it for all events from `emitter`.

* `callback?: Function`

  (Requires the `event`) The function to be removed from the call list for the given `event`.

#### Returns

* `void`

<a id="events"></a>

## Events

<a id="event-changeUpdated"></a>

### `changeUpdated( eventInfo, <anonymous> = { <anonymous>.change, <anonymous>.index } )`

Fired whenever anything about a proposed change state changes.

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `<anonymous>: object`

  Properties

  * `<anonymous>.change: ProposedChange`
  * `<anonymous>.index: number`

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)