8
0
Szymon Kupś vor 7 Jahren
Ursprung
Commit
946d81bdd5

+ 1 - 1
packages/ckeditor5-engine/src/conversion/buildmodelconverter.js

@@ -178,7 +178,7 @@ class ModelConverterBuilder {
 	 * Default priority is `10`.
 	 *
 	 * **Note:** Keep in mind that event priority, that is set by this modifier, is used for attribute priority
-	 * when {@link module:engine/view/writer~writer} is used. This changes how view elements are ordered,
+	 * when {@link module:engine/view/writer~Writer} is used. This changes how view elements are ordered,
 	 * i.e.: `<strong><em>foo</em></strong>` vs `<em><strong>foo</strong></em>`. Using priority you can also
 	 * prevent node merging, i.e.: `<span class="bold"><span class="theme">foo</span><span>` vs `<span class="bold theme">foo</span>`.
 	 * If you want to prevent merging, just set different priority for both converters.

+ 1 - 1
packages/ckeditor5-engine/src/model/utils/insertcontent.js

@@ -165,9 +165,9 @@ class Insertion {
 	}
 
 	/**
-	 * @private
 	 * Handles insertion of a single node.
 	 *
+	 * @private
 	 * @param {module:engine/model/node~Node} node
 	 * @param {Object} context
 	 * @param {Boolean} context.isFirst Whether the given node is the first one in the content to be inserted.

+ 1 - 1
packages/ckeditor5-engine/src/view/attributeelement.js

@@ -14,7 +14,7 @@ const DEFAULT_PRIORITY = 10;
 
 /**
  * Attributes are elements which define document presentation. They are mostly elements like `<b>` or `<span>`.
- * Attributes can be broken and merged by the {@link module:engine/view/writer~writer view writer}.
+ * Attributes can be broken and merged by the {@link module:engine/view/writer~Writer view writer}.
  *
  * Editing engine does not define fixed HTML DTD. This is why the type of the {@link module:engine/view/element~Element} need to
  * be defined by the feature developer. Creating an element you should use {@link module:engine/view/containerelement~ContainerElement}

+ 3 - 3
packages/ckeditor5-engine/src/view/containerelement.js

@@ -23,8 +23,8 @@ import Element from './element';
  * DOM properly. {@link module:engine/view/domconverter~DomConverter} will ensure that `ContainerElement` is editable and it is possible
  * to put caret inside it, even if the container is empty.
  *
- * Secondly, {@link module:engine/view/writer~writer view writer} uses this information.
- * Nodes {@link module:engine/view/writer~writer.breakAttributes breaking} and {@link module:engine/view/writer~writer.mergeAttributes
+ * Secondly, {@link module:engine/view/writer~Writer view writer} uses this information.
+ * Nodes {@link module:engine/view/writer~Writer#breakAttributes breaking} and {@link module:engine/view/writer~Writer#mergeAttributes
  * merging}
  * is performed only in a bounds of a container nodes.
  *
@@ -32,7 +32,7 @@ import Element from './element';
  *
  *		<p><b>fo^o</b></p>
  *
- * {@link module:engine/view/writer~writer.breakAttributes breakAttributes} will create:
+ * {@link module:engine/view/writer~Writer#breakAttributes breakAttributes} will create:
  *
  *		<p><b>fo</b><b>o</b></p>
  *

+ 2 - 2
packages/ckeditor5-engine/src/view/editableelement.js

@@ -41,8 +41,8 @@ export default class EditableElement extends ContainerElement {
 		/**
 		 * Whether the editable is focused.
 		 *
-		 * This property updates when {@link module:engine/view/document~Document#isFocused document.isFocused} is changed and after each
-		 * {@link module:engine/view/document~Document#render render} method call.
+		 * This property updates when {@link module:engine/view/document~Document#isFocused document.isFocused} or view
+		 * selection is changed.
 		 *
 		 * @readonly
 		 * @observable

+ 1 - 1
packages/ckeditor5-engine/src/view/observer/domeventdata.js

@@ -16,7 +16,7 @@ import extend from '@ckeditor/ckeditor5-utils/src/lib/lodash/extend';
  */
 export default class DomEventData {
 	/**
-	 * @param {module:engine/view/view~view} view The instance of the view controller.
+	 * @param {module:engine/view/view~View} view The instance of the view controller.
 	 * @param {Event} domEvent The DOM event.
 	 * @param {Object} [additionalData] Additional properties that the instance should contain.
 	 */

+ 2 - 2
packages/ckeditor5-engine/src/view/observer/mutationobserver.js

@@ -48,14 +48,14 @@ export default class MutationObserver extends Observer {
 		};
 
 		/**
-		 * Reference to the {@link module:engine/view/document~Document#domConverter}.
+		 * Reference to the {@link module:engine/view/view~View#domConverter}.
 		 *
 		 * @member {module:engine/view/domconverter~DomConverter}
 		 */
 		this.domConverter = view.domConverter;
 
 		/**
-		 * Reference to the {@link module:engine/view/document~Document#renderer}.
+		 * Reference to the {@link module:engine/view/view~View#renderer}.
 		 *
 		 * @member {module:engine/view/renderer~Renderer}
 		 */

+ 35 - 35
packages/ckeditor5-engine/src/view/selection.js

@@ -21,7 +21,7 @@ import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
  * Class representing selection in tree view.
  *
  * Selection can consist of {@link module:engine/view/range~Range ranges} that can be set using
- * {@link module:engine/view/selection~Selection#setTo} method.
+ * {@link module:engine/view/selection~Selection#_setTo} method.
  * That method create copies of provided ranges and store those copies internally. Further modifications to passed
  * ranges will not change selection's state.
  * Selection's ranges can be obtained via {@link module:engine/view/selection~Selection#getRanges getRanges},
@@ -102,27 +102,6 @@ export default class Selection {
 	}
 
 	/**
-	 * Sets this selection instance to be marked as `fake`. A fake selection does not render as browser native selection
-	 * over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to
-	 * the user and selection over elements can be represented in other way, for example by applying proper CSS class.
-	 *
-	 * Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM (and be
-	 * properly handled by screen readers).
-	 *
-	 * @protected
-	 * @fires change
-	 * @param {Boolean} [value=true] If set to true selection will be marked as `fake`.
-	 * @param {Object} [options] Additional options.
-	 * @param {String} [options.label=''] Fake selection label.
-	 */
-	_setFake( value = true, options = {} ) {
-		this._isFake = value;
-		this._fakeSelectionLabel = value ? options.label || '' : '';
-
-		this.fire( 'change' );
-	}
-
-	/**
 	 * Returns true if selection instance is marked as `fake`.
 	 *
 	 * @see #_setFake
@@ -391,6 +370,25 @@ export default class Selection {
 	}
 
 	/**
+	 * Returns the selected element. {@link module:engine/view/element~Element Element} is considered as selected if there is only
+	 * one range in the selection, and that range contains exactly one element.
+	 * Returns `null` if there is no selected element.
+	 *
+	 * @returns {module:engine/view/element~Element|null}
+	 */
+	getSelectedElement() {
+		if ( this.rangeCount !== 1 ) {
+			return null;
+		}
+
+		const range = this.getFirstRange();
+		const nodeAfterStart = range.start.nodeAfter;
+		const nodeBeforeEnd = range.end.nodeBefore;
+
+		return ( nodeAfterStart instanceof Element && nodeAfterStart == nodeBeforeEnd ) ? nodeAfterStart : null;
+	}
+
+	/**
 	 * Removes all ranges that were added to the selection.
 	 *
 	 * @fires change
@@ -529,22 +527,24 @@ export default class Selection {
 	}
 
 	/**
-	 * Returns the selected element. {@link module:engine/view/element~Element Element} is considered as selected if there is only
-	 * one range in the selection, and that range contains exactly one element.
-	 * Returns `null` if there is no selected element.
+	 * Sets this selection instance to be marked as `fake`. A fake selection does not render as browser native selection
+	 * over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to
+	 * the user and selection over elements can be represented in other way, for example by applying proper CSS class.
 	 *
-	 * @returns {module:engine/view/element~Element|null}
+	 * Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM (and be
+	 * properly handled by screen readers).
+	 *
+	 * @protected
+	 * @fires change
+	 * @param {Boolean} [value=true] If set to true selection will be marked as `fake`.
+	 * @param {Object} [options] Additional options.
+	 * @param {String} [options.label=''] Fake selection label.
 	 */
-	getSelectedElement() {
-		if ( this.rangeCount !== 1 ) {
-			return null;
-		}
-
-		const range = this.getFirstRange();
-		const nodeAfterStart = range.start.nodeAfter;
-		const nodeBeforeEnd = range.end.nodeBefore;
+	_setFake( value = true, options = {} ) {
+		this._isFake = value;
+		this._fakeSelectionLabel = value ? options.label || '' : '';
 
-		return ( nodeAfterStart instanceof Element && nodeAfterStart == nodeBeforeEnd ) ? nodeAfterStart : null;
+		this.fire( 'change' );
 	}
 
 	/**

+ 37 - 25
packages/ckeditor5-engine/src/view/view.js

@@ -49,21 +49,17 @@ import { injectQuirksHandling } from './filler';
  */
 export default class View {
 	constructor() {
+		/**
+		 * Instance of the {@link module:engine/view/document~Document} associated with this view controller.
+		 *
+		 * @readonly
+		 * @member {module:engine/view/document~Document} module:engine/view/view~View#document
+		 */
 		this.document = new Document();
-		this._writer = new Writer( this.document );
-
-		// TODO: check docs
-		// TODO: move change event description to this file.
-		// TODO: check import path
-		// TODO: check where render() is used and eventually switch to change() where possible
-		// TODO: observers docs fixes
-		// TODO: check where writer instance is created and it should be returned by change() method only (converters!)
-		// TODO: manual tests
-		// TODO: placeholder - use change() block
 
 		/**
 		 * Instance of the {@link module:engine/view/domconverter~DomConverter domConverter} use by
-		 * {@link module:engine/view/document~Document#renderer renderer}
+		 * {@link module:engine/view/view~View#renderer renderer}
 		 * and {@link module:engine/view/observer/observer~Observer observers}.
 		 *
 		 * @readonly
@@ -72,7 +68,7 @@ export default class View {
 		this.domConverter = new DomConverter();
 
 		/**
-		 * Instance of the {@link module:engine/view/document~Document#renderer renderer}.
+		 * Instance of the {@link module:engine/view/renderer~Renderer renderer}.
 		 *
 		 * @readonly
 		 * @member {module:engine/view/renderer~Renderer} module:engine/view/view~View#renderer
@@ -96,16 +92,6 @@ export default class View {
 		 */
 		this._observers = new Map();
 
-		// Add default observers.
-		this.addObserver( MutationObserver );
-		this.addObserver( SelectionObserver );
-		this.addObserver( FocusObserver );
-		this.addObserver( KeyObserver );
-		this.addObserver( FakeSelectionObserver );
-
-		injectQuirksHandling( this );
-		injectUiElementHandling( this );
-
 		/**
 		 * Is set to `true` when {@link #change view changes} are currently in progress.
 		 *
@@ -121,6 +107,25 @@ export default class View {
 		 * @member {Boolean} module:engine/view/view~View#_renderingInProgress
 		 */
 		this._renderingInProgress = false;
+
+		/**
+		 * Writer instance used in {@link #change change method) callbacks.
+		 *
+		 * @private
+		 * @member {module:engine/view/writer~Writer} module:engine/view/view~View#_writer
+		 */
+		this._writer = new Writer( this.document );
+
+		// Add default observers.
+		this.addObserver( MutationObserver );
+		this.addObserver( SelectionObserver );
+		this.addObserver( FocusObserver );
+		this.addObserver( KeyObserver );
+		this.addObserver( FakeSelectionObserver );
+
+		// Inject quirks handlers.
+		injectQuirksHandling( this );
+		injectUiElementHandling( this );
 	}
 
 	/**
@@ -167,7 +172,7 @@ export default class View {
 	/**
 	 * Creates observer of the given type if not yet created, {@link module:engine/view/observer/observer~Observer#enable enables} it
 	 * and {@link module:engine/view/observer/observer~Observer#observe attaches} to all existing and future
-	 * {@link module:engine/view/document~Document#domRoots DOM roots}.
+	 * {@link #domRoots DOM roots}.
 	 *
 	 * Note: Observers are recognized by their constructor (classes). A single observer will be instantiated and used only
 	 * when registered for the first time. This means that features and other components can register a single observer
@@ -282,8 +287,8 @@ export default class View {
 	 *
 	 * Change block is executed immediately.
 	 *
-	 * When the outermost block is done and rendering to DOM is over it fires {@link module:engine/view/document~Document#change }
-	 * event.
+	 * When the outermost change block is done and rendering to DOM is over it fires
+	 * {@link module:engine/view/document~Document#event:change} event.
 	 *
 	 * @param {Function} callback Callback function which may modify the view.
 	 */
@@ -355,6 +360,13 @@ export default class View {
 
 		this._renderingInProgress = false;
 	}
+
+	/**
+	 * Fired after a topmost {@link module:engine/view/view~View#change change block} is finished and DOM rendering has
+	 * been executed.
+	 *
+	 * @event module:engine/view/document~Document#event:change
+	 */
 }
 
 mix( View, ObservableMixin );

+ 1 - 1
packages/ckeditor5-engine/src/view/writer.js

@@ -68,7 +68,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Moves {@link module:engine/view/selection~Selection selection's} {@link #focus} to the specified location.
+	 * Moves {@link module:engine/view/selection~Selection#focus selection's focus} to the specified location.
 	 *
 	 * The location can be specified in the same form as {@link module:engine/view/position~Position.createAt} parameters.
 	 *