|
|
@@ -18,6 +18,11 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
|
|
|
import DocumentFragment from './documentfragment';
|
|
|
import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
|
|
|
|
|
|
+/**
|
|
|
+ * View writer class. Provides set of methods used to properly manipulate nodes attached to
|
|
|
+ * {@link module:engine/view/document~Document view document}. To get an instance of view writer associated with
|
|
|
+ * the document use {@link module:engine/view/view~View#change view.change()) method.
|
|
|
+ */
|
|
|
export default class Writer {
|
|
|
/**
|
|
|
* Breaks attribute nodes at provided position or at boundaries of provided range. It breaks attribute elements inside
|
|
|
@@ -32,8 +37,8 @@ export default class Writer {
|
|
|
*
|
|
|
* **Note:** {@link module:engine/view/documentfragment~DocumentFragment DocumentFragment} is treated like a container.
|
|
|
*
|
|
|
- * **Note:** Difference between {@link module:engine/view/writer~writer.breakAttributes breakAttributes} and
|
|
|
- * {@link module:engine/view/writer~writer.breakContainer breakContainer} is that `breakAttributes` breaks all
|
|
|
+ * **Note:** Difference between {@link module:engine/view/writer~Writer#breakAttributes breakAttributes} and
|
|
|
+ * {@link module:engine/view/writer~Writer#breakContainer breakContainer} is that `breakAttributes` breaks all
|
|
|
* {@link module:engine/view/attributeelement~AttributeElement attribute elements} that are ancestors of given `position`,
|
|
|
* up to the first encountered {@link module:engine/view/containerelement~ContainerElement container element}.
|
|
|
* `breakContainer` assumes that given `position` is directly in container element and breaks that container element.
|
|
|
@@ -52,8 +57,7 @@ export default class Writer {
|
|
|
*
|
|
|
* @see module:engine/view/attributeelement~AttributeElement
|
|
|
* @see module:engine/view/containerelement~ContainerElement
|
|
|
- * @see module:engine/view/writer~writer.breakContainer
|
|
|
- * @function module:engine/view/writer~writer.breakAttributes
|
|
|
+ * @see module:engine/view/writer~Writer#breakContainer
|
|
|
* @param {module:engine/view/position~Position|module:engine/view/range~Range} positionOrRange Position where
|
|
|
* to break attribute elements.
|
|
|
* @returns {module:engine/view/position~Position|module:engine/view/range~Range} New position or range, after breaking the attribute
|
|
|
@@ -77,16 +81,15 @@ export default class Writer {
|
|
|
* <p>^foobar</p> -> ^<p>foobar</p>
|
|
|
* <p>foobar^</p> -> <p>foobar</p>^
|
|
|
*
|
|
|
- * **Note:** Difference between {@link module:engine/view/writer~writer.breakAttributes breakAttributes} and
|
|
|
- * {@link module:engine/view/writer~writer.breakContainer breakContainer} is that `breakAttributes` breaks all
|
|
|
+ * **Note:** Difference between {@link module:engine/view/writer~Writer#breakAttributes breakAttributes} and
|
|
|
+ * {@link module:engine/view/writer~Writer#breakContainer breakContainer} is that `breakAttributes` breaks all
|
|
|
* {@link module:engine/view/attributeelement~AttributeElement attribute elements} that are ancestors of given `position`,
|
|
|
* up to the first encountered {@link module:engine/view/containerelement~ContainerElement container element}.
|
|
|
* `breakContainer` assumes that given `position` is directly in container element and breaks that container element.
|
|
|
*
|
|
|
* @see module:engine/view/attributeelement~AttributeElement
|
|
|
* @see module:engine/view/containerelement~ContainerElement
|
|
|
- * @see module:engine/view/writer~writer.breakAttributes
|
|
|
- * @function module:engine/view/writer~writer.breakContainer
|
|
|
+ * @see module:engine/view/writer~Writer#breakAttributes
|
|
|
* @param {module:engine/view/position~Position} position Position where to break element.
|
|
|
* @returns {module:engine/view/position~Position} Position between broken elements. If element has not been broken,
|
|
|
* the returned position is placed either before it or after it.
|
|
|
@@ -145,15 +148,14 @@ export default class Writer {
|
|
|
* <p><b>[]</b></p> -> <p>[]</p>
|
|
|
* <p><b>foo</b><i>[]</i><b>bar</b></p> -> <p><b>foo{}bar</b></p>
|
|
|
*
|
|
|
- * **Note:** Difference between {@link module:engine/view/writer~writer.mergeAttributes mergeAttributes} and
|
|
|
- * {@link module:engine/view/writer~writer.mergeContainers mergeContainers} is that `mergeAttributes` merges two
|
|
|
+ * **Note:** Difference between {@link module:engine/view/writer~Writer#mergeAttributes mergeAttributes} and
|
|
|
+ * {@link module:engine/view/writer~Writer#mergeContainers mergeContainers} is that `mergeAttributes` merges two
|
|
|
* {@link module:engine/view/attributeelement~AttributeElement attribute elements} or {@link module:engine/view/text~Text text nodes}
|
|
|
* while `mergeContainer` merges two {@link module:engine/view/containerelement~ContainerElement container elements}.
|
|
|
*
|
|
|
* @see module:engine/view/attributeelement~AttributeElement
|
|
|
* @see module:engine/view/containerelement~ContainerElement
|
|
|
- * @see module:engine/view/writer~writer.mergeContainers
|
|
|
- * @function module:engine/view/writer~writer.mergeAttributes
|
|
|
+ * @see module:engine/view/writer~Writer#mergeContainers
|
|
|
* @param {module:engine/view/position~Position} position Merge position.
|
|
|
* @returns {module:engine/view/position~Position} Position after merge.
|
|
|
*/
|
|
|
@@ -209,15 +211,14 @@ export default class Writer {
|
|
|
* <p>foo</p>^<p>bar</p> -> <p>foo^bar</p>
|
|
|
* <div>foo</div>^<p>bar</p> -> <div>foo^bar</div>
|
|
|
*
|
|
|
- * **Note:** Difference between {@link module:engine/view/writer~writer.mergeAttributes mergeAttributes} and
|
|
|
- * {@link module:engine/view/writer~writer.mergeContainers mergeContainers} is that `mergeAttributes` merges two
|
|
|
+ * **Note:** Difference between {@link module:engine/view/writer~Writer#mergeAttributes mergeAttributes} and
|
|
|
+ * {@link module:engine/view/writer~Writer#mergeContainers mergeContainers} is that `mergeAttributes` merges two
|
|
|
* {@link module:engine/view/attributeelement~AttributeElement attribute elements} or {@link module:engine/view/text~Text text nodes}
|
|
|
* while `mergeContainer` merges two {@link module:engine/view/containerelement~ContainerElement container elements}.
|
|
|
*
|
|
|
* @see module:engine/view/attributeelement~AttributeElement
|
|
|
* @see module:engine/view/containerelement~ContainerElement
|
|
|
- * @see module:engine/view/writer~writer.mergeAttributes
|
|
|
- * @function module:engine/view/writer~writer.mergeContainers
|
|
|
+ * @see module:engine/view/writer~Writer#mergeAttributes
|
|
|
* @param {module:engine/view/position~Position} position Merge position.
|
|
|
* @returns {module:engine/view/position~Position} Position after merge.
|
|
|
*/
|
|
|
@@ -255,7 +256,6 @@ export default class Writer {
|
|
|
* {@link module:engine/view/emptyelement~EmptyElement EmptyElements} or
|
|
|
* {@link module:engine/view/uielement~UIElement UIElements}.
|
|
|
*
|
|
|
- * @function insert
|
|
|
* @param {module:engine/view/position~Position} position Insertion position.
|
|
|
* @param {module:engine/view/text~Text|module:engine/view/attributeelement~AttributeElement|
|
|
|
* module:engine/view/containerelement~ContainerElement|module:engine/view/emptyelement~EmptyElement|
|
|
|
@@ -309,7 +309,6 @@ export default class Writer {
|
|
|
* {@link module:engine/view/range~Range#start start} and {@link module:engine/view/range~Range#end end} positions are not placed inside
|
|
|
* same parent container.
|
|
|
*
|
|
|
- * @function module:engine/view/writer~writer.remove
|
|
|
* @param {module:engine/view/range~Range} range Range to remove from container. After removing, it will be updated
|
|
|
* to a collapsed range showing the new position.
|
|
|
* @returns {module:engine/view/documentfragment~DocumentFragment} Document fragment containing removed nodes.
|
|
|
@@ -347,7 +346,6 @@ export default class Writer {
|
|
|
* {@link module:engine/view/range~Range#start start} and {@link module:engine/view/range~Range#end end} positions are not placed inside
|
|
|
* same parent container.
|
|
|
*
|
|
|
- * @function module:engine/view/writer~writer.clear
|
|
|
* @param {module:engine/view/range~Range} range Range to clear.
|
|
|
* @param {module:engine/view/element~Element} element Element to remove.
|
|
|
*/
|
|
|
@@ -407,7 +405,6 @@ export default class Writer {
|
|
|
* {@link module:engine/view/range~Range#start start} and {@link module:engine/view/range~Range#end end} positions are not placed inside
|
|
|
* same parent container.
|
|
|
*
|
|
|
- * @function module:engine/view/writer~writer.move
|
|
|
* @param {module:engine/view/range~Range} sourceRange Range containing nodes to move.
|
|
|
* @param {module:engine/view/position~Position} targetPosition Position to insert.
|
|
|
* @returns {module:engine/view/range~Range} Range in target container. Inserted nodes are placed between
|
|
|
@@ -447,7 +444,6 @@ export default class Writer {
|
|
|
* Throws {@link module:utils/ckeditorerror~CKEditorError} `view-writer-wrap-invalid-attribute` when passed attribute element is not
|
|
|
* an instance of {module:engine/view/attributeelement~AttributeElement AttributeElement}.
|
|
|
*
|
|
|
- * @function module:engine/view/writer~writer.wrap
|
|
|
* @param {module:engine/view/range~Range} range Range to wrap.
|
|
|
* @param {module:engine/view/attributeelement~AttributeElement} attribute Attribute element to use as wrapper.
|
|
|
* @param {module:engine/view/selection~Selection} [viewSelection=null] View selection to change, required when
|
|
|
@@ -771,7 +767,7 @@ export default class Writer {
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * Helper function for `view.writer.wrap`. Wraps position with provided attribute element.
|
|
|
+ * Helper function for {@link #wrap}. Wraps position with provided attribute element.
|
|
|
* This method will also merge newly added attribute element with its siblings whenever possible.
|
|
|
*
|
|
|
* Throws {@link module:utils/ckeditorerror~CKEditorError} `view-writer-wrap-invalid-attribute` when passed attribute element is not
|