Report an issue
Class

CKEDITOR.plugins.widget

class since 4.3.0

An instance of a widget. Together with CKEDITOR.plugins.widget.repository these two classes constitute the core of the Widget System.

Note that neither the repository nor the widget instances can be created by using their constructors. A repository instance is automatically set up by the Widget plugin and is accessible under CKEDITOR.editor.widgets, while widget instances are created and destroyed by the repository.

To create a widget, first you need to register its definition:

editor.widgets.add( 'simplebox', {
    upcast: function( element ) {
        // Defines which elements will become widgets.
        if ( element.hasClass( 'simplebox' ) )
            return true;
    },
    init: function() {
        // ...
    }
} );

Once the widget definition is registered, widgets will be automatically created when loading data:

editor.setData( '<div class="simplebox">foo</div>', function() {
    console.log( editor.widgets.instances ); // -> An object containing one instance.
} );

It is also possible to create instances during runtime by using a command (if a CKEDITOR.plugins.widget.definition.template property was defined):

// You can execute an automatically defined command to
// insert a new simplebox widget or edit the one currently focused.
editor.execCommand( 'simplebox' );

Note: Since CKEditor 4.5.0 widget's startupData can be passed as the command argument:

editor.execCommand( 'simplebox', {
    startupData: {
        align: 'left'
    }
} );

A widget can also be created in a completely custom way:

var element = editor.document.createElement( 'div' );
editor.insertElement( element );
var widget = editor.widgets.initOn( element, 'simplebox' );

Filtering

