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

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

activeShowListeners : Object

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

Defaults to {}
editor : Object

See source
The editor for this balloon panel.
focusables : Object

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

Defaults to {}
height : String

See source
The default height of the balloon panel.

Defaults to 'auto'
parts : Object

See source
The UI elements of the balloon panel.

Defaults to {}
rect : Object

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

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

Defaults to {}
templateDefinitions : Object

See source
Balloon panel templates. Automatically converted into a CKEDITOR.template in the panel constructor.
templates : Object

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

Defaults to {}
triangleHeight : Number

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

Defaults to 20
triangleMinDistance : Number

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

Defaults to 40
triangleWidth : Number

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

Defaults to 20
width : Number

See source
The default width of the balloon panel.

Defaults to 360

Methods

_getViewPaneRect( window ) → Object

See source

Parameters

window : window

Returns

Object

Returns viewport position, taking scroll offset into account.

Properties

top : Number

bottom : Number

left : Number

right : Number
activateShowListener( id )

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

Parameters

id : Object
activateShowListeners()

See source
Activates all event listeners associated with this balloon panel. See showListeners, activeShowListeners, deactivateShowListeners, addShowListener, removeShowListener.
addShowListener( listener ) → Object

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

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

See source
Moves the focus back to the editor's editable.
build()

See source
Builds the UI of the balloon panel.
deactivateShowListener( id )

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

Parameters

id : Object
deactivateShowListeners()

See source
Removes all event listeners associated with this balloon panel. See activateShowListeners.
deregisterFocusable( element )

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

Parameters

element : element

An element to be registered.
destroy()

See source
Destroys the balloon panel by removing it from DOM and purging all associated event listeners.
getHeight() → Number

See source
Returns the balloon panel height.

Returns

Number
getWidth() → Number

See source
Returns the balloon panel width.

Returns

Number
hide()

See source
Hides the balloon panel and moves the focus back to the editable.
move( top, left )

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

Parameters

top : Number

left : Number
registerFocusable( element )

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

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

Parameters

id : Number

An ID of the listener.
resize( width, height )

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

See source
Sets the balloon panel title.

Parameters

title : String

A new panel title.
setTriangle( side )

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

See source
Shows the balloon panel.
private
_adjustElementRect( elementRect, editorRect )
See source
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`

See source

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 )

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

Parameters

evt : eventInfo
hide( evt )

See source
Event fired when the balloon panel is hidden.

Parameters

evt : eventInfo
show( evt )

See source
Event fired when the balloon panel is shown.

Parameters

evt : eventInfo

CKEDITOR.ui.balloonPanel

Filtering

Properties

activeShowListeners : ObjectCKEDITOR.ui.balloonPanel#activeShowListeners

editor : ObjectCKEDITOR.ui.balloonPanel#editor

focusables : ObjectCKEDITOR.ui.balloonPanel#focusables

height : StringCKEDITOR.ui.balloonPanel#height

parts : ObjectCKEDITOR.ui.balloonPanel#parts

rect : ObjectCKEDITOR.ui.balloonPanel#rect

showListeners : ObjectCKEDITOR.ui.balloonPanel#showListeners

templateDefinitions : ObjectCKEDITOR.ui.balloonPanel#templateDefinitions

templates : ObjectCKEDITOR.ui.balloonPanel#templates

triangleHeight : NumberCKEDITOR.ui.balloonPanel#triangleHeight

triangleMinDistance : NumberCKEDITOR.ui.balloonPanel#triangleMinDistance

triangleWidth : NumberCKEDITOR.ui.balloonPanel#triangleWidth

width : NumberCKEDITOR.ui.balloonPanel#width

Methods

_getViewPaneRect( window ) → ObjectCKEDITOR.ui.balloonPanel#_getViewPaneRect

Parameters

Returns

activateShowListener( id )CKEDITOR.ui.balloonPanel#activateShowListener

Parameters

activateShowListeners()CKEDITOR.ui.balloonPanel#activateShowListeners

addShowListener( listener ) → ObjectCKEDITOR.ui.balloonPanel#addShowListener

Parameters

Returns

attach( elementOrSelection, [ options ] )CKEDITOR.ui.balloonPanel#attach

Parameters

blur()CKEDITOR.ui.balloonPanel#blur

build()CKEDITOR.ui.balloonPanel#build

deactivateShowListener( id )CKEDITOR.ui.balloonPanel#deactivateShowListener

Parameters

deactivateShowListeners()CKEDITOR.ui.balloonPanel#deactivateShowListeners

deregisterFocusable( element )CKEDITOR.ui.balloonPanel#deregisterFocusable

Parameters

destroy()CKEDITOR.ui.balloonPanel#destroy

getHeight() → NumberCKEDITOR.ui.balloonPanel#getHeight

Returns

getWidth() → NumberCKEDITOR.ui.balloonPanel#getWidth

Returns

hide()CKEDITOR.ui.balloonPanel#hide

move( top, left )CKEDITOR.ui.balloonPanel#move

Parameters

registerFocusable( element )CKEDITOR.ui.balloonPanel#registerFocusable

Parameters

removeShowListener( id )CKEDITOR.ui.balloonPanel#removeShowListener

Parameters

resize( width, height )CKEDITOR.ui.balloonPanel#resize

Parameters

setTitle( title )CKEDITOR.ui.balloonPanel#setTitle

Parameters

setTriangle( side )CKEDITOR.ui.balloonPanel#setTriangle

Parameters

show()CKEDITOR.ui.balloonPanel#show

private _adjustElementRect( elementRect, editorRect )CKEDITOR.ui.balloonPanel#_adjustElementRect

Parameters

private _getAlignments( elementRect, panelWidth, panelHeight ) → ObjectCKEDITOR.ui.balloonPanel#_getAlignments

Parameters

Returns

Events

attach( evt )CKEDITOR.ui.balloonPanel#attach

Parameters

hide( evt )CKEDITOR.ui.balloonPanel#hide

Parameters

show( evt )CKEDITOR.ui.balloonPanel#show

Parameters

`activeShowListeners : Object`

`editor : Object`

`focusables : Object`

`height : String`

`parts : Object`

`rect : Object`

`showListeners : Object`

`templateDefinitions : Object`

`templates : Object`

`triangleHeight : Number`

`triangleMinDistance : Number`

`triangleWidth : Number`

`width : Number`

`_getViewPaneRect( window ) → Object`

`activateShowListener( id )`

`activateShowListeners()`

`addShowListener( listener ) → Object`

`attach( elementOrSelection, [ options ] )`

`blur()`

`build()`

`deactivateShowListener( id )`

`deactivateShowListeners()`

`deregisterFocusable( element )`

`destroy()`

`getHeight() → Number`

`getWidth() → Number`

`hide()`

`move( top, left )`

`registerFocusable( element )`

`removeShowListener( id )`

`resize( width, height )`

`setTitle( title )`

`setTriangle( side )`

`show()`

private
`_adjustElementRect( elementRect, editorRect )`

private
`_getAlignments( elementRect, panelWidth, panelHeight ) → Object`

`attach( evt )`

`hide( evt )`

`show( evt )`