# DowncastDispatcher

class

The downcast dispatcher is a central point of downcasting (conversion from the model to the view), which is a process of reacting to changes in the model and firing a set of events. The callbacks listening to these events are called converters. The converters' role is to convert the model changes to changes in view (for example, adding view nodes or changing attributes on view elements).

During the conversion process, downcast dispatcher fires events basing on the state of the model and prepares data for these events. It is important to understand that the events are connected with the changes done on the model, for example: "a node has been inserted" or "an attribute has changed". This is in contrary to upcasting (a view-to-model conversion) where you convert the view state (view nodes) to a model tree.

The events are prepared basing on a diff created by the [Differ](module_engine_model_differ-Differ.md), which buffers them and then passes to the downcast dispatcher as a diff between the old model state and the new model state.

Note that because the changes are converted, there is a need to have a mapping between the model structure and the view structure. To map positions and elements during the downcast (a model-to-view conversion), use [`Mapper`](module_engine_conversion_mapper-Mapper.md).

Downcast dispatcher fires the following events for model tree changes:

* [`insert`](#event-insert) – If a range of nodes was inserted to the model tree.
* [`remove`](#event-remove) – If a range of nodes was removed from the model tree.
* [`attribute`](#event-attribute) – If an attribute was added, changed or removed from a model node.

For [`insert`](#event-insert) and [`attribute`](#event-attribute), the downcast dispatcher generates [consumables](module_engine_conversion_modelconsumable-ModelConsumable.md). These are used to have control over which changes have already been consumed. It is useful when some converters overwrite others or convert multiple changes (for example, it converts an insertion of an element and also converts that element's attributes during the insertion).

Additionally, downcast dispatcher fires events for [marker](module_engine_model_markercollection-Marker.md) changes:

* [`addMarker`](#event-addMarker) – If a marker was added.
* [`removeMarker`](#event-removeMarker) – If a marker was removed.

Note that changing a marker is done through removing the marker from the old range and adding it to the new range, so both of these events are fired.

Finally, a downcast dispatcher also handles firing events for the [model selection](module_engine_model_selection.md) conversion:

* [`selection`](#event-selection) – Converts the selection from the model to the view.
* [`attribute`](#event-attribute) – Fired for every selection attribute.
* [`addMarker`](#event-addMarker) – Fired for every marker that contains a selection.

Unlike the model tree and the markers, the events for selection are not fired for changes but for a selection state.

When providing custom listeners for a downcast dispatcher, remember to check whether a given change has not been [consumed](module_engine_conversion_modelconsumable-ModelConsumable.md#function-consume) yet.

When providing custom listeners for a downcast dispatcher, keep in mind that you **should not** stop the event. If you stop it, then the default converter at the `lowest` priority will not trigger the conversion of this node's attributes and child nodes.

When providing custom listeners for a downcast dispatcher, remember to use the provided [view downcast writer](module_engine_view_downcastwriter-ViewDowncastWriter.md) to apply changes to the view document.

You can read more about conversion in the following guide:

* [Downcast conversion](../framework/deep-dive/conversion/downcast.md)

An example of a custom converter for the downcast dispatcher:

```typescript
// You will convert inserting a "paragraph" model element into the model.
downcastDispatcher.on( 'insert:paragraph', ( evt, data, conversionApi ) => {
	// Remember to check whether the change has not been consumed yet and consume it.
	if ( !conversionApi.consumable.consume( data.item, 'insert' ) ) {
		return;
	}

	// Translate the position in the model to a position in the view.
	const viewPosition = conversionApi.mapper.toViewPosition( data.range.start );

	// Create a <p> element that will be inserted into the view at the `viewPosition`.
	const viewElement = conversionApi.writer.createContainerElement( 'p' );

	// Bind the newly created view element to the model element so positions will map accordingly in the future.
	conversionApi.mapper.bindElements( data.item, viewElement );

	// Add the newly created view element to the view.
	conversionApi.writer.insert( viewPosition, viewElement );
} );
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L123)

<a id="properties">

## Properties

<a id="member-_conversionApi">

### `_conversionApi: Pick<DowncastConversionApi, 'dispatcher' | 'mapper' | 'schema'>` _(internal)_

A template for an interface passed by the dispatcher to the event callbacks.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L129)

<a id="member-_firedEventsMap">

### `_firedEventsMap: WeakMap<DowncastConversionApi, Map<unknown, Set<string>>>` _(private)_

A map of already fired events for a given `ModelConsumable`.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L134)

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( conversionApi )`

Creates a downcast dispatcher instance.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L144)

#### Parameters

* `conversionApi: Pick<DowncastConversionApi, 'mapper' | 'schema'>`

  Additional properties for an interface that will be passed to events fired by the downcast dispatcher.

#### Related:

* [DowncastConversionApi](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md)

<a id="function-convert">

### `convert( range, markers, writer, options ) → void`

Starts a conversion of a model range and the provided markers.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L242)

#### Parameters

* `range: ModelRange`

  The inserted range.

* `markers: Map<string, ModelRange>`

  The map of markers that should be down-casted.

* `writer: ViewDowncastWriter`

  The view writer that should be used to modify the view document.

* `options: Record<string, unknown>`

  Optional options object passed to `convertionApi.options`.

  Defaults to `{}`

#### Returns

* `void`

#### Fires

* [insert](#event-insert)
* [attribute](#event-attribute)
* [addMarker](#event-addMarker)

<a id="function-convertChanges">

### `convertChanges( differ, markers, writer ) → void`

Converts changes buffered in the given [model differ](module_engine_model_differ-Differ.md) and fires conversion events based on it.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L165)

#### Parameters

* `differ: Differ`

  The differ object with buffered changes.

* `markers: MarkerCollection`

  Markers related to the model fragment to convert.

* `writer: ViewDowncastWriter`

  The view writer that should be used to modify the view document.

#### Returns

* `void`

#### Fires

* [insert](#event-insert)
* [remove](#event-remove)
* [attribute](#event-attribute)
* [addMarker](#event-addMarker)
* [removeMarker](#event-removeMarker)
* [reduceChanges](#event-reduceChanges)

<a id="function-convertSelection">

### `convertSelection( selection, markers, writer ) → void`

Starts the model selection conversion.

Fires events for a given [selection](module_engine_model_selection-ModelSelection.md) to start the selection conversion.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L274)

#### Parameters

* `selection: ModelSelection | ModelDocumentSelection`

  The selection to convert.

* `markers: MarkerCollection`

  Markers connected with the converted model.

* `writer: ViewDowncastWriter`

  View writer that should be used to modify the view document.

#### Returns

* `void`

#### Fires

* [selection](#event-selection)
* [addMarker](#event-addMarker)
* [attribute](#event-attribute)

<a id="function-delegate">

### `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 );
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L539)

#### Parameters

* `events: Array<string>`

  Event names that will be delegated to another emitter.

#### Returns

* `EmitterMixinDelegateChain`

<a id="function-fire">

### `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.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L512)

#### 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-listenTo:BASE_EMITTER">

### `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.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L475)

#### 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">

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

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L444)

#### Parameters

* `event: string`

  The name of the event.

* `callback: Function`

  The function to stop being called.

#### Returns

* `void`

<a id="function-on">

### `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).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L416)

#### 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">

### `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.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L431)

#### 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">

### `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.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L552)

#### 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">

### `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.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L497)

#### 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="function-_addConsumablesForInsert">

### `_addConsumablesForInsert( consumable, walkerValues ) → ModelConsumable` _(private)_

Populates provided [`ModelConsumable`](module_engine_conversion_modelconsumable-ModelConsumable.md) with values to consume from a given range, assuming that the range has just been inserted to the model.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L557)

#### Parameters

* `consumable: ModelConsumable`

  The consumable.

* `walkerValues: Iterable<ModelTreeWalkerValue>`

  The walker values for the inserted range.

#### Returns

* `ModelConsumable`

  The values to consume.

<a id="function-_addConsumablesForRange">

### `_addConsumablesForRange( consumable, range, type ) → ModelConsumable` _(private)_

Populates provided [`ModelConsumable`](module_engine_conversion_modelconsumable-ModelConsumable.md) with values to consume for a given range.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L585)

#### Parameters

* `consumable: ModelConsumable`

  The consumable.

* `range: ModelRange`

  The affected range.

* `type: string`

  Consumable type.

#### Returns

* `ModelConsumable`

  The values to consume.

<a id="function-_addConsumablesForSelection">

### `_addConsumablesForSelection( consumable, selection, markers ) → ModelConsumable` _(private)_

Populates provided [`ModelConsumable`](module_engine_conversion_modelconsumable-ModelConsumable.md) with selection consumable values.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L605)

#### Parameters

* `consumable: ModelConsumable`

  The consumable.

* `selection: ModelSelection | ModelDocumentSelection`

  The selection to create the consumable from.

* `markers: Iterable<Marker>`

  Markers that contain the selection.

#### Returns

* `ModelConsumable`

  The values to consume.

<a id="function-_convertAttribute">

### `_convertAttribute( range, key, oldValue, newValue, conversionApi ) → void` _(private)_

Starts a conversion of an attribute change on a given `range`.

For each node in the given `range`, [attribute event](#event-attribute) is fired with the passed data.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L395)

#### Parameters

* `range: ModelRange`

  Changed range.

* `key: string`

  Key of the attribute that has changed.

* `oldValue: unknown`

  Attribute value before the change or `null` if the attribute has not been set before.

* `newValue: unknown`

  New attribute value or `null` if the attribute has been removed.

* `conversionApi: DowncastConversionApi`

  The conversion API object.

#### Returns

* `void`

#### Fires

* [attribute](#event-attribute)

<a id="function-_convertInsert">

### `_convertInsert( range, conversionApi, options = { options.doNotAddConsumables? } ) → void` _(private)_

Fires insertion conversion of a range of nodes.

For each node in the range, [`insert` event is fired](#event-insert). For each attribute on each node, [`attribute` event is fired](#event-attribute).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L350)

#### Parameters

* `range: ModelRange`

  The inserted range.

* `conversionApi: DowncastConversionApi`

  The conversion API object.

* `options: object`

  Properties

  * `options.doNotAddConsumables?: boolean`

    Whether the ModelConsumable should not get populated for items in the provided range.

  Defaults to `{}`

#### Returns

* `void`

#### Fires

* [insert](#event-insert)
* [attribute](#event-attribute)

<a id="function-_convertMarkerAdd">

### `_convertMarkerAdd( markerName, markerRange, conversionApi ) → void` _(private)_

Converts the added marker. Fires the [`addMarker`](#event-addMarker) event for each item in the marker's range. If the range is collapsed, a single event is dispatched. See the event description for more details.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L461)

#### Parameters

* `markerName: string`

  Marker name.

* `markerRange: ModelRange`

  The marker range.

* `conversionApi: DowncastConversionApi`

  The conversion API object.

#### Returns

* `void`

#### Fires

* [addMarker](#event-addMarker)

<a id="function-_convertMarkerRemove">

### `_convertMarkerRemove( markerName, markerRange, conversionApi ) → void` _(private)_

Fires the conversion of the marker removal. Fires the [`removeMarker`](#event-removeMarker) event with the provided data.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L514)

#### Parameters

* `markerName: string`

  Marker name.

* `markerRange: ModelRange`

  The marker range.

* `conversionApi: DowncastConversionApi`

  The conversion API object.

#### Returns

* `void`

#### Fires

* [removeMarker](#event-removeMarker)

<a id="function-_convertReinsert">

### `_convertReinsert( range, conversionApi ) → void` _(private)_

Fires re-insertion conversion (with a `reconversion` flag passed to `remove` and `insert` events) of a range of elements (only elements on the range depth, without children).

For each node in the range on its depth (without children), [`insert` event](#event-insert) is fired. For each attribute on each node, [`attribute` event](#event-attribute) is fired.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L431)

#### Parameters

* `range: ModelRange`

  The range to reinsert.

* `conversionApi: DowncastConversionApi`

  The conversion API object.

#### Returns

* `void`

#### Fires

* [insert](#event-insert)
* [attribute](#event-attribute)

<a id="function-_convertRemove">

### `_convertRemove( position, length, name, conversionApi ) → void` _(private)_

Fires conversion of a single node removal. Fires [remove event](#event-remove) with provided data.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L374)

#### Parameters

* `position: ModelPosition`

  Position from which node was removed.

* `length: number`

  Offset size of removed node.

* `name: string`

  Name of removed node.

* `conversionApi: DowncastConversionApi`

  The conversion API object.

#### Returns

* `void`

<a id="function-_createConversionApi">

### `_createConversionApi( writer, refreshedItems, options ) → DowncastConversionApi` _(private)_

Builds an instance of the [`DowncastConversionApi`](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md) from a template and a given [`ViewDowncastWriter`](module_engine_view_downcastwriter-ViewDowncastWriter.md) and options object.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L688)

#### Parameters

* `writer: ViewDowncastWriter`

  View writer that should be used to modify the view document.

* `refreshedItems: Set<ModelItem>`

  A set of model elements that should not reuse their previous view representations.

  Defaults to `...`

* `options: Record<string, unknown>`

  Optional options passed to `convertionApi.options`.

  Defaults to `{}`

#### Returns

* `DowncastConversionApi`

  The conversion API object.

<a id="function-_reduceChanges">

### `_reduceChanges( changes, refreshedItems ) → Iterable<DifferItem | DifferItemReinsert>` _(private)_

Fires the reduction of changes buffered in the [`Differ`](module_engine_model_differ-Differ.md).

Features can replace selected [`DifferItem`](module_engine_model_differ-DifferItem.md)s with `reinsert` entries to trigger reconversion. The [`DowncastHelpers.elementToStructure()`](module_engine_conversion_downcasthelpers-DowncastHelpers.md#function-elementToStructure) is using this event to trigger reconversion.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L532)

#### Parameters

* `changes: Iterable<DifferItem>`
* `refreshedItems: Set<ModelItem>`

#### Returns

* `Iterable<DifferItem | DifferItemReinsert>`

#### Fires

* [reduceChanges](#event-reduceChanges)

<a id="function-_testAndFire">

### `_testAndFire( type, data, conversionApi ) → void` _(private)_

Tests whether given event wasn't already fired and if so, fires it.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L632)

#### Type parameters

* `TType`

#### Parameters

* `` type: TType | `${ string }` ``

  Event type.

* `data: DowncastDispatcherEventMap<ModelItem>[ TType ]`

  Event data.

* `conversionApi: DowncastConversionApi`

  The conversion API object.

#### Returns

* `void`

#### Fires

* [insert](#event-insert)
* [attribute](#event-attribute)

<a id="function-_testAndFireAddAttributes">

### `_testAndFireAddAttributes( item, conversionApi ) → void` _(private)_

Fires not already fired events for setting attributes on just inserted item.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L660)

#### Parameters

* `item: ModelItem`

  The model item to convert attributes for.

* `conversionApi: DowncastConversionApi`

  The conversion API object.

#### Returns

* `void`

<a id="events">

## Events

<a id="event-addMarker">

### `addMarker( eventInfo, data, conversionApi )`

Fired when a new marker is added to the model. Also fired when a collapsed model selection that is inside a marker is converted.

`addMarker` is a namespace for a class of events. Names of actually called events follow this pattern: `addMarker:markerName`. By specifying certain marker names, you can make the events even more gradual. For example, if markers are named `foo:abc`, `foo:bar`, then it is possible to listen to `addMarker:foo` or `addMarker:foo:abc` and `addMarker:foo:bar` events.

If the marker range is not collapsed:

* the event is fired for each item in the marker range one by one,
* `conversionApi.consumable` includes each item of the marker range and the consumable value is same as the event name.

If the marker range is collapsed:

* there is only one event,
* `conversionApi.consumable` includes marker range with the event name.

If the selection inside a marker is converted:

* there is only one event,
* `conversionApi.consumable` includes the selection instance with the event name.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L905)

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `data: DowncastDispatcherEventMap<TItem>[ TName ]`

  Additional information about the change.

* `conversionApi: DowncastConversionApi`

  Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor.

<a id="event-attribute">

### `attribute( eventInfo, data, conversionApi )`

Fired in the following cases:

* when an attribute has been added, changed, or removed from a node,
* when a node with an attribute is inserted,
* when a collapsed model selection attribute is converted.

`attribute` is a namespace for a class of events. Names of actually called events follow this pattern: `attribute:attributeKey:name`. `attributeKey` is the key of added/changed/removed attribute. `name` is either `'$text'` if change was on [a text node](module_engine_model_text-ModelText.md), or the [name](module_engine_model_element-ModelElement.md#member-name) of element which attribute has changed.

This way listeners can either listen to a general `attribute:bold` event or specific event (for example `attribute:src:imageBlock`).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L846)

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `data: DowncastDispatcherEventMap<TItem>[ TName ]`

  Additional information about the change.

* `conversionApi: DowncastConversionApi`

  Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor.

<a id="event-cleanSelection">

### `cleanSelection( eventInfo, data, conversionApi )`

Fired at the beginning of selection conversion, before [selection](#event-selection) events.

Should be used to clean up the view state at the current selection position, before the selection is moved to another place.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L869)

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `data: DowncastDispatcherEventMap<TItem>[ TName ]`

* `conversionApi: DowncastConversionApi`

  Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor.

<a id="event-insert">

### `insert( eventInfo, data, conversionApi )`

Fired for inserted nodes.

`insert` is a namespace for a class of events. Names of actually called events follow this pattern: `insert:name`. `name` is either `'$text'`, when [a text node](module_engine_model_text-ModelText.md) has been inserted, or [name](module_engine_model_element-ModelElement.md#member-name) of inserted element.

This way, the listeners can either listen to a general `insert` event or specific event (for example `insert:paragraph`).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L801)

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `data: DowncastDispatcherEventMap<TItem>[ TName ]`

  Additional information about the change.

* `conversionApi: DowncastConversionApi`

  Conversion interface to be used by callback, passed in the `DowncastDispatcher` constructor.

<a id="event-reduceChanges">

### `reduceChanges( eventInfo, data )`

Fired to enable reducing (transforming) changes buffered in the [`Differ`](module_engine_model_differ-Differ.md) before [`convertChanges()`](#function-convertChanges) will fire any conversion events.

For instance, a feature can replace selected [`DifferItem`](module_engine_model_differ-DifferItem.md)s with a `reinsert` entry to trigger reconversion of an element when e.g. its attribute has changes. The [\* `DowncastHelpers.elementToStructure()`](module_engine_conversion_downcasthelpers-DowncastHelpers.md#function-elementToStructure) helper is using this event to trigger reconversion of an element when the element, its attributes or direct children changed.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L726)

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `data: DowncastReduceChangesEventData`

<a id="event-remove">

### `remove( eventInfo, data, conversionApi )`

Fired for removed nodes.

`remove` is a namespace for a class of events. Names of actually called events follow this pattern: `remove:name`. `name` is either `'$text'`, when a [a text node](module_engine_model_text-ModelText.md) has been removed, or the [name](module_engine_model_element-ModelElement.md#member-name) of removed element.

This way, listeners can either listen to a general `remove` event or specific event (for example `remove:paragraph`).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L819)

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `data: DowncastDispatcherEventMap<TItem>[ TName ]`

  Additional information about the change.

* `conversionApi: DowncastConversionApi`

  Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor.

<a id="event-removeMarker">

### `removeMarker( eventInfo, data, conversionApi )`

Fired when a marker is removed from the model.

`removeMarker` is a namespace for a class of events. Names of actually called events follow this pattern: `removeMarker:markerName`. By specifying certain marker names, you can make the events even more gradual. For example, if markers are named `foo:abc`, `foo:bar`, then it is possible to listen to `removeMarker:foo` or `removeMarker:foo:abc` and `removeMarker:foo:bar` events.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L922)

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `data: DowncastDispatcherEventMap<TItem>[ TName ]`

  Additional information about the change.

* `conversionApi: DowncastConversionApi`

  Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor.

<a id="event-selection">

### `selection( eventInfo, data, conversionApi )`

Fired for [selection](module_engine_model_selection-ModelSelection.md) changes.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/conversion/downcastdispatcher.ts#L856)

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `data: DowncastDispatcherEventMap<TItem>[ TName ]`

* `conversionApi: DowncastConversionApi`

  Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor.

---

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