Class

EditorUI (core/editor)

@ckeditor/ckeditor5-core/src/editor/editorui

class

A class providing the minimal interface that is required to successfully bootstrap any editor UI.

Filtering

Properties

  • readonly

    componentFactory : ComponentFactory

    An instance of the ComponentFactory, a registry used by plugins to register factories of specific UI components.

  • readonly

    editor : Editor

    The editor that the UI belongs to.

  • readonly

    element : HTMLElement | null

    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. In InlineEditor it is the editable element itself (as there is no other wrapper). However, in DecoupledEditor it is set to null 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.

  • readonly

    focusTracker : FocusTracker

    Stores the information about the editor UI focus and propagates it so various plugins and components are unified as a focus group.

  • readonly

    isReady : Boolean

    Indicates the UI is ready. Set true after event-ready event is fired.

    Defaults to false

  • readonly

    tooltipManager : TooltipManager

    Manages the tooltips displayed on mouseover and focus across the UI.

  • observable

    viewportOffset : Object

    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
    };
    
  • deprecated protected

    _editableElements : Map.<String, HTMLElement>

    Stores all editable elements used by the editor instance.

  • private

    _editableElementsMap : Map.<String, HTMLElement>

    Stores all editable elements used by the editor instance.

  • private

    _focusableToolbarDefinitions : Array.<FocusableToolbarDefinition>

    All available & focusable toolbars.

Methods

  • constructor( editor )

    Creates an instance of the editor UI class.

    Parameters

    editor : Editor

    The editor instance.

  • addToolbar( toolbarView, [ options ] = { [options.isContextual], [options.beforeFocus], [options.afterBlur] } )

    Adds a toolbar to the editor UI. Used primarily to maintain the accessibility of the UI.

    Focusable toolbars can be accessed (focused) by users by pressing the Alt + F10 keystroke. Successive keystroke presses navigate over available toolbars.

    Parameters

    toolbarView : ToolbarView

    A instance of the toolbar to be registered.

    [ options ] : Object
    Properties
    [ options.isContextual ] : Boolean

    Set true if the toolbar is attached to the content of the editor. Such toolbar takes a precedence over other toolbars when a user pressed Alt + F10.

    [ options.beforeFocus ] : function

    Specify a callback executed before the toolbar instance DOM element gains focus upon the Alt + F10 keystroke.

    [ options.afterBlur ] : function

    Specify a callback executed after the toolbar instance DOM element loses focus upon Esc keystroke but before the focus goes back to the editable element.

  • mixed

    delegate( events ) → EmitterMixinDelegateChain

    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 and emitterC along with data:

    emitterA.fire( 'eventX', data );
    

    and eventY is delegated (fired by) emitterC along with data:

    emitterA.fire( 'eventY', data );
    

    Parameters

    events : String

    Event names that will be delegated to another emitter.

    Returns

    EmitterMixinDelegateChain
  • destroy()

    Destroys the UI.

  • mixed

    fire( eventOrInfo, [ args ] ) → *

    Fires an event, executing all callbacks registered for it.

    The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() 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 the evt.return's property (the event info is the first param of every callback).

  • getEditableElement( [ rootName ] ) → HTMLElement | undefined

    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>

    Returns array of names of all editor editable elements.

    Returns

    Iterable.<String>
  • mixed

    listenTo( emitter, event, callback, [ options ] = { [options.priority] } )

    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 {}

  • mixed

    off( event, callback )

    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.

  • mixed

    on( event, callback, [ options ] = { [options.priority] } )

    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 {}

  • mixed

    once( event, callback, [ options ] = { [options.priority] } )

    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.

    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 )

    Stores the native DOM editable element used by the editor under a unique name.

    Also, registers the element in the editor to maintain the accessibility of the UI. When the user is editing text in a focusable editable area, they can use the Alt + F10 keystroke to navigate over editor toolbars. See addToolbar.

    Parameters

    rootName : String

    The unique name of the editable element.

    domElement : HTMLElement

    The native DOM editable element.

  • mixed

    stopDelegating( [ event ], [ emitter ] )

    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 of event to all emitters.

  • mixed

    stopListening( [ emitter ], [ event ], [ callback ] )

    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 from emitter.

    [ callback ] : function

    (Requires the event) The function to be removed from the call list for the given event.

  • 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).

  • protected mixed

    _addEventListener( event, callback, [ options ] = { [options.priority] } )

    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 {}

  • protected mixed

    _removeEventListener( event, callback )

    Removes callback from emitter for given event.

    Parameters

    event : String

    The name of the event.

    callback : function

    The function to stop being called.

  • private

    _focusFocusableCandidateToolbar( candidateToolbarDefinition ) → Boolean

    Focuses a focusable toolbar candidate using its definition.

    Parameters

    candidateToolbarDefinition : FocusableToolbarDefinition

    A definition of the toolbar to focus.

    Returns

    Boolean

    true when the toolbar candidate was focused. false otherwise.

  • private

    _getCurrentFocusedToolbarDefinition() → FocusableToolbarDefinition | null

    Returns a definition of the toolbar that is currently visible and focused (one of its children has focus).

    null is returned when no toolbar is currently focused.

    Returns

    FocusableToolbarDefinition | null
  • private

    _getFocusableCandidateToolbarDefinitions() → Array.<FocusableToolbarDefinition>

    Returns definitions of toolbars that could potentially be focused, sorted by their importance for the user.

    Focusable toolbars candidates are either:

    • already visible,
    • have beforeFocus() set in their definition that suggests that they might show up when called. Keep in mind that determining whether a toolbar will show up (and become focusable) is impossible at this stage because it depends on its implementation, that in turn depends on the editing context (selection).

    Note: Contextual toolbars take precedence over regular toolbars.

    Returns

    Array.<FocusableToolbarDefinition>
  • private

    _initFocusTracking()

    Starts listening for Alt + F10 and Esc keystrokes in the context of focusable editable elements and toolbars to allow users navigate across the UI.

  • private

    _readViewportOffsetFromConfig() → Object

    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 )

    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 or null, if operation should remove property.

    oldValue : Object

    Old value of the viewportOffset property with given key or null, if property was not set before.

  • ready( eventInfo )

    Fired when the editor UI is ready.

    Fired before event-ready.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

  • update( eventInfo )

    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 the update method.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.