|
|
@@ -28,12 +28,8 @@ import modifySelection from './utils/modifyselection';
|
|
|
import getSelectedContent from './utils/getselectedcontent';
|
|
|
|
|
|
/**
|
|
|
- * Editor's data model class. Model defines all the data: both nodes that are attached to the roots of the
|
|
|
- * {@link module:engine/model/model~Model#document model document}, and also all detached nodes which has not been yet
|
|
|
- * added to the document.
|
|
|
- *
|
|
|
- * All those nodes are created and modified by the {@link module:engine/model/writer~Writer model writer}, which can be
|
|
|
- * accessed by using {@link module:engine/model/model~Model#change} or {@link module:engine/model/model~Model#enqueueChange} methods.
|
|
|
+ * Editor's data model. Read about the model in the
|
|
|
+ * {@glink framework/guides/architecture/editing-engine engine architecture guide}.
|
|
|
*
|
|
|
* @mixes module:utils/observablemixin~ObservableMixin
|
|
|
*/
|
|
|
@@ -146,8 +142,6 @@ export default class Model {
|
|
|
* return writer.createElement( 'img' );
|
|
|
* } );
|
|
|
*
|
|
|
- * When the outermost block is done the {@link #event:_change} event is fired.
|
|
|
- *
|
|
|
* @see #enqueueChange
|
|
|
* @param {Function} callback Callback function which may modify the model.
|
|
|
* @returns {*} Value returned by the callback.
|
|
|
@@ -165,7 +159,7 @@ export default class Model {
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * `enqueueChange` method performs similar task as the {@link #change change method}, with two major differences.
|
|
|
+ * The `enqueueChange()` method performs similar task as the {@link #change `change()` method}, with two major differences.
|
|
|
*
|
|
|
* First, the callback of the `enqueueChange` is executed when all other changes are done. It might be executed
|
|
|
* immediately if it is not nested in any other change block, but if it is nested in another (enqueue)change block,
|
|
|
@@ -243,20 +237,22 @@ export default class Model {
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * See {@link module:engine/model/utils/insertcontent~insertContent}.
|
|
|
+ * Inserts content into the editor (specified selection) as one would expect the paste
|
|
|
+ * functionality to work.
|
|
|
*
|
|
|
* @fires insertContent
|
|
|
* @param {module:engine/model/documentfragment~DocumentFragment|module:engine/model/item~Item} content The content to insert.
|
|
|
- * @param {module:engine/model/selection~Selection} selection Selection into which the content should be inserted.
|
|
|
+ * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
|
|
|
+ * Selection into which the content should be inserted.
|
|
|
*/
|
|
|
insertContent( content, selection ) {
|
|
|
insertContent( this, content, selection );
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * See {@link module:engine/model/utils/deletecontent.deleteContent}.
|
|
|
+ * Deletes content of the selection and merge siblings. The resulting selection is always collapsed.
|
|
|
*
|
|
|
- * Note: For the sake of predictability, the resulting selection should always be collapsed.
|
|
|
+ * **Note:** For the sake of predictability, the resulting selection should always be collapsed.
|
|
|
* In cases where a feature wants to modify deleting behavior so selection isn't collapsed
|
|
|
* (e.g. a table feature may want to keep row selection after pressing <kbd>Backspace</kbd>),
|
|
|
* then that behavior should be implemented in the view's listener. At the same time, the table feature
|
|
|
@@ -265,30 +261,84 @@ export default class Model {
|
|
|
* That needs to be done in order to ensure that other features which use `deleteContent()` will work well with tables.
|
|
|
*
|
|
|
* @fires deleteContent
|
|
|
- * @param {module:engine/model/selection~Selection} selection Selection of which the content should be deleted.
|
|
|
- * @param {Object} options See {@link module:engine/model/utils/deletecontent~deleteContent}'s options.
|
|
|
+ * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
|
|
|
+ * Selection of which the content should be deleted.
|
|
|
+ * @param {module:engine/model/batch~Batch} batch Batch to which the deltas will be added.
|
|
|
+ * @param {Object} [options]
|
|
|
+ * @param {Boolean} [options.leaveUnmerged=false] Whether to merge elements after removing the content of the selection.
|
|
|
+ *
|
|
|
+ * For example `<heading>x[x</heading><paragraph>y]y</paragraph>` will become:
|
|
|
+ *
|
|
|
+ * * `<heading>x^y</heading>` with the option disabled (`leaveUnmerged == false`)
|
|
|
+ * * `<heading>x^</heading><paragraph>y</paragraph>` with enabled (`leaveUnmerged == true`).
|
|
|
+ *
|
|
|
+ * Note: {@link module:engine/model/schema~Schema#isObject object} and {@link module:engine/model/schema~Schema#isLimit limit}
|
|
|
+ * elements will not be merged.
|
|
|
+ *
|
|
|
+ * @param {Boolean} [options.doNotResetEntireContent=false] Whether to skip replacing the entire content with a
|
|
|
+ * paragraph when the entire content was selected.
|
|
|
+ *
|
|
|
+ * For example `<heading>[x</heading><paragraph>y]</paragraph>` will become:
|
|
|
+ *
|
|
|
+ * * `<paragraph>^</paragraph>` with the option disabled (`doNotResetEntireContent == false`)
|
|
|
+ * * `<heading>^</heading>` with enabled (`doNotResetEntireContent == true`)
|
|
|
*/
|
|
|
deleteContent( selection, options ) {
|
|
|
deleteContent( this, selection, options );
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * See {@link module:engine/model/utils/modifyselection~modifySelection}.
|
|
|
+ * Modifies the selection. Currently, the supported modifications are:
|
|
|
+ *
|
|
|
+ * * Extending. The selection focus is moved in the specified `options.direction` with a step specified in `options.unit`.
|
|
|
+ * Possible values for `unit` are:
|
|
|
+ * * `'character'` (default) - moves selection by one user-perceived character. In most cases this means moving by one
|
|
|
+ * character in `String` sense. However, unicode also defines "combing marks". These are special symbols, that combines
|
|
|
+ * with a symbol before it ("base character") to create one user-perceived character. For example, `q̣̇` is a normal
|
|
|
+ * letter `q` with two "combining marks": upper dot (`Ux0307`) and lower dot (`Ux0323`). For most actions, i.e. extending
|
|
|
+ * selection by one position, it is correct to include both "base character" and all of it's "combining marks". That is
|
|
|
+ * why `'character'` value is most natural and common method of modifying selection.
|
|
|
+ * * `'codePoint'` - moves selection by one unicode code point. In contrary to, `'character'` unit, this will insert
|
|
|
+ * selection between "base character" and "combining mark", because "combining marks" have their own unicode code points.
|
|
|
+ * However, for technical reasons, unicode code points with values above `UxFFFF` are represented in native `String` by
|
|
|
+ * two characters, called "surrogate pairs". Halves of "surrogate pairs" have a meaning only when placed next to each other.
|
|
|
+ * For example `𨭎` is represented in `String` by `\uD862\uDF4E`. Both `\uD862` and `\uDF4E` do not have any meaning
|
|
|
+ * outside the pair (are rendered as ? when alone). Position between them would be incorrect. In this case, selection
|
|
|
+ * extension will include whole "surrogate pair".
|
|
|
+ * * `'word'` - moves selection by a whole word.
|
|
|
+ *
|
|
|
+ * **Note:** if you extend a forward selection in a backward direction you will in fact shrink it.
|
|
|
*
|
|
|
* @fires modifySelection
|
|
|
- * @param {module:engine/model/selection~Selection} selection The selection to modify.
|
|
|
- * @param {Object} options See {@link module:engine/model/utils/modifyselection.modifySelection}'s options.
|
|
|
+ * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
|
|
|
+ * The selection to modify.
|
|
|
+ * @param {Object} [options]
|
|
|
+ * @param {'forward'|'backward'} [options.direction='forward'] The direction in which the selection should be modified.
|
|
|
+ * @param {'character'|'codePoint'|'word'} [options.unit='character'] The unit by which selection should be modified.
|
|
|
*/
|
|
|
modifySelection( selection, options ) {
|
|
|
modifySelection( this, selection, options );
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * See {@link module:engine/model/utils/getselectedcontent~getSelectedContent}.
|
|
|
+ * Gets a clone of the selected content.
|
|
|
+ *
|
|
|
+ * For example, for the following selection:
|
|
|
+ *
|
|
|
+ * ```html
|
|
|
+ * <p>x</p><quote><p>y</p><h>fir[st</h></quote><p>se]cond</p><p>z</p>
|
|
|
+ * ```
|
|
|
+ *
|
|
|
+ * It will return a document fragment with such a content:
|
|
|
+ *
|
|
|
+ * ```html
|
|
|
+ * <quote><h>st</h></quote><p>se</p>
|
|
|
+ * ```
|
|
|
*
|
|
|
* @fires getSelectedContent
|
|
|
- * @param {module:engine/model/selection~Selection} selection The selection of which content will be retrieved.
|
|
|
- * @returns {module:engine/model/documentfragment~DocumentFragment} Document fragment holding the clone of the selected content.
|
|
|
+ * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
|
|
|
+ * The selection of which content will be returned.
|
|
|
+ * @returns {module:engine/model/documentfragment~DocumentFragment}
|
|
|
*/
|
|
|
getSelectedContent( selection ) {
|
|
|
return getSelectedContent( this, selection );
|