CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 4/API
Class

CKEDITOR.ui.balloonToolbarView

class private

A class representing the view of the balloon toolbar, used by CKEDITOR.ui.balloonToolbar.

Filtering

Properties

  • activeShowListeners : Object

    Event listeners associated with this balloon panel, active as long as the panel is shown. See addShowListener, activateShowListeners, deactivateShowListeners.

    Defaults to {}

  • editor : Object

    The editor for this balloon panel.

  • focusables : Object

    Focusable elements in this balloon panel. See registerFocusable, deregisterFocusable and CKEDITOR.focusManager.

    Defaults to {}

  • height : String

    The default height of the balloon panel.

    Defaults to 'auto'

  • parts : Object

    The UI elements of the balloon panel.

    Defaults to {}

  • rect : Object

    Contains panel properties as move, resize, show and hide are called. It stores values and avoids unnecessary and expensive checks in the future.

    Defaults to {visible: false}

  • showListeners : Object

    Event listeners associated with this balloon panel, activated on panel show. See addShowListener, activateShowListeners, deactivateShowListeners.

    Defaults to {}

  • templateDefinitions : Object

    Balloon panel templates. Automatically converted into a CKEDITOR.template in the panel constructor.

  • templates : Object

    Templates for UI elements in this balloon panel. See templateDefinitions, parts.

    Defaults to {}

  • triangleHeight : Number

    The default height of the triangle that points to the element in the editable.

    Defaults to 20

  • triangleMinDistance : Number

    The default distance between the triangle and the vertical edge of the panel.

    Defaults to 40

  • triangleWidth : Number

    The default width of the triangle that points to the element in the editable.

    Defaults to 20

  • width : Number

    The default width of the balloon panel.

    Defaults to 360

  • _listeners : Array

    private

    Listeners registered by this toolbar view.

    Defaults to []

  • _pointedElement : Object

    private

    The DOM element used by the balloon toolbar to attach to.

Methods

  • constructor( editor, definition ) → balloonToolbarView

    since 4.8

    Creates a balloon toolbar view instance.

    Parameters

    editor : editor

    The editor instance for which the toolbar is created.

    definition : Object

    An object containing the toolbar definition. See CKEDITOR.ui.balloonPanel documentation for an example definition.

    Returns

    balloonToolbarView

  • _getViewPaneRect( window ) → Object

    Parameters

    window : window

    Returns

    Object

    Returns viewport position, taking scroll offset into account.

    Properties
    top : Number
    bottom : Number
    left : Number
    right : Number

  • activateShowListener( id )

    Activates an event listener associated with this balloon panel. See showListeners, activeShowListeners, deactivateShowListener, addShowListener, removeShowListener.

    Parameters

    id : Object

  • activateShowListeners()

    Activates all event listeners associated with this balloon panel. See showListeners, activeShowListeners, deactivateShowListeners, addShowListener, removeShowListener.

  • addShowListener( listener ) → Object

    Adds an event listener associated with this balloon panel. This listener will be activated on panel show and deactivated on panel hide. See showListeners, activeShowListeners, activateShowListeners, deactivateShowListeners.

    Parameters

    listener : Function

    A function that, if called, attaches the listener and returns the listener object.

    Returns

    Object

    An object containing the removeListener method that removes the listener from the collection.

  • attach( elementOrSelection, [ options ] )

    Places the balloon panel next to a specified element or a selection so the tip of the balloon's triangle touches that element or the center of the selection. Once the panel is attached it gains focus.

    Parameters

    elementOrSelection : element | selection

    The element or selection to which the panel is attached. Since 4.11.0 instead of an element it is possible to pass a selection CKEDITOR.dom.selection.

    [ options ] : Object | element | Boolean

    Since 4.8.0 this parameter works as an options object.

    If a CKEDITOR.dom.element/Boolean instance is given, this parameter acts as an options.focusElement.

    Properties
    [ focusElement ] : element | Boolean

    The element to be focused after the panel is attached. By default the panel property of parts will be focused. You might specify the element to be focused by passing any CKEDITOR.dom.element instance. You can also prevent changing the focus at all by setting it to false.

    [ show ] : Boolean

    Defines if the balloon panel should be shown after being attached.

    Defaults to true

    Overrides: CKEDITOR.ui.balloonPanel.attach

  • blur( [ focusEditor ] )

    Moves the focus back to the editor's editable.

    Parameters

    [ focusEditor ] : Boolean

    Whether the editor should be focused after blurring.

    Defaults to false

    Overrides: CKEDITOR.ui.balloonPanel.blur

  • build()

    Builds the balloon toolbar DOM representation.

    Overrides: CKEDITOR.ui.balloonPanel.build

  • deactivateShowListener( id )

    Deactivates an event listener associated with this balloon panel. See activateShowListener.

    Parameters

    id : Object

  • deactivateShowListeners()

    Removes all event listeners associated with this balloon panel. See activateShowListeners.

  • deregisterFocusable( element )

    Unregisters an element from editor's focus manager. See focusables.

    Parameters

    element : element

    An element to be registered.

  • destroy()

    Destroys the balloon panel by removing it from DOM and purging all associated event listeners.

  • getHeight() → Number

    Returns the balloon panel height.

    Returns

    Number

  • getWidth() → Number

    Returns the balloon panel width.

    Returns

    Number

  • hide()

    Hides the balloon panel and moves the focus back to the editable.

  • move( top, left )

    Moves the upper-left balloon panel corner to the specified absolute position.

    Parameters

    top : Number
    left : Number

  • registerFocusable( element )

    Registers a new focusable element in the editor's focus manager so the instance does not blur once the child of the balloon panel gains focus. See focusables.

    Parameters

    element : element

    An element to be registered.

  • removeShowListener( id )

    Removes an event listener associated with this balloon panel visible state. See addShowListener.

    Parameters

    id : Number

    An ID of the listener.

  • renderItems( items )

    Renders provided UI elements inside the view.

    Parameters

    items : button[] | richCombo[]

    An array of UI element objects.

  • resize( width, height )

    Resizes the balloon panel container to given dimensions. Use 'auto' to make the dimensions of the panel flexible.

    Parameters

    width : Number
    height : Number

  • setTitle( title )

    Sets the balloon panel title.

    Parameters

    title : String

    A new panel title.

  • setTriangle( side )

    Changes the position of the balloon's triangle that points to the element in the editable.

    Parameters

    side : String

    One of 'left', 'right', 'top' or 'bottom'.

  • show()

    Shows the balloon panel.

  • _adjustElementRect( elementRect, editorRect )

    private

    This method will modify elementRect if the element is outside of editorRect. If it is outside, it is going to change it into a rectangle that is within editorRect.

    For example here elementRect is going to be changed into a very narrow rectangle (with unmodified height) representation within editorRect.

    +------------------------------------------+
