CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

BalloonEditorUI (editor-balloon)

@ckeditor/ckeditor5-editor-balloon/src/ballooneditorui

class
See source

The balloon editor UI class.

Filtering

Properties

  • componentFactory : ComponentFactory

    readonly inherited

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

    See source

  • editor : Editor

    readonly inherited

    The editor that the UI belongs to.

    See source

  • element : HTMLElement | null

    readonly inherited

    The main (outermost) DOM element of the editor UI.

    See source

    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.

  • focusTracker : FocusTracker

    readonly inherited

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

    See source

  • view : EditorUIView

    readonly

    The main (top–most) view of the editor UI.

    See source

  • viewportOffset : Object

    inherited observable

    Stores viewport offsets from every direction.

    See source

    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>

    deprecated protected inherited

    Stores all editable elements used by the editor instance.

    See source

  • _editableElementsMap : Map.<String, HTMLElement>

    private inherited

    Stores all editable elements used by the editor instance.

    See source

Methods

  • constructor( editor, view )

    Creates an instance of the balloon editor UI class.

    See source

    Parameters

    editor : Editor

    The editor instance.

    view : EditorUIView

    The view of the UI.

  • delegate( events ) → EmitterMixinDelegateChain

    mixed

    Delegates selected events to another Emitter. For instance:

    See source
    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()

    inherited

    Destroys the UI.

    See source

  • fire( eventOrInfo, [ args ] ) → *

    mixed

    Fires an event, executing all callbacks registered for it.

    See source

    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

    inherited

    Returns the editable editor element with the given name or null if editable does not exist.

    See source

    Parameters

    [ rootName ] : String

    The editable name.

    Defaults to main

    Returns

    HTMLElement | undefined

  • getEditableElementsNames() → Iterable.<String>

    inherited

    Returns array of names of all editor editable elements.

    See source

    Returns

    Iterable.<String>

  • init()

    Initializes the UI.

    See source

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

    mixed

    Registers a callback function to be executed when an event is fired in a specific (emitter) object.

    See source

    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 )

    mixed

    Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).

    See source

    Parameters

    event : String

    The name of the event.

    callback : function

    The function to stop being called.

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

    mixed

    Registers a callback function to be executed when an event is fired.

    See source

    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] } )

    mixed

    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.

    See source

    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 )

    inherited

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

    See source

    Parameters

    rootName : String

    The unique name of the editable element.

    domElement : HTMLElement

    The native DOM editable element.

  • stopDelegating( [ event ], [ emitter ] )

    mixed

    Stops delegating events. It can be used at different levels:

    See source
    • 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.

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

    mixed

    Stops listening for events. It can be used at different levels:

    See source
    • 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()

    inherited

    Fires the update event.

    See source

    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] } )

    protected mixed

    Adds callback to emitter for given event.

    See source

    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 )

    protected mixed

    Removes callback from emitter for given event.

    See source

    Parameters

    event : String

    The name of the event.

    callback : function

    The function to stop being called.

  • _initPlaceholder()

    private

    Enable the placeholder text on the editing root, if any was configured.

    See source

  • _readViewportOffsetFromConfig() → Object

    private inherited

    Returns viewport offsets object:

    See source
    {
	top: Number,
	right: Number,
	bottom: Number,
	left: Number
}

    Only top property is currently supported.

    Returns

    Object

Events

  • change:viewportOffset( eventInfo, name, value, oldValue )

    inherited

    Fired when the viewportOffset property changed value.

    See source

    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 )

    inherited

    Fired when the editor UI is ready.

    See source

    Fired before event-ready.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

  • update( eventInfo )

    inherited

    Fired whenever the UI (all related components) should be refreshed.

    See source

    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.