CKEditor 4
Report an issue
Class

CKEDITOR.ui.balloonPanel

class since 4.6

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

  • 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

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( element, [ options ] )

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

    Parameters

    element : element

    The element to which the panel is attached.

    [ 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 focus at all by setting it to false.

    [ show ] : Boolean

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

    Defaults to true

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

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

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