|                                          |
|                                         #|          +----------+
|                                         #|          |          |
|                                         #|          |          |
|               editorRect                #|          |elmentRect|
|                                         #|          |          |
|                                         #|          |          |
|                                         #|          +----------+
|                                          |
+------------------------------------------+

    Parameters

    elementRect : Object

    Rectangle object that should be contained within editorRect. This object might be modified.

    editorRect : Object

    Reference container that should contain elementRect.

  • _deregisterItemFocusables()

    since 4.9.0 private

    Deregisters focusables registered by UI items, like buttons.

  • _detachListeners()

    private

    Detaches all listeners.

  • _getAlignments( elementRect, panelWidth, panelHeight ) → Object

    private

    Returns a dictionary containing different alignment positions.

    Keys tell where the balloon is positioned relative to the element, e.g. this would be the result for "top center":

    [Editor]
+-------------------------------------+
|         [Panel]                     |
|         +-----------------+         |
|         |                 |         |
|  [El.]  +--------v--------+         |
|  +-------------------------------+  |
|  |                               |  |
|  |                               |  |
+--+-------------------------------+--+

    Sample result:

    {
    "right vcenter": { top: 529.5, left: 175 },
    "left vcenter": { top: 529.5, left: 10},
    "top hcenter": { top: 402, left: 92.5},
    "top left": { top: 402, left: 102.5},
    "top right": { top: 402, left: 82.5},
    "bottom hcenter": { top: 643, left: 92.5},
    "bottom left": { top: 643, left: 102.5},
    "bottom right": { top: 643, left: 82.5}
}

    Parameters

    elementRect : Object
    panelWidth : Number
    panelHeight : Number

    Returns

    Object

Events

  • attach( evt )

    Event fired when the balloon panel is attached to an element.

    Parameters

    evt : eventInfo

  • hide( evt )

    Event fired when the balloon panel is hidden.

    Parameters

    evt : eventInfo

  • show( evt )

    Event fired when the balloon panel is shown.

    Parameters

    evt : eventInfo