8
0
Oskar Wróbel 7 лет назад
Родитель
Сommit
b7ff7027dd

+ 14 - 3
packages/ckeditor5-engine/src/model/documentselection.js

@@ -139,6 +139,12 @@ export default class DocumentSelection {
 		return this._selection.isBackward;
 	}
 
+	/**
+	 * Describes whether gravity is overridden (using {@link ~DocumentSelection#_overrideGravity}) or not.
+	 *
+	 * @readonly
+	 * @return {boolean}
+	 */
 	get isGravityOverridden() {
 		return this._selection._isGravityOverriden;
 	}
@@ -393,18 +399,23 @@ export default class DocumentSelection {
 	}
 
 	/**
-	 * Temporarily and partially disables default gravity behaviour that tries to get attributes from nodes surrounding the caret.
+	 * Temporarily changes the gravity of the selection from left to right. The gravity defines from which direction
+	 * the selection inherits its attributes. If it's the default left gravity, the selection (after being moved by
+	 * the user) inherits attributes from its left hand side. This method allows to temporarily override this behavior
+	 * by forcing the gravity to the right.
 	 *
 	 * @see module:engine/model/writer~Writer#overrideSelectionGravity
 	 * @protected
-	 * @param {Boolean} [customRestore=false] When `true` then gravity won't be restored automatically.
+	 * @param {Boolean} [customRestore=false] When `true` then gravity won't be restored until
+	 * {@link ~DocumentSelection#_restoreGravity} will be called directly. When `false` then gravity is restored
+	 * after selection is moved by user.
 	 */
 	_overrideGravity( customRestore ) {
 		this._selection.overrideGravity( customRestore );
 	}
 
 	/**
-	 * Restore overridden gravity.
+	 * Restores {@link ~DocumentSelection#_overrideGravity overridden gravity}.
 	 *
 	 * @see module:engine/model/writer~Writer#restoreSelectionGravity
 	 * @protected

+ 12 - 9
packages/ckeditor5-engine/src/model/writer.js

@@ -1017,29 +1017,32 @@ export default class Writer {
 	}
 
 	/**
-	 * Disables default gravity behaviour that tries to get attributes from nodes surrounding the caret. When gravity is
-	 * marked as overridden then attributes from the node before the caret won't be taken into consideration while
-	 * updating selection attributes.
+	 * Temporarily changes the gravity of the selection from left to right. The gravity defines from which direction
+	 * the selection inherits its attributes. If it's the default left gravity, the selection (after being moved by
+	 * the user) inherits attributes from its left hand side. This method allows to temporarily override this behavior
+	 * by forcing the gravity to the right.
 	 *
 	 * For the following model fragment:
 	 *
 	 * 		<$text bold="true" linkHref="url">bar[]</$text><$text bold="true">biz</$text>
 	 *
-	 * Selection attribute keys before override will be equal `[ 'bold', 'linkHref' ]`
-	 * Selection attribute keys after override will be equal `[ 'bold' ]`
+	 * Default gravity: selection will have the `bold` and `linkHref` attributes.
+	 * Overridden gravity: selection will have `bold` attribute.
 	 *
-	 * As default gravity is automatically restored just after a direct selection change event but this behaviour
-	 * can be disabled by passing `true` flag as param.
+	 * By default the selection's gravity is automatically restored just after a direct selection change (when user
+	 * move caret) but you can pass customRestore = true in which case you will have to call
+	 * {@link ~Writer#restoreSelectionGravity} manually.
 	 *
 	 * @param {Boolean} [customRestore=false] When `true` then gravity won't be restored until
-	 * {@link ~Writer#overrideSelectionGravity} will be called directly.
+	 * {@link ~Writer#restoreSelectionGravity} will be called directly. When `false` then gravity is restored
+	 * after selection is moved by user.
 	 */
 	overrideSelectionGravity( customRestore ) {
 		this.model.document.selection._overrideGravity( customRestore );
 	}
 
 	/**
-	 * Restore overridden gravity to default.
+	 * Restores overridden gravity to default.
 	 */
 	restoreSelectionGravity() {
 		this.model.document.selection._restoreGravity();

+ 4 - 4
packages/ckeditor5-engine/src/utils/bindtwostepcarettoattribute.js

@@ -71,7 +71,7 @@ export default function bindTwoStepCaretToAttribute( view, model, emitter, attri
 
 			// If caret sticks to the bound of Text with attribute it means that we are going to
 			// enter `foo{}<a>bar</a>biz` or leave `foo<a>bar{}</a>biz` the text with attribute.
-			if ( isStickToAttribute( position.nodeAfter, position.nodeBefore, attribute ) ) {
+			if ( isAtAttributeBoundary( position.nodeAfter, position.nodeBefore, attribute ) ) {
 				// So we need to prevent caret from being moved.
 				data.preventDefault();
 				// And override default selection gravity.
@@ -82,7 +82,7 @@ export default function bindTwoStepCaretToAttribute( view, model, emitter, attri
 		} else {
 			// If caret sticks to the bound of Text with attribute and gravity is already overridden it means that
 			// we are going to enter `foo<a>bar</a>{}biz` or leave `foo<a>{}bar</a>biz` text with attribute.
-			if ( modelSelection.isGravityOverridden && isStickToAttribute( position.nodeBefore, position.nodeAfter, attribute ) ) {
+			if ( modelSelection.isGravityOverridden && isAtAttributeBoundary( position.nodeBefore, position.nodeAfter, attribute ) ) {
 				// So we need to prevent cater from being moved.
 				data.preventDefault();
 				// And restore the gravity.
@@ -103,7 +103,7 @@ export default function bindTwoStepCaretToAttribute( view, model, emitter, attri
 			// When caret is going stick to the bound of Text with attribute after movement then we need to override
 			// the gravity before the move. But we need to do it in a custom way otherwise `selection#change:range`
 			// event following the overriding will restore the gravity.
-			if ( isStickToAttribute( nextPosition.nodeBefore, nextPosition.nodeAfter, attribute ) ) {
+			if ( isAtAttributeBoundary( nextPosition.nodeBefore, nextPosition.nodeAfter, attribute ) ) {
 				model.change( writer => {
 					let counter = 0;
 
@@ -127,7 +127,7 @@ export default function bindTwoStepCaretToAttribute( view, model, emitter, attri
 // @param {module:engine/model/node~Node} prevNode Node after the position.
 // @param {String} attribute Attribute name.
 // @returns {Boolean} `true` when position between the nodes sticks to the bound of text with given attribute.
-function isStickToAttribute( nextNode, prevNode, attribute ) {
+function isAtAttributeBoundary( nextNode, prevNode, attribute ) {
 	const isAttrInNext = nextNode ? nextNode.hasAttribute( attribute ) : false;
 	const isAttrInPrev = prevNode ? prevNode.hasAttribute( attribute ) : false;