EditorUI (core/editor)
@ckeditor/ckeditor5-core/src/editor/editorui
A class providing the minimal interface that is required to successfully bootstrap any editor UI.
Filtering
Properties
-
componentFactory : ComponentFactory
module:core/editor/editorui~EditorUI#componentFactory
readonly
An instance of the
ComponentFactory
, a registry used by plugins to register factories of specific UI components. -
The editor that the UI belongs to.
-
element : HTMLElement | null
module:core/editor/editorui~EditorUI#element
readonly
The main (outermost) DOM element of the editor UI.
For example, in
ClassicEditor
it is a<div>
which wraps the editable element and the toolbar. InInlineEditor
it is the editable element itself (as there is no other wrapper). However, inDecoupledEditor
it is set tonull
because this editor does not come with a single "main" HTML element (its editable element and toolbar are separate).This property can be understood as a shorthand for retrieving the element that a specific editor integration considers to be its main DOM element.
-
focusTracker : FocusTracker
module:core/editor/editorui~EditorUI#focusTracker
readonly
Stores the information about the editor UI focus and propagates it so various plugins and components are unified as a focus group.
-
viewportOffset : Object
module:core/editor/editorui~EditorUI#viewportOffset
Stores viewport offsets from every direction.
Viewport offset can be used to constrain balloons or other UI elements into an element smaller than the viewport. This can be useful if there are any other absolutely positioned elements that may interfere with editor UI.
Example
editor.ui.viewportOffset
returns:{ top: 50, right: 50, bottom: 50, left: 50 }
This property can be overriden after editor already being initialized:
editor.ui.viewportOffset = { top: 100, right: 0, bottom: 0, left: 0 };
-
_editableElements : Map.<String, HTMLElement>
module:core/editor/editorui~EditorUI#_editableElements
deprecated protected
Stores all editable elements used by the editor instance.
-
_editableElementsMap : Map.<String, HTMLElement>
module:core/editor/editorui~EditorUI#_editableElementsMap
private
Stores all editable elements used by the editor instance.
Methods
-
constructor( editor )
module:core/editor/editorui~EditorUI#constructor
Creates an instance of the editor UI class.
Parameters
editor : Editor
The editor instance.
-
delegate( events ) → EmitterMixinDelegateChain
module:core/editor/editorui~EditorUI#delegate
mixed
Delegates selected events to another
Emitter
. For instance:emitterA.delegate( 'eventX' ).to( emitterB ); emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
then
eventX
is delegated (fired by)emitterB
andemitterC
along withdata
:emitterA.fire( 'eventX', data );
and
eventY
is delegated (fired by)emitterC
along withdata
:emitterA.fire( 'eventY', data );
Parameters
events : String
Event names that will be delegated to another emitter.
Returns
-
destroy()
module:core/editor/editorui~EditorUI#destroy
Destroys the UI.
-
fire( eventOrInfo, [ args ] ) → *
module:core/editor/editorui~EditorUI#fire
mixed
Fires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an
EventInfo
object, followed by the optionalargs
provided in thefire()
method call.Parameters
eventOrInfo : String | EventInfo
The name of the event or
EventInfo
object if event is delegated.[ args ] : *
Additional arguments to be passed to the callbacks.
Returns
*
By default the method returns
undefined
. However, the return value can be changed by listeners through modification of theevt.return
's property (the event info is the first param of every callback).
-
getEditableElement( [ rootName ] ) → HTMLElement | undefined
module:core/editor/editorui~EditorUI#getEditableElement
Returns the editable editor element with the given name or null if editable does not exist.
Parameters
[ rootName ] : String
The editable name.
Defaults to
main
Returns
HTMLElement | undefined
-
getEditableElementsNames() → Iterable.<String>
module:core/editor/editorui~EditorUI#getEditableElementsNames
Returns array of names of all editor editable elements.
Returns
Iterable.<String>
-
listenTo( emitter, event, callback, [ options ] = { [options.priority] } )
module:core/editor/editorui~EditorUI#listenTo
mixed
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 stop the event and set the return value of the
fire
method.Parameters
emitter : Emitter
The object that fires the event.
event : String
The name of the event.
callback : function
The function to be called on event.
[ options ] : Object
Additional options.
Properties[ options.priority ] : PriorityString | Number
The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.
Defaults to
'normal'
Defaults to
{}
-
off( event, callback )
module:core/editor/editorui~EditorUI#off
mixed
Stops executing the callback on the given event. Shorthand for
this.stopListening( this, event, callback )
.Parameters
event : String
The name of the event.
callback : function
The function to stop being called.
-
on( event, callback, [ options ] = { [options.priority] } )
module:core/editor/editorui~EditorUI#on
mixed
Registers a callback function to be executed when an event is fired.
Shorthand for
this.listenTo( this, event, callback, options )
(it makes the emitter listen on itself).Parameters
event : String
The name of the event.
callback : function
The function to be called on event.
[ options ] : Object
Additional options.
Properties[ options.priority ] : PriorityString | Number
The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.
Defaults to
'normal'
Defaults to
{}
-
once( event, callback, [ options ] = { [options.priority] } )
module:core/editor/editorui~EditorUI#once
mixed
Registers a callback function to be executed on the next time the event is fired only. This is similar to calling
on
followed byoff
in the callback.Parameters
event : String
The name of the event.
callback : function
The function to be called on event.
[ options ] : Object
Additional options.
Properties[ options.priority ] : PriorityString | Number
The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.
Defaults to
'normal'
Defaults to
{}
-
setEditableElement( rootName, domElement )
module:core/editor/editorui~EditorUI#setEditableElement
Store the native DOM editable element used by the editor under a unique name.
Parameters
rootName : String
The unique name of the editable element.
domElement : HTMLElement
The native DOM editable element.
-
stopDelegating( [ event ], [ emitter ] )
module:core/editor/editorui~EditorUI#stopDelegating
mixed
Stops delegating events. It can be used at different levels:
- To stop delegating all events.
- To stop delegating a specific event to all emitters.
- To stop delegating a specific event to a specific emitter.
Parameters
[ event ] : String
The name of the event to stop delegating. If omitted, stops it all delegations.
[ emitter ] : Emitter
(requires
event
) The object to stop delegating a particular event to. If omitted, stops delegation ofevent
to all emitters.
-
stopListening( [ emitter ], [ event ], [ callback ] )
module:core/editor/editorui~EditorUI#stopListening
mixed
Stops listening for events. It can be used at different levels:
- To stop listening to a specific callback.
- To stop listening to a specific event.
- To stop listening to all events fired by a specific object.
- To stop listening to all events fired by all objects.
Parameters
[ emitter ] : Emitter
The object to stop listening to. If omitted, stops it for all objects.
[ event ] : String
(Requires the
emitter
) The name of the event to stop listening to. If omitted, stops it for all events fromemitter
.[ callback ] : function
(Requires the
event
) The function to be removed from the call list for the givenevent
.
-
update()
module:core/editor/editorui~EditorUI#update
Fires the
update
event.This method should be called when the editor UI (e.g. positions of its balloons) needs to be updated due to some environmental change which CKEditor 5 is not aware of (e.g. resize of a container in which it is used).
-
_addEventListener( event, callback, [ options ] = { [options.priority] } )
module:core/editor/editorui~EditorUI#_addEventListener
protected mixed
Adds callback to emitter for given event.
Parameters
event : String
The name of the event.
callback : function
The function to be called on event.
[ options ] : Object
Additional options.
Properties[ options.priority ] : PriorityString | Number
The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.
Defaults to
'normal'
Defaults to
{}
-
_removeEventListener( event, callback )
module:core/editor/editorui~EditorUI#_removeEventListener
protected mixed
Removes callback from emitter for given event.
Parameters
event : String
The name of the event.
callback : function
The function to stop being called.
-
_readViewportOffsetFromConfig() → Object
module:core/editor/editorui~EditorUI#_readViewportOffsetFromConfig
private
Returns viewport offsets object:
{ top: Number, right: Number, bottom: Number, left: Number }
Only top property is currently supported.
Returns
Object
Events
-
change:viewportOffset( eventInfo, name, value, oldValue )
module:core/editor/editorui~EditorUI#event:change:viewportOffset
Fired when the
viewportOffset
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : String
Name of the changed property (
viewportOffset
).value : Object
New value of the
viewportOffset
property with given key ornull
, if operation should remove property.oldValue : Object
Old value of the
viewportOffset
property with given key ornull
, if property was not set before.
-
ready( eventInfo )
module:core/editor/editorui~EditorUI#event:ready
Fired when the editor UI is ready.
Fired before
event-ready
.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
-
update( eventInfo )
module:core/editor/editorui~EditorUI#event:update
Fired whenever the UI (all related components) should be refreshed.
Note:: The event is fired after each
event-layoutChanged
. It can also be fired manually via theupdate
method.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
Every day, we work hard to keep our documentation complete. Have you spotted an outdated information? Is something missing? Please report it via our issue tracker.