Properties

  • allowedContent : allowedContentRules

    HTML code that can be generated by this feature.

    For example a basic image feature (image button displaying the image dialog window) may allow 'img[!src,alt,width,height]'.

    During the feature activation this value is passed to CKEDITOR.filter.allow.

    Defaults to null

  • button : String

    The label for the widget toolbar button.

    editor.widgets.add( 'simplebox', {
        button: 'Create a simple box'
    } );
    
    editor.widgets.add( 'simplebox', {
        button: editor.lang.simplebox.title
    } );
    
  • contentForms : Object

    Feature content forms to be registered in the CKEDITOR.editor.filter during the feature activation.

    See CKEDITOR.filter.addContentForms for more details.

    Defaults to null

  • contentTransformations : Object

    Transformations (usually for content generated by this feature, but not necessarily) that will be registered in the CKEDITOR.editor.filter during the feature activation.

    See CKEDITOR.filter.addTransformations for more details.

    Defaults to null

  • data : Object

    readonly

    Widget's data object.

    The data can only be set by using the setData method. Changes made to the data fire the data event.

  • dataReady : Boolean

    readonly

    Indicates if a widget is data-ready. Set to true when data from all sources (CKEDITOR.plugins.widget.definition.defaults, set in the init method, loaded from the widget's element and startup data coming from the constructor) are finally loaded. This is immediately followed by the first data.

    Defaults to false

  • defaults : Object

    The data object which will be used to populate the data of a newly created widget. See CKEDITOR.plugins.widget.data.

    defaults: {
        showCaption: true,
        align: 'none'
    }
    
  • definition : definition

    readonly

    The widget definition from which this instance was created.

  • dialog : String

    The name of a dialog window which will be opened on CKEDITOR.plugins.widget.edit. If not defined, then the CKEDITOR.plugins.widget.edit method will not perform any action and widget's command will insert a new widget without opening a dialog window first.

  • downcast : String | Function

    The function to be used to downcast this widget or a name of the downcast option from the downcasts object.

    The downcast function will be executed in the CKEDITOR.plugins.widget context and with widgetElement (CKEDITOR.htmlParser.element) argument which is the widget's main element.

    The function may return an instance of the CKEDITOR.htmlParser.node class if the widget needs to be downcasted to a different node than the widget's main element.

  • downcasts : Object

    The object containing functions which can be used to downcast this widget. Only the one pointed by the downcast property will be used.

    In most cases it is appropriate to use downcast directly, because majority of widgets have just one variant of downcasting (or none at all). However, in some cases the widget author may want to expose more than one variant and then this property may be used.

    downcasts: {
        // This downcast may transform the widget into the figure element.
        figure: function() {
            // ...
        },
        // This downcast may transform the widget into the image element with data-* attributes.
        image: function() {
            // ...
        }
    }
    
    // Then, the widget user may choose one of the downcast options when setting up his editor.
    editor.on( 'widgetDefinition', function( evt ) {
        if ( evt.data.name == 'image' )
                evt.data.downcast = 'figure';
    } );
    
  • draggable : Boolean

    Whether widget should be draggable. Defaults to true. If set to false drag handler will not be displayed when hovering widget.

  • edit : Function

    If set, it will be added as the CKEDITOR.plugins.widget.edit event listener. This means that it will be executed when a widget is being edited. See the CKEDITOR.plugins.widget.edit method.

  • editables : Object

    An object containing definitions of nested editables (editable name => CKEDITOR.plugins.widget.nestedEditable.definition). Note that editables have to be defined in the same order as they are in DOM / template. Otherwise errors will occur when nesting widgets inside each other.

    editables: {
        header: 'h1',
        content: {
            selector: 'div.content',
            allowedContent: 'p strong em; a[!href]'
        }
    }
    
  • editor : editor

    readonly

    The editor instance.

  • element : element

    readonly

    The widget element — the element on which the widget was initialized.

  • focusedEditable : nestedEditable

    readonly

    The nested editable element which is currently focused.

  • getLabel : Function

    The function used to obtain an accessibility label for the widget. It might be used to make the widget labels as precise as possible, since it has access to the widget instance.

    If not specified, the default implementation will use the pathName or the main element tag name.

  • id : Number

    readonly

    This widget's unique (per editor instance) ID.

  • init : Function

    The method executed while initializing a widget, after a widget instance is created, but before it is ready. It is executed before the first CKEDITOR.plugins.widget.data is fired so it is common to use the init method to populate widget data with information loaded from the DOM, like for exmaple:

    init: function() {
        this.setData( 'width', this.element.getStyle( 'width' ) );
    
        if ( this.parts.caption.getStyle( 'display' ) != 'none' )
            this.setData( 'showCaption', true );
    }
    
  • inited : Boolean

    readonly

    Whether a widget instance was initialized. This means that:

    • An instance was created,
    • Its properties were set,
    • The init method was executed.

    Note: The first data event could not be fired yet which means that the widget's DOM has not been set up yet. Wait for the ready event to be notified when a widget is fully initialized and ready.

    Note: Use the isInited method to check whether a widget is initialized and has not been destroyed.

    Defaults to false

  • inline : Boolean

    readonly

    Whether this widget is an inline widget (based on an inline element unless forced otherwise by CKEDITOR.plugins.widget.definition.inline).

    Note: This option does not allow to turn a block element into an inline widget. However, it makes it possible to turn an inline element into a block widget or to force a correct type in case when automatic recognition fails.

  • insert : Function

    The method to be executed when the widget's command is executed in order to insert a new widget (widget of this type is not focused). If not defined, then the default action will be performed which means that:

    Parameters

    options : Object

    Options object added in 4.11.0.

    Properties
    editor : editor

    The editor where the widget is going to be inserted to.

    [ commandData ] : Object

    Command data passed to the invoking command, if any.

  • mask : Boolean

    If set to true, the widget's element will be covered with a transparent mask. This will prevent its content from being clickable, which matters in case of special elements like embedded Flash or iframes that generate a separate "context".

  • name : String

    Widget definition name. It is automatically set when the definition is registered.

  • parts : Object

    readonly

    An object of widget component elements.

    For every partName => selector pair in CKEDITOR.plugins.widget.definition.parts, one partName => element pair is added to this object during the widget initialization.

  • pathName : String

    The widget name displayed in the elements path.

  • ready : Boolean

    readonly

    Whether a widget instance is ready. This means that the widget is inited and that its DOM was finally set up.

    Note: Use the isReady method to check whether a widget is ready and has not been destroyed.

    Defaults to false

  • repository : repository

    readonly

    Link to the widget repository which created this instance.

  • requiredContent : contentRule

    Minimal HTML code that this feature must be allowed to generate in order to work.

    For example a basic image feature (image button displaying the image dialog window) needs 'img[src,alt]' in order to be activated.

    During the feature validation this value is passed to CKEDITOR.filter.check.

    If this value is not provided, a feature will be always activated.

    Defaults to null

  • styleToAllowedContentRules : Function

    since 4.4.0

    Function transforming custom widget's CKEDITOR.style instance into CKEDITOR.filter.allowedContentRules. It may be used when a static styleableElements property is not enough to inform the CKEDITOR.filter what HTML features should be enabled when allowing the given style.

    In most cases, when style's classes just have to be added to element name(s) used by the widget element, it is recommended to use simpler styleableElements property.

    In order to get parsed classes from the style definition you can use CKEDITOR.style.customHandlers.widget.getClassesArray.

    For example, if you want to use the object format of allowed content rules, to specify match validator, your implementation could look like this:

    editor.widgets.add( 'customWidget', {
        // ...
    
        styleToAllowedContentRules: funciton( style ) {
            // Retrieve classes defined in the style.
            var classes = style.getClassesArray();
    
            // Do something crazy - for example return allowed content rules in object format,
            // with custom match property and propertiesOnly flag.
            return {
                h1: {
                    match: isWidgetElement,
                    propertiesOnly: true,
                    classes: classes
                }
            };
        }
    } );
    

    Parameters

    style : widget

    The style to be transformed.

  • styleableElements : String

    since 4.4.0

    Names of element(s) (separated by spaces) for which the CKEDITOR.filter should allow classes defined in the widget styles. For example if your widget is upcasted from a simple <div> element, then in order to make it styleable you can set:

    editor.widgets.add( 'customWidget', {
        upcast: function( element ) {
            return element.name == 'div';
        },
    
        // ...
    
        styleableElements: 'div'
    } );
    

    Then, when the following style is defined:

    {
        name: 'Thick border', type: 'widget', widget: 'customWidget',
        attributes: { 'class': 'thickBorder' }
    }
    

    a rule allowing the thickBorder class for div elements will be registered in the CKEDITOR.filter.

    If you need to have more freedom when transforming widget style to allowed content rules, you can use the styleToAllowedContentRules callback.

  • template : template

    readonly

    The template which will be used to create a new widget element (when the widget's command is executed). It will be populated with default values.

  • upcast : String | Function

    The function to be used to upcast an element to this widget or a comma-separated list of upcast methods from the upcasts object.

    The upcast function is not executed in the widget context (because the widget does not exist yet), however, it is executed in the widget's definition context. Two arguments are passed to the upcast function:

    • element (CKEDITOR.htmlParser.element) – The element to be checked.
    • data (Object) – The object which can be extended with data which will then be passed to the widget.

    An element will be upcasted if a function returned true or an instance of a CKEDITOR.htmlParser.element if upcasting meant DOM structure changes (in this case the widget will be initialized on the returned element).

  • upcastPriority : Number

    since 4.5.0

    The upcast method(s) priority. The upcast with a lower priority number will be called before the one with a higher number. The default priority is 10.

    Defaults to 10

  • upcasts : Object

    The object containing functions which can be used to upcast this widget. Only those pointed by the upcast property will be used.

    In most cases it is appropriate to use upcast directly, because majority of widgets need just one method. However, in some cases the widget author may want to expose more than one variant and then this property may be used.

    upcasts: {
        // This function may upcast only figure elements.
        figure: function() {
            // ...
        },
        // This function may upcast only image elements.
        image: function() {
            // ...
        },
        // More variants...
    }
    
    // Then, widget user may choose which upcast methods will be enabled.
    editor.on( 'widgetDefinition', function( evt ) {
        if ( evt.data.name == 'image' )
                evt.data.upcast = 'figure,image'; // Use both methods.
    } );
    
  • wrapper : element

    readonly

    The widget wrapper — a non-editable div or span element (depending on inline) which is a parent of the element and widget compontents like the drag handler and the mask. It is the outermost widget element.

Static properties

  • WRAPPER_CLASS_PREFIX : String

    since 4.6.0 readonly static

    Prefix added to wrapper classes. Each class added to the widget element by the addClass method will also be added to the wrapper prefixed with it.

    Defaults to 'cke_widget_wrapper_'

  • useCapture : Boolean

    mixed static

Methods

  • constructor( widgetsRepo, id, element, widgetDef, [ startupData ] ) → widget

    Creates an instance of the widget class. Do not use it directly, but instead initialize widgets by using the CKEDITOR.plugins.widget.repository.initOn method or by the upcasting system.

    Parameters

    widgetsRepo : repository
    id : Number

    Unique ID of this widget instance.

    element : element

    The widget element.

    widgetDef : definition

    Widget's registered definition.

    [ startupData ] : Object

    Initial widget data. This data object will overwrite the default data and the data loaded from the DOM.

    Returns

    widget
  • addClass( className )

    since 4.4.0

    Adds a class to the widget element. This method is used by the applyStyle method and should be overridden by widgets which should handle classes differently (e.g. add them to other elements).

    Since 4.6.0 this method also adds a corresponding class prefixed with WRAPPER_CLASS_PREFIX to the widget wrapper element.

    Note: This method should not be used directly. Use the setData method to set the classes property. Read more in the setData documentation.

    See also: removeClass, hasClass, getClasses.

    Parameters

    className : String

    The class name to be added.

  • applyStyle( style )

    since 4.4.0

    Applies the specified style to the widget. It is highly recommended to use the CKEDITOR.editor.applyStyle or CKEDITOR.style.apply methods instead of using this method directly, because unlike editor's and style's methods, this one does not perform any checks.

    By default this method handles only classes defined in the style. It clones existing classes which are stored in the widget data's classes property, adds new classes, and calls the setData method if at least one new class was added. Then, using the data event listener widget applies modifications passing new classes to the addClass method.

    If you need to handle classes differently than in the default way, you can override the addClass and related methods. You can also handle other style properties than classes by overriding this method.

    See also: checkStyleActive, removeStyle.

    Parameters

    style : style

    The custom widget style to be applied.

  • capture()

    Register event handler under the capturing stage on supported target.

  • checkStyleActive( style ) → Boolean

    since 4.4.0

    Checks if the specified style is applied to this widget. It is highly recommended to use the CKEDITOR.style.checkActive method instead of using this method directly, because unlike style's method, this one does not perform any checks.

    By default this method handles only classes defined in the style and passes them to the hasClass method. You can override these methods to handle classes differently or to handle more of the style properties.

    See also: applyStyle, removeStyle.

    Parameters

    style : style

    The custom widget style to be checked.

    Returns

    Boolean

    Whether the style is applied to this widget.

  • 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

  • destroy( [ offline ] )

    Destroys this widget instance.

    Use CKEDITOR.plugins.widget.repository.destroy when possible instead of this method.

    This method fires the {#event-destroy} event.

    Parameters

    [ offline ] : Boolean

    Whether a widget is offline (detached from the DOM tree) — in this case the DOM (attributes, classes, etc.) will not be cleaned up.

  • destroyEditable( editableName, [ offline ] )

    Destroys a nested editable and all nested widgets.

    Parameters

    editableName : String

    Nested editable name.

    [ offline ] : Boolean

    See destroy method.

  • edit() → Boolean

    Starts widget editing.

    This method fires the edit event which may be canceled in order to prevent it from opening a dialog window.

    The dialog window name is obtained from the event's data dialog property or from CKEDITOR.plugins.widget.definition.dialog.

    Returns

    Boolean

    Returns true if a dialog window was opened.

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

  • focus()

    Focuses a widget by selecting it.

  • getClasses() → Object

    since 4.4.0

    Returns widget element classes parsed to an object. This method is used to populate the classes property of widget's data.

    This method reuses CKEDITOR.plugins.widget.repository.parseElementClasses. It should be overriden if a widget should handle classes differently (e.g. on other elements).

    See also: removeClass, addClass, hasClass.

    Returns

    Object
  • hasClass( className, Whether )

    since 4.4.0

    Checks if the widget element has specified class. This method is used by the checkStyleActive method and should be overriden by widgets which should handle classes differently (e.g. on other elements).

    See also: removeClass, addClass, getClasses.

    Parameters

    className : String

    The class to be checked.

    Whether : Boolean

    a widget has specified class.

  • 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
  • initEditable( editableName, definition ) → Boolean

    Initializes a nested editable.

    Note: Only elements from CKEDITOR.dtd.$editable may become editables.

    Parameters

    editableName : String

    The nested editable name.

    definition : definition

    The definition of the nested editable.

    Returns

    Boolean

    Whether an editable was successfully initialized.

  • isInited() → Boolean

    Checks if a widget has already been initialized and has not been destroyed yet.

    See inited for more details.

    Returns

    Boolean
  • isReady() → Boolean

    Checks if a widget is ready and has not been destroyed yet.

    See ready for more details.

    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.

  • removeAllListeners()

    Remove all existing listeners on this object, for cleanup purpose.

  • removeClass( className )

    since 4.4.0

    Removes a class from the widget element. This method is used by the removeStyle method and should be overriden by widgets which should handle classes differently (e.g. on other elements).

    Note: This method should not be used directly. Use the setData method to set the classes property. Read more in the setData documentation.

    See also: hasClass, addClass.

    Parameters

    className : String

    The class to be removed.

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

  • removeStyle( style )

    since 4.4.0

    Removes the specified style from the widget. It is highly recommended to use the CKEDITOR.editor.removeStyle or CKEDITOR.style.remove methods instead of using this method directly, because unlike editor's and style's methods, this one does not perform any checks.

    Read more about how applying/removing styles works in the applyStyle method documentation.

    See also checkStyleActive, applyStyle, getClasses.

    Parameters

    style : style

    The custom widget style to be removed.

  • setData( keyOrData, value ) → widget

    chainable

    Sets widget value(s) in the data object. If the given value(s) modifies current ones, the data event is fired.

    this.setData( 'align', 'left' );
    this.data.align; // -> 'left'
    
    this.setData( { align: 'right', opened: false } );
    this.data.align; // -> 'right'
    this.data.opened; // -> false
    

    Set values are stored in element's attribute (data-cke-widget-data), in a JSON string, therefore data should contain only serializable data.

    Note: A special data property, classes, exists. It contains an object with classes which were returned by the getClasses method during the widget initialization. This property is then used by the applyStyle and removeStyle methods. When it is changed (the reference to object must be changed!), the widget updates its classes by using the addClass and removeClass methods.

    // Adding a new class.
    var classes = CKEDITOR.tools.clone( widget.data.classes );
    classes.newClass = 1;
    widget.setData( 'classes', classes );
    
    // Removing a class.
    var classes = CKEDITOR.tools.clone( widget.data.classes );
    delete classes.newClass;
    widget.setData( 'classes', classes );
    

    Parameters

    keyOrData : String | Object
    value : Object

    Returns

    widget

    this

  • setFocused( selected ) → widget

    chainable

    Changes the widget's focus state. This method is executed automatically after a widget was focused by the focus method or the selection was moved out of the widget.

    This is a low-level method which is not integrated with e.g. the undo manager. Use the focus method instead.

    Parameters

    selected : Boolean

    Whether to select or deselect this widget.

    Returns

    widget

    this

  • setSelected( selected ) → widget

    chainable

    Changes the widget's select state. This method is executed automatically after a widget was selected by the focus method or the selection was moved out of the widget.

    This is a low-level method which is not integrated with e.g. the undo manager. Use the focus method instead or simply change the selection.

    Parameters

    selected : Boolean

    Whether to select or deselect this widget.

    Returns

    widget

    this

  • toFeature() → feature

    Returns a feature that this feature needs to register.

    In some cases, during activation, one feature may need to register another feature. For example a CKEDITOR.ui.button often registers a related command. See CKEDITOR.ui.button.toFeature.

    This method is executed when a feature is passed to the CKEDITOR.editor.addFeature.

    Returns

    feature
  • updateDragHandlerPosition()

    Repositions drag handler according to the widget's element position. Should be called from events, like mouseover.

  • _findOneNotNested( selector ) → element

    since 4.5.0 private

    Looks inside wrapper element to find a node that matches given selector and is not nested in other widget. (https://dev.ckeditor.com/ticket/13334)

    Parameters

    selector : String

    Selector to match.

    Returns

    element

    Matched element or null if a node has not been found.

Static methods

Events

  • blur( evt )

    An event fired when a widget is blurred.

    Parameters

    evt : eventInfo
  • contextMenu( evt )

    An event fired when the context menu is opened for a widget.

    Parameters

    evt : eventInfo
    Properties
    data : Object

    The object containing context menu options to be added for this widget. See CKEDITOR.plugins.contextMenu.addListener.

  • data( evt )

    An event fired when the widget data changed. See the setData method and the data property.

    Parameters

    evt : eventInfo
  • deselect( evt )

    An event fired when a widget is deselected.

    Parameters

    evt : eventInfo
  • destroy( evt )

    An event fired when a widget is about to be destroyed, but before it is fully torn down.

    Parameters

    evt : eventInfo
  • dialog( evt )

    An event fired when a dialog window for widget editing is opened. This event can be canceled in order to handle the editing dialog in a custom manner.

    Parameters

    evt : eventInfo
    Properties
    data : dialog

    The opened dialog window instance.

  • doubleclick( evt )

    An event fired when a widget is double clicked.

    Note: If a default editing action is executed on double click (i.e. a widget has a dialog defined and the doubleclick event was not canceled), this event will be automatically canceled, so a listener added with the default priority (10) will not be executed. Use a listener with low priority (e.g. 5) to be sure that it will be executed.

    widget.on( 'doubleclick', function( evt ) {
        console.log( 'widget#doubleclick' );
    }, null, null, 5 );
    

    If your widget handles double click in a special way (so the default editing action is not executed), make sure you cancel this event, because otherwise it will be propagated to CKEDITOR.editor.doubleclick and another feature may step in (e.g. a Link dialog window may be opened if your widget was inside a link).

    Parameters

    evt : eventInfo
    Properties
    data : Object
    Properties
    element : element

    The double-clicked element.

  • edit( evt )

    An event fired by the edit method. It can be canceled in order to stop the default action (opening a dialog window and/or finalizing widget creation).

    Parameters

    evt : eventInfo
    Properties
    data : Object
    Properties
    dialog : String

    Defaults to CKEDITOR.plugins.widget.definition.dialog and can be changed or set by the listener.

  • focus( evt )

    An event fired when a widget is focused.

    Widget can be focused by executing focus.

    Parameters

    evt : eventInfo
  • key( evt )

    An event fired when a key is pressed on a focused widget. This event is forwarded from the CKEDITOR.editor.key event and has the ability to block editor keystrokes if it is canceled.

    Parameters

    evt : eventInfo
    Properties
    data : Object
    Properties
    keyCode : Number

    A number representing the key code (or combination).

  • ready( evt )

    An event fired when a widget is ready (fully initialized). This event is fired after:

    • init is called,
    • The first data event is fired,
    • A widget is attached to the document.

    Therefore, in case of widget creation with a command which opens a dialog window, this event will be delayed after the dialog window is closed and the widget is finally inserted into the document.

    Note: If your widget does not use automatic dialog window binding (i.e. you open the dialog window manually) or another situation in which the widget wrapper is not attached to document at the time when it is initialized occurs, you need to take care of firing ready yourself.

    See also ready and inited properties, and isReady and isInited methods.

    Parameters

    evt : eventInfo
  • select( evt )

    An event fired when a widget is selected.

    Parameters

    evt : eventInfo