Creates an empty live selection for given module:engine/model/document~ModelDocument.
Document which owns this selection.
InternalUsed for the compatibility with the module:engine/model/selection~ModelSelection#isEqual method.
Selection anchor. Anchor may be described as a position where the most recent part of the selection starts. Together with #focus they define the direction of selection, which is important when expanding/shrinking selection. Anchor is always module:engine/model/range~ModelRange#start start or module:engine/model/range~ModelRange#end end position of the most recently added range.
Is set to null if there are no ranges in selection.
Selection focus. Focus is a position where the selection ends.
Is set to null if there are no ranges in selection.
Describes whether Documentselection has own range(s) set, or if it is defaulted to
module:engine/model/document~ModelDocument#_getDefaultRange document's default range.
Specifies whether the #focus precedes #anchor.
Describes whether the selection is collapsed. Selection is collapsed when there is exactly one range which is collapsed.
Describes whether the gravity is overridden (using module:engine/model/writer~ModelWriter#overrideSelectionGravity) or not.
Note that the gravity remains overridden as long as will not be restored the same number of times as it was overridden.
A collection of selection module:engine/model/markercollection~Marker markers. Marker is a selection marker when selection range is inside the marker range.
Note: Only markers from ~ModelDocumentSelection#observeMarkers observed markers groups are collected.
Number of ranges in selection.
InternalReturns an iterable that iterates through all selection attributes stored in current selection's parent.
InternalTemporarily changes the gravity of the selection from the left to the 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 the user) inherits attributes from its left hand side. This method allows to temporarily override this behavior by forcing the gravity to the right.
It returns an unique identifier which is required to restore the gravity. It guarantees the symmetry of the process.
The unique id which allows restoring the gravity.
InternalRemoves an attribute with given key from the selection. If the given attribute was set on the selection, fires the module:engine/model/selection~ModelSelection#event:change:range event with removed attribute key. Should be used only within the module:engine/model/writer~ModelWriter#removeSelectionAttribute method.
Key of the attribute to remove.
InternalRestores the ~ModelDocumentSelection#_overrideGravity overridden gravity.
Restoring the gravity is only possible using the unique identifier returned by ~ModelDocumentSelection#_overrideGravity. Note that the gravity remains overridden as long as won't be restored the same number of times it was overridden.
The unique id returned by #_overrideGravity.
InternalSets attribute on the selection. If attribute with the same key already is set, it's value is overwritten. Should be used only within the module:engine/model/writer~ModelWriter#setSelectionAttribute method.
Key of the attribute to set.
Attribute value.
InternalMoves module:engine/model/documentselection~ModelDocumentSelection#focus to the specified location. Should be used only within the module:engine/model/writer~ModelWriter#setSelectionFocus method.
The location can be specified in the same form as module:engine/model/writer~ModelWriter#createPositionAt writer.createPositionAt() parameters.
Optionaloffset: ModelPositionOffsetOffset or one of the flags. Used only when first parameter is a module:engine/model/item~ModelItem model item.
InternalSets this selection's ranges and direction to the specified location based on the given module:engine/model/selection~ModelSelectable selectable. Should be used only within the module:engine/model/writer~ModelWriter#setSelection method.
Checks whether the selection contains the entire content of the given element. This means that selection must start at a position module:engine/model/position~ModelPosition#isTouching touching the element's start and ends at position touching the element's end.
By default, this method will check whether the entire content of the selection's current root is selected. Useful to check if e.g. the user has just pressed Ctrl + A.
Delegates selected events to another module:utils/emittermixin~Emitter. For instance:
emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
then eventX is delegated (fired by) emitterB and emitterC along with data:
emitterA.fire( 'eventX', data );
and eventY is delegated (fired by) emitterC along with data:
emitterA.fire( 'eventY', data );
Event names that will be delegated to another emitter.
Unbinds all events previously bound by document selection.
Fires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an module:utils/eventinfo~EventInfo object,
followed by the optional args provided in the fire() method call.
The type describing the event. See module:utils/emittermixin~BaseEvent.
The name of the event or EventInfo object if event is delegated.
Additional arguments to be passed to the callbacks.
By default the method returns undefined. However, the return value can be changed by listeners
through modification of the module:utils/eventinfo~EventInfo#return evt.return's property (the event info
is the first param of every callback).
Gets an attribute value for given key or undefined if that attribute is not set on the selection.
Key of attribute to look for.
Attribute value or undefined.
Returns iterable that iterates over this selection's attribute keys.
Returns iterable that iterates over this selection's attributes.
Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value.
This format is accepted by native Map object and also can be passed in Node constructor.
Returns the first position in the selection. First position is the position that module:engine/model/position~ModelPosition#isBefore is before any other position in the selection.
Returns null if there are no ranges in selection.
Returns a copy of the first range in the selection. First range is the one which module:engine/model/range~ModelRange#start start position module:engine/model/position~ModelPosition#isBefore is before start position of all other ranges (not to confuse with the first range added to the selection).
Returns null if there are no ranges in selection.
Returns the last position in the selection. Last position is the position that module:engine/model/position~ModelPosition#isAfter is after any other position in the selection.
Returns null if there are no ranges in selection.
Returns a copy of the last range in the selection. Last range is the one which module:engine/model/range~ModelRange#end end position module:engine/model/position~ModelPosition#isAfter is after end position of all other ranges (not to confuse with the range most recently added to the selection).
Returns null if there are no ranges in selection.
Returns an iterable that iterates over copies of selection ranges.
Gets elements of type module:engine/model/schema~ModelSchema#isBlock "block" touched by the selection.
This method's result can be used for example to apply block styling to all blocks covered by this selection.
Note: getSelectedBlocks() returns blocks that are nested in other non-block elements
but will not return blocks nested in other blocks.
In this case the function will return exactly all 3 paragraphs (note: <blockQuote> is not a block itself):
<paragraph>[a</paragraph>
<blockQuote>
<paragraph>b</paragraph>
</blockQuote>
<paragraph>c]d</paragraph>
In this case the paragraph will also be returned, despite the collapsed selection:
<paragraph>[]a</paragraph>
In such a scenario, however, only blocks A, B & E will be returned as blocks C & D are nested in block B:
[<blockA></blockA>
<blockB>
<blockC></blockC>
<blockD></blockD>
</blockB>
<blockE></blockE>]
If the selection is inside a block all the inner blocks (A & B) are returned:
<block>
<blockA>[a</blockA>
<blockB>b]</blockB>
</block>
Special case: If a selection ends at the beginning of a block, that block is not returned as from user perspective this block wasn't selected. See #984 for more details.
<paragraph>[a</paragraph>
<paragraph>b</paragraph>
<paragraph>]c</paragraph> // this block will not be returned
Returns the selected element. module:engine/model/element~ModelElement 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.
Checks if the selection has an attribute for given key.
Key of attribute to check.
true if attribute with given key is set on selection, false otherwise.
Checks whether the object is of type module:engine/model/node~ModelNode or its subclass.
This method is useful when processing model objects that are of unknown type. For example, a function may return a module:engine/model/documentfragment~ModelDocumentFragment or a module:engine/model/node~ModelNode that can be either a text node or an element. This method can be used to check what kind of object is returned.
someObject.is( 'element' ); // -> true if this is an element
someObject.is( 'node' ); // -> true if this is a node (a text node or an element)
someObject.is( 'documentFragment' ); // -> true if this is a document fragment
Since this method is also available on a range of view objects, you can prefix the type of the object with
model: or view: to check, for example, if this is the model's or view's element:
modelElement.is( 'model:element' ); // -> true
modelElement.is( 'view:element' ); // -> false
By using this method it is also possible to check a name of an element:
imageElement.is( 'element', 'imageBlock' ); // -> true
imageElement.is( 'element', 'imageBlock' ); // -> same as above
imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more precise
Checks whether the object is of type module:engine/model/element~ModelElement or its subclass.
element.is( 'element' ); // -> true
element.is( 'node' ); // -> true
element.is( 'model:element' ); // -> true
element.is( 'model:node' ); // -> true
element.is( 'view:element' ); // -> false
element.is( 'documentSelection' ); // -> false
Assuming that the object being checked is an element, you can also check its module:engine/model/element~ModelElement#name name:
element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
text.is( 'element', 'imageBlock' ); -> false
Checks whether the object is of type module:engine/model/rootelement~ModelRootElement.
rootElement.is( 'rootElement' ); // -> true
rootElement.is( 'element' ); // -> true
rootElement.is( 'node' ); // -> true
rootElement.is( 'model:rootElement' ); // -> true
rootElement.is( 'model:element' ); // -> true
rootElement.is( 'model:node' ); // -> true
rootElement.is( 'view:element' ); // -> false
rootElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is an element, you can also check its module:engine/model/element~ModelElement#name name:
rootElement.is( 'rootElement', '$root' ); // -> same as above
Checks whether the object is of type module:engine/model/text~ModelText.
text.is( '$text' ); // -> true
text.is( 'node' ); // -> true
text.is( 'model:$text' ); // -> true
text.is( 'model:node' ); // -> true
text.is( 'view:$text' ); // -> false
text.is( 'documentSelection' ); // -> false
Note: Until version 20.0.0 this method wasn't accepting '$text' type. The legacy 'text' type is still
accepted for backward compatibility.
Checks whether the object is of type module:engine/model/position~ModelPosition or its subclass.
position.is( 'position' ); // -> true
position.is( 'model:position' ); // -> true
position.is( 'view:position' ); // -> false
position.is( 'documentSelection' ); // -> false
Checks whether the object is of type module:engine/model/liveposition~ModelLivePosition.
livePosition.is( 'position' ); // -> true
livePosition.is( 'model:position' ); // -> true
livePosition.is( 'liveposition' ); // -> true
livePosition.is( 'model:livePosition' ); // -> true
livePosition.is( 'view:position' ); // -> false
livePosition.is( 'documentSelection' ); // -> false
Checks whether the object is of type module:engine/model/range~ModelRange or its subclass.
range.is( 'range' ); // -> true
range.is( 'model:range' ); // -> true
range.is( 'view:range' ); // -> false
range.is( 'documentSelection' ); // -> false
Checks whether the object is of type module:engine/model/liverange~ModelLiveRange.
liveRange.is( 'range' ); // -> true
liveRange.is( 'model:range' ); // -> true
liveRange.is( 'liveRange' ); // -> true
liveRange.is( 'model:liveRange' ); // -> true
liveRange.is( 'view:range' ); // -> false
liveRange.is( 'documentSelection' ); // -> false
Checks whether the object is of type module:engine/model/documentfragment~ModelDocumentFragment.
docFrag.is( 'documentFragment' ); // -> true
docFrag.is( 'model:documentFragment' ); // -> true
docFrag.is( 'view:documentFragment' ); // -> false
docFrag.is( 'element' ); // -> false
docFrag.is( 'node' ); // -> false
Checks whether the object is of type module:engine/model/selection~ModelSelection or module:engine/model/documentselection~ModelDocumentSelection.
selection.is( 'selection' ); // -> true
selection.is( 'model:selection' ); // -> true
selection.is( 'view:selection' ); // -> false
selection.is( 'range' ); // -> false
Checks whether the object is of type module:engine/model/documentselection~ModelDocumentSelection.
selection.is( 'selection' ); // -> true
selection.is( 'documentSelection' ); // -> true
selection.is( 'model:selection' ); // -> true
selection.is( 'model:documentSelection' ); // -> true
selection.is( 'view:selection' ); // -> false
selection.is( 'element' ); // -> false
selection.is( 'node' ); // -> false
Checks whether the object is of type module:engine/model/markercollection~Marker.
marker.is( 'marker' ); // -> true
marker.is( 'model:marker' ); // -> true
marker.is( 'view:element' ); // -> false
marker.is( 'documentSelection' ); // -> false
Checks whether the object is of type module:engine/model/textproxy~ModelTextProxy.
textProxy.is( '$textProxy' ); // -> true
textProxy.is( 'model:$textProxy' ); // -> true
textProxy.is( 'view:$textProxy' ); // -> false
textProxy.is( 'range' ); // -> false
Note: Until version 20.0.0 this method wasn't accepting '$textProxy' type. The legacy 'textProxt' type is still
accepted for backward compatibility.
Checks whether the object is of type module:engine/model/element~ModelElement or its subclass and has the specified name.
element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
text.is( 'element', 'imageBlock' ); -> false
Checks whether the object is of type module:engine/model/rootelement~ModelRootElement and has the specified name.
rootElement.is( 'rootElement', '$root' );
Registers a callback function to be executed when an event is fired in a specific (emitter) object.
Events can be grouped in namespaces using :.
When namespaced event is fired, it additionally fires all callbacks for that namespace.
// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );
// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );
An event callback can module:utils/eventinfo~EventInfo#stop stop the event and set the module:utils/eventinfo~EventInfo#return return value of the #fire method.
The type describing the event. See module:utils/emittermixin~BaseEvent.
The object that fires the event.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
Registers a marker group prefix or a marker name to be collected in the ~ModelDocumentSelection#markers selection markers collection.
See also module:engine/model/markercollection~MarkerCollection#getMarkersGroup MarkerCollection#getMarkersGroup().
The marker group prefix or marker name.
Stops executing the callback on the given event.
Shorthand for #stopListening this.stopListening( this, event, callback ).
The name of the event.
The function to stop being called.
Registers a callback function to be executed when an event is fired.
Shorthand for #listenTo this.listenTo( this, event, callback, options ) (it makes the emitter
listen on itself).
The type descibing the event. See module:utils/emittermixin~BaseEvent.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
Registers a callback function to be executed on the next time the event is fired only. This is similar to calling #on followed by #off in the callback.
The type descibing the event. See module:utils/emittermixin~BaseEvent.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
Refreshes selection attributes and markers according to the current position in the model.
Stops delegating events. It can be used at different levels:
Optionalevent: stringThe name of the event to stop delegating. If omitted, stops it all delegations.
Optionalemitter: Emitter(requires event) The object to stop delegating a particular event to.
If omitted, stops delegation of event to all emitters.
Stops listening for events. It can be used at different levels:
Optionalemitter: EmitterThe object to stop listening to. If omitted, stops it for all objects.
Optionalevent: string(Requires the emitter) The name of the event to stop listening to. If omitted, stops it
for all events from emitter.
Optionalcallback: Function(Requires the event) The function to be removed from the call list for the given
event.
Converts DocumentSelection to plain object and returns it.
DocumentSelection converted to plain object.
Static_InternalGenerates and returns an attribute key for selection attributes store, basing on original attribute key.
Attribute key to convert.
Converted attribute key, applicable for selection store.
Static_InternalChecks whether the given attribute key is an attribute stored on an element.
ModelDocumentSelectionis a special selection which is used as the module:engine/model/document~ModelDocument#selection document's selection. There can be only one instance ofModelDocumentSelectionper document.Document selection can only be changed by using the module:engine/model/writer~ModelWriter instance inside the module:engine/model/model~Model#change
change()block, as it provides a secure way to modify model.ModelDocumentSelectionis automatically updated upon changes in the module:engine/model/document~ModelDocument document to always contain valid ranges. Its attributes are inherited from the text unless set explicitly.Differences between module:engine/model/selection~ModelSelection and
ModelDocumentSelectionare:ModelDocumentSelection- even if no ranges were added there is a "default range" present in the selection,ModelDocumentSelectionare updated automatically according to selection ranges.Since
ModelDocumentSelectionuses module:engine/model/liverange~ModelLiveRange live ranges and is updated when module:engine/model/document~ModelDocument document changes, it cannot be set on module:engine/model/node~ModelNode nodes that are inside module:engine/model/documentfragment~ModelDocumentFragment document fragment. If you need to represent a selection in document fragment, use module:engine/model/selection~ModelSelection Selection class instead.