CKEDITOR.ui
Contains UI features related to an editor instance.
Filtering
Properties
-
_ : Object
private
Object used to store private stuff.
Defaults to
{handlers: {}}
Static properties
-
useCapture : Boolean
mixed static
Methods
-
constructor( editor ) → ui
Creates a
ui
class instance. -
add( name, type, definition )
Adds a UI item to the items collection. These items can be later used in the interface.
// Add a new button named 'MyBold'. editorInstance.ui.add( 'MyBold', CKEDITOR.UI_BUTTON, { label: 'My Bold', command: 'bold' } );
Parameters
name : String
The UI item name.
type : Object
The item type.
definition : Object
The item definition. The properties of this object depend on the item type.
-
addButton( name, definition )
Adds a button definition to the UI elements list.
editorInstance.ui.addButton( 'MyBold', { label: 'My Bold', command: 'bold', toolbar: 'basicstyles,1' } );
Parameters
name : String
The button name.
definition : Object
The button definition.
Propertieslabel : String
The textual part of the button (if visible) and its tooltip.
command : String
The command to be executed once the button is activated.
toolbar : String
The toolbar group into which the button will be added. An optional index value (separated by a comma) determines the button position within the group.
icon : String
The path to a custom icon or icon name registered by another plugin. Custom icon paths are supported since the 4.9.0 version.
To use icon registered by another plugin, icon parameter should be used like:
editor.ui.addButton( 'my_button', { icon: 'Link' // Uses link icon from Link plugin. } );
If the plugin provides a HiDPI version of an icon, it will be used for HiDPI displays (so defining
iconHiDpi
is not needed in this case).To use a custom icon, the path to the icon should be provided:
editor.ui.addButton( 'my_button', { icon: 'assets/icons/my_button.png' } )
This icon will be used for both standard and HiDPI displays unless
iconHiDpi
is explicitly defined. Important: CKEditor will resolve relative paths based on CKEDITOR.basePath.iconHiDpi : String
The path to the custom HiDPI icon version. Supported since 4.9.0 version. It will be used only in HiDPI environments. The usage is similar to the
icon
parameter:editor.ui.addButton( 'my_button', { iconHiDpi: 'assets/icons/my_button.hidpi.png' } )
hasArrow : String | Boolean
If Boolean, it indicates whether the button should have a dropdown. If a string, it acts as a value of the button's
aria-haspopup
attribute. Since 4.11.0 it supports the string as a value.
-
addHandler( type, handler )
Adds a handler for a UI item type. The handler is responsible for transforming UI item definitions into UI objects.
Parameters
type : Object
The item type.
handler : Object
The handler definition.
-
addRichCombo( name, definition )
Parameters
name : String
definition : Object
-
addToolbarGroup( name, previous, [ subgroupOf ] )
Adds a toolbar group. See CKEDITOR.config.toolbarGroups for more details.
Note: This method will not modify toolbar groups set explicitly by CKEDITOR.config.toolbarGroups. It will only extend the default setting.
Parameters
name : String
Toolbar group name.
previous : Number | String
The name of the toolbar group after which this one should be added or
0
if this group should be the first one.[ subgroupOf ] : String
The name of the parent group.
-
capture()
Register event handler under the capturing stage on supported target.
-
create( name ) → Object
Gets a UI object.
Parameters
name : String
The UI item name.
Returns
Object
The UI element.
-
define( name, meta )
Predefine some intrinsic properties on a specific event name.
Parameters
name : String
The event name
meta : Object
-
Properties
[ errorProof ]
Whether the event firing should catch error thrown from a per listener call.
Defaults to
false
-
fire( eventName, [ data ], [ editor ] ) → Boolean | Object
Fires an specific event in the object. All registered listeners are called at this point.
someObject.on( 'someEvent', function() { ... } ); someObject.on( 'someEvent', function() { ... } ); someObject.fire( 'someEvent' ); // Both listeners are called. someObject.on( 'someEvent', function( event ) { alert( event.data ); // 'Example' } ); someObject.fire( 'someEvent', 'Example' );
Parameters
eventName : String
The event name to fire.
[ data ] : Object
Data to be sent as the CKEDITOR.eventInfo.data when calling the listeners.
[ editor ] : editor
The editor instance to send as the CKEDITOR.eventInfo.editor when calling the listener.
Returns
Boolean | Object
A boolean indicating that the event is to be canceled, or data returned by one of the listeners.
-
fireOnce( eventName, [ data ], [ editor ] ) → Boolean | Object
Fires an specific event in the object, releasing all listeners registered to that event. The same listeners are not called again on successive calls of it or of fire.
someObject.on( 'someEvent', function() { ... } ); someObject.fire( 'someEvent' ); // Above listener called. someObject.fireOnce( 'someEvent' ); // Above listener called. someObject.fire( 'someEvent' ); // No listeners called.
Parameters
eventName : String
The event name to fire.
[ data ] : Object
Data to be sent as the CKEDITOR.eventInfo.data when calling the listeners.
[ editor ] : editor
The editor instance to send as the CKEDITOR.eventInfo.editor when calling the listener.
Returns
Boolean | Object
A booloan indicating that the event is to be canceled, or data returned by one of the listeners.
-
get( name )
Retrieves the created UI objects by name.
Parameters
name : String
The name of the UI definition.
-
hasListeners( eventName ) → Boolean
Checks if there is any listener registered to a given event.
var myListener = function() { ... }; someObject.on( 'someEvent', myListener ); alert( someObject.hasListeners( 'someEvent' ) ); // true alert( someObject.hasListeners( 'noEvent' ) ); // false
Parameters
eventName : String
The event name.
Returns
Boolean
-
on( eventName, listenerFunction, [ scopeObj ], [ listenerData ], [ priority ] ) → Object
Registers a listener to a specific event in the current object.
someObject.on( 'someEvent', function() { alert( this == someObject ); // true } ); someObject.on( 'someEvent', function() { alert( this == anotherObject ); // true }, anotherObject ); someObject.on( 'someEvent', function( event ) { alert( event.listenerData ); // 'Example' }, null, 'Example' ); someObject.on( 'someEvent', function() { ... } ); // 2nd called someObject.on( 'someEvent', function() { ... }, null, null, 100 ); // 3rd called someObject.on( 'someEvent', function() { ... }, null, null, 1 ); // 1st called
Parameters
eventName : String
The event name to which listen.
listenerFunction : Function
The function listening to the event. A single CKEDITOR.eventInfo object instanced is passed to this function containing all the event data.
[ scopeObj ] : Object
The object used to scope the listener call (the
this
object). If omitted, the current object is used.[ listenerData ] : Object
Data to be sent as the CKEDITOR.eventInfo.listenerData when calling the listener.
[ priority ] : Number
The listener priority. Lower priority listeners are called first. Listeners with the same priority value are called in registration order.
Defaults to
10
Returns
Object
An object containing the
removeListener
function, which can be used to remove the listener at any time.
-
once()
Similiar with on but the listener will be called only once upon the next event firing.
-
Remove all existing listeners on this object, for cleanup purpose.
-
removeListener( eventName, listenerFunction )
Unregisters a listener function from being called at the specified event. No errors are thrown if the listener has not been registered previously.
var myListener = function() { ... }; someObject.on( 'someEvent', myListener ); someObject.fire( 'someEvent' ); // myListener called. someObject.removeListener( 'someEvent', myListener ); someObject.fire( 'someEvent' ); // myListener not called.
Parameters
eventName : String
The event name.
listenerFunction : Function
The listener function to unregister.
-
Returns the unique DOM element that represents one editor's UI part, also known as "space". There are 3 main editor spaces available:
top
,contents
andbottom
and their availability depends on editor type.// Hide the bottom space in the UI. var bottom = editor.ui.space( 'bottom' ); bottom.setStyle( 'display', 'none' );
Parameters
name : String
The name of the space.
Returns
element
The element that represents the space.
-
spaceId( name ) → String
Returns the HTML ID for a specific UI space name.
Parameters
name : String
The name of the space.
Returns
String
The ID of an element representing this space in the DOM.
Static methods
-
implementOn( targetObject )
mixed static
Implements the CKEDITOR.event features in an object.
var myObject = { message: 'Example' }; CKEDITOR.event.implementOn( myObject ); myObject.on( 'testEvent', function() { alert( this.message ); } ); myObject.fire( 'testEvent' ); // 'Example'
Parameters
targetObject : Object
The object into which implement the features.