@ckeditor/ckeditor5-engine 30.0.0

package/src/view/editableelement.js

@@ -0,0 +1,118 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/view/editableelement
+ */
+
+import ContainerElement from './containerelement';
+import mix from '@ckeditor/ckeditor5-utils/src/mix';
+import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
+
+/**
+ * Editable element which can be a {@link module:engine/view/rooteditableelement~RootEditableElement root}
+ * or nested editable area in the editor.
+ *
+ * Editable is automatically read-only when its {@link module:engine/view/document~Document Document} is read-only.
+ *
+ * The constructor of this class shouldn't be used directly. To create new `EditableElement` use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createEditableElement `downcastWriter#createEditableElement()`} method.
+ *
+ * @extends module:engine/view/containerelement~ContainerElement
+ * @mixes module:utils/observablemixin~ObservableMixin
+ */
+export default class EditableElement extends ContainerElement {
+	/**
+	 * Creates an editable element.
+	 *
+	 * @see module:engine/view/downcastwriter~DowncastWriter#createEditableElement
+	 * @protected
+	 */
+	constructor( document, name, attrs, children ) {
+		super( document, name, attrs, children );
+
+		/**
+		 * Whether the editable is in read-write or read-only mode.
+		 *
+		 * @observable
+		 * @member {Boolean} module:engine/view/editableelement~EditableElement#isReadOnly
+		 */
+		this.set( 'isReadOnly', false );
+
+		/**
+		 * Whether the editable is focused.
+		 *
+		 * This property updates when {@link module:engine/view/document~Document#isFocused document.isFocused} or view
+		 * selection is changed.
+		 *
+		 * @readonly
+		 * @observable
+		 * @member {Boolean} module:engine/view/editableelement~EditableElement#isFocused
+		 */
+		this.set( 'isFocused', false );
+
+		this.bind( 'isReadOnly' ).to( document );
+
+		this.bind( 'isFocused' ).to(
+			document,
+			'isFocused',
+			isFocused => isFocused && document.selection.editableElement == this
+		);
+
+		// Update focus state based on selection changes.
+		this.listenTo( document.selection, 'change', () => {
+			this.isFocused = document.isFocused && document.selection.editableElement == this;
+		} );
+	}
+
+	/**
+	 * Checks whether this object is of the given.
+	 *
+	 *		editableElement.is( 'editableElement' ); // -> true
+	 *		editableElement.is( 'element' ); // -> true
+	 *		editableElement.is( 'node' ); // -> true
+	 *		editableElement.is( 'view:editableElement' ); // -> true
+	 *		editableElement.is( 'view:element' ); // -> true
+	 *		editableElement.is( 'view:node' ); // -> true
+	 *
+	 *		editableElement.is( 'model:element' ); // -> false
+	 *		editableElement.is( 'documentFragment' ); // -> false
+	 *
+	 * Assuming that the object being checked is an editbale element, you can also check its
+	 * {@link module:engine/view/editableelement~EditableElement#name name}:
+	 *
+	 *		editableElement.is( 'element', 'div' ); // -> true if this is a div element
+	 *		editableElement.is( 'editableElement', 'div' ); // -> same as above
+	 *		text.is( 'element', 'div' ); -> false
+	 *
+	 * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
+	 *
+	 * @param {String} type Type to check.
+	 * @param {String} [name] Element name.
+	 * @returns {Boolean}
+	 */
+	is( type, name = null ) {
+		if ( !name ) {
+			return type === 'editableElement' || type === 'view:editableElement' ||
+				// From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+				type === 'containerElement' || type === 'view:containerElement' ||
+				type === 'element' || type === 'view:element' ||
+				type === 'node' || type === 'view:node';
+		} else {
+			return name === this.name && (
+				type === 'editableElement' || type === 'view:editableElement' ||
+				// From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+				type === 'containerElement' || type === 'view:containerElement' ||
+				type === 'element' || type === 'view:element'
+			);
+		}
+	}
+
+	destroy() {
+		this.stopListening();
+	}
+}
+
+mix( EditableElement, ObservableMixin );