Report an issue
Class

CKEDITOR.ui.balloonPanel

class since 4.6.0

A class that represents a floating, balloon-shaped panel capable of presenting defined content at a precise position in the document. It can be used to represent contextual data or forms i.e. related to an element in the editor's editable.

// Create an instance of the balloon panel.
var panel = new CKEDITOR.ui.balloonPanel( editor, {
    title: 'My Panel',
    content: '<p>This is my panel</p>'
} );

// Attach the panel to an element in DOM and show it immediately.
panel.attach( domElement );

Filtering

Properties

Methods

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

  • blur()

    Moves the focus back to the editor's editable.

  • build()

    Builds the UI of the balloon panel.

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

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

  • private

    _adjustElementRect( elementRect, editorRect )

    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.

  • private

    _getAlignments( elementRect, panelWidth, panelHeight ) → Object

    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