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

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

See source

Defaults to {}
editor : Object

The editor for this balloon panel.

See source
focusables : Object

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

See source

Defaults to {}
height : String

The default height of the balloon panel.

See source

Defaults to 'auto'
parts : Object

The UI elements of the balloon panel.

See source

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.

See source

Defaults to {visible: false}
showListeners : Object

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

See source

Defaults to {}
templateDefinitions : Object

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

See source
templates : Object

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

See source

Defaults to {}
triangleHeight : Number

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

See source

Defaults to 20
triangleMinDistance : Number

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

See source

Defaults to 40
triangleWidth : Number

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

See source

Defaults to 20
width : Number

The default width of the balloon panel.

See source

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 )

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

See source

Parameters

id : Object
activateShowListeners()

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

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

See source

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.

See source

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
blur()

Moves the focus back to the editor's editable.

See source
build()

Builds the UI of the balloon panel.

See source
deactivateShowListener( id )

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

See source

Parameters

id : Object
deactivateShowListeners()

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

See source
deregisterFocusable( element )

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

See source

Parameters

element : element

An element to be registered.
destroy()

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

See source
getHeight() → Number

Returns the balloon panel height.

See source

Returns

Number
getWidth() → Number

Returns the balloon panel width.

See source

Returns

Number
hide()

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

See source
move( top, left )

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

See source

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.

See source

Parameters

element : element

An element to be registered.
removeShowListener( id )

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

See source

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.

See source

Parameters

width : Number

height : Number
setTitle( title )

Sets the balloon panel title.

See source

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.

See source

Parameters

side : String

One of 'left', 'right', 'top' or 'bottom'.
show()

Shows the balloon panel.

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

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

See source

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.

See source

Parameters

evt : eventInfo
hide( evt )

Event fired when the balloon panel is hidden.

See source

Parameters

evt : eventInfo
show( evt )

Event fired when the balloon panel is shown.

See source

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

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

Parameters

_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()`

`_adjustElementRect( elementRect, editorRect )`

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

`attach( evt )`

`hide( evt )`

`show( evt )`