|
|
@@ -14,84 +14,84 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
|
|
|
import { extend } from 'lodash-es';
|
|
|
|
|
|
/**
|
|
|
- * `DowncastDispatcher` is a central point of downcasting (conversion from model to view), which is a process of reacting to changes
|
|
|
- * in the model and firing a set of events. Callbacks listening to those events are called converters. Those
|
|
|
- * converters role is to convert the model changes to changes in view (for example, adding view nodes or
|
|
|
+ * 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. 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 conversion process, `DowncastDispatcher` fires events, basing on state of the model and prepares
|
|
|
- * data for those events. It is important to understand that those events are connected with changes done on model,
|
|
|
- * for example: "node has been inserted" or "attribute has changed". This is in a contrary to upcasting (view to model conversion),
|
|
|
- * where we convert view state (view nodes) to a model tree.
|
|
|
+ * 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 {@link module:engine/model/differ~Differ Differ}, which buffers them
|
|
|
- * and then passes to `DowncastDispatcher` as a diff between old model state and new model state.
|
|
|
+ * and then passes to the downcast dispatcher as a diff between the old model state and the new model state.
|
|
|
*
|
|
|
- * Note, that because changes are converted there is a need to have a mapping between model structure and view structure.
|
|
|
- * To map positions and elements during downcast (model to view conversion) use {@link module:engine/conversion/mapper~Mapper}.
|
|
|
+ * 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 {@link module:engine/conversion/mapper~Mapper}.
|
|
|
*
|
|
|
- * `DowncastDispatcher` fires following events for model tree changes:
|
|
|
+ * Downcast dispatcher fires the following events for model tree changes:
|
|
|
*
|
|
|
- * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert insert}
|
|
|
- * if a range of nodes has been inserted to the model tree,
|
|
|
- * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:remove remove}
|
|
|
- * if a range of nodes has been removed from the model tree,
|
|
|
- * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute attribute}
|
|
|
- * if attribute has been added, changed or removed from a model node.
|
|
|
+ * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert `insert`} –
|
|
|
+ * If a range of nodes was inserted to the model tree.
|
|
|
+ * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:remove `remove`} –
|
|
|
+ * If a range of nodes was removed from the model tree.
|
|
|
+ * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute `attribute`} –
|
|
|
+ * If an attribute was added, changed or removed from a model node.
|
|
|
*
|
|
|
- * For {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert insert}
|
|
|
- * and {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute attribute},
|
|
|
- * `DowncastDispatcher` generates {@link module:engine/conversion/modelconsumable~ModelConsumable consumables}.
|
|
|
- * These are used to have a control over which changes has been already consumed. It is useful when some converters
|
|
|
- * overwrite other or converts multiple changes (for example converts insertion of an element and also converts that
|
|
|
- * element's attributes during insertion).
|
|
|
+ * For {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert `insert`}
|
|
|
+ * and {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute `attribute`},
|
|
|
+ * downcast dispatcher generates {@link module:engine/conversion/modelconsumable~ModelConsumable consumables}.
|
|
|
+ * 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, `DowncastDispatcher` fires events for {@link module:engine/model/markercollection~Marker marker} changes:
|
|
|
+ * Additionally, downcast dispatcher fires events for {@link module:engine/model/markercollection~Marker marker} changes:
|
|
|
*
|
|
|
- * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker} if a marker has been added,
|
|
|
- * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:removeMarker} if a marker has been removed.
|
|
|
+ * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker} – If a marker was added.
|
|
|
+ * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:removeMarker} – If a marker was removed.
|
|
|
*
|
|
|
- * Note, that changing a marker is done through removing the marker from the old range, and adding on the new range,
|
|
|
- * so both those events are fired.
|
|
|
+ * Note that changing a marker is done through removing the marker from the old range and adding it on the new range,
|
|
|
+ * so both events are fired.
|
|
|
*
|
|
|
- * Finally, `DowncastDispatcher` also handles firing events for {@link module:engine/model/selection model selection}
|
|
|
+ * Finally, downcast dispatcher also handles firing events for the {@link module:engine/model/selection model selection}
|
|
|
* conversion:
|
|
|
*
|
|
|
* * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:selection}
|
|
|
- * which converts selection from model to view,
|
|
|
+ * – Converts the selection from the model to the view.
|
|
|
* * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute}
|
|
|
- * which is fired for every selection attribute,
|
|
|
+ * – Fired for every selection attribute.
|
|
|
* * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker}
|
|
|
- * which is fired for every marker which contains selection.
|
|
|
+ * – Fired for every marker that contains a selection.
|
|
|
*
|
|
|
* Unlike model tree and markers, events for selection are not fired for changes but for selection state.
|
|
|
*
|
|
|
- * When providing custom listeners for `DowncastDispatcher` remember to check whether given change has not been
|
|
|
+ * When providing custom listeners for downcast dispatcher, remember to check whether a given change has not been
|
|
|
* {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed} yet.
|
|
|
*
|
|
|
- * When providing custom listeners for `DowncastDispatcher` keep in mind that any callback that had
|
|
|
+ * When providing custom listeners for downcast dispatcher, keep in mind that any callback that has
|
|
|
* {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed} a value from a consumable and
|
|
|
* converted the change should also stop the event (for efficiency purposes).
|
|
|
*
|
|
|
- * When providing custom listeners for `DowncastDispatcher` remember to use provided
|
|
|
+ * When providing custom listeners for downcast dispatcher, remember to use the provided
|
|
|
* {@link module:engine/view/downcastwriter~DowncastWriter view downcast writer} to apply changes to the view document.
|
|
|
*
|
|
|
- * Example of a custom converter for `DowncastDispatcher`:
|
|
|
+ * An example of a custom converter for the downcast dispatcher:
|
|
|
*
|
|
|
- * // We will convert inserting "paragraph" model element into the model.
|
|
|
+ * // 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 position in model to position in view.
|
|
|
+ * // Translate the position in the model to a position in the view.
|
|
|
* const viewPosition = conversionApi.mapper.toViewPosition( data.range.start );
|
|
|
*
|
|
|
- * // Create <p> element that will be inserted in view at `viewPosition`.
|
|
|
+ * // 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 model element so positions will map accordingly in future.
|
|
|
+ * // 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.
|
|
|
@@ -103,15 +103,15 @@ import { extend } from 'lodash-es';
|
|
|
*/
|
|
|
export default class DowncastDispatcher {
|
|
|
/**
|
|
|
- * Creates a `DowncastDispatcher` instance.
|
|
|
+ * Creates a downcast dispatcher instance.
|
|
|
*
|
|
|
* @see module:engine/conversion/downcastdispatcher~DowncastConversionApi
|
|
|
- * @param {Object} conversionApi Additional properties for interface that will be passed to events fired
|
|
|
- * by `DowncastDispatcher`.
|
|
|
+ * @param {Object} conversionApi Additional properties for an interface that will be passed to events fired
|
|
|
+ * by the downcast dispatcher.
|
|
|
*/
|
|
|
constructor( conversionApi ) {
|
|
|
/**
|
|
|
- * Interface passed by dispatcher to the events callbacks.
|
|
|
+ * An interface passed by the dispatcher to the event callbacks.
|
|
|
*
|
|
|
* @member {module:engine/conversion/downcastdispatcher~DowncastConversionApi}
|
|
|
*/
|
|
|
@@ -119,11 +119,11 @@ export default class DowncastDispatcher {
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * Takes {@link module:engine/model/differ~Differ model differ} object with buffered changes and fires conversion basing on it.
|
|
|
+ * Takes a {@link module:engine/model/differ~Differ model differ} object with buffered changes and fires conversion basing on it.
|
|
|
*
|
|
|
- * @param {module:engine/model/differ~Differ} differ Differ object with buffered changes.
|
|
|
- * @param {module:engine/model/markercollection~MarkerCollection} markers Markers connected with converted model.
|
|
|
- * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
|
|
|
+ * @param {module:engine/model/differ~Differ} differ The differ object with buffered changes.
|
|
|
+ * @param {module:engine/model/markercollection~MarkerCollection} markers Markers connected with the converted model.
|
|
|
+ * @param {module:engine/view/downcastwriter~DowncastWriter} writer The view writer that should be used to modify the view document.
|
|
|
*/
|
|
|
convertChanges( differ, markers, writer ) {
|
|
|
// Before the view is updated, remove markers which have changed.
|
|
|
@@ -157,15 +157,15 @@ export default class DowncastDispatcher {
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * Starts conversion of a range insertion.
|
|
|
+ * Starts a conversion of a range insertion.
|
|
|
*
|
|
|
- * For each node in the range, {@link #event:insert insert event is fired}. For each attribute on each node,
|
|
|
- * {@link #event:attribute attribute event is fired}.
|
|
|
+ * For each node in the range, {@link #event:insert `insert` event is fired}. For each attribute on each node,
|
|
|
+ * {@link #event:attribute `attribute` event is fired}.
|
|
|
*
|
|
|
* @fires insert
|
|
|
* @fires attribute
|
|
|
- * @param {module:engine/model/range~Range} range Inserted range.
|
|
|
- * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
|
|
|
+ * @param {module:engine/model/range~Range} range The inserted range.
|
|
|
+ * @param {module:engine/view/downcastwriter~DowncastWriter} writer The view writer that should be used to modify the view document.
|
|
|
*/
|
|
|
convertInsert( range, writer ) {
|
|
|
this.conversionApi.writer = writer;
|
|
|
@@ -554,7 +554,7 @@ export default class DowncastDispatcher {
|
|
|
*/
|
|
|
|
|
|
/**
|
|
|
- * Fired when a new marker is added to the model. Also fired when collapsed model selection that is inside marker is converted.
|
|
|
+ * Fired when a new marker is added to the model. Also fired when 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,
|
|
|
@@ -634,7 +634,7 @@ function shouldMarkerChangeBeConverted( modelPosition, marker, mapper ) {
|
|
|
/**
|
|
|
* Conversion interface that is registered for given {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}
|
|
|
* and is passed as one of parameters when {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher dispatcher}
|
|
|
- * fires it's events.
|
|
|
+ * fires its events.
|
|
|
*
|
|
|
* @interface module:engine/conversion/downcastdispatcher~DowncastConversionApi
|
|
|
*/
|