_source/core/command.js

   1 /*
   2 Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved.
   3 For licensing, see LICENSE.html or http://ckeditor.com/license
   4 */
   5
   6 /**
   7  * Creates a command class instance.
   8  * @class Represents a command that can be executed on an editor instance.
   9  * @param {CKEDITOR.editor} editor The editor instance this command will be
  10  *              related to.
  11  * @param {CKEDITOR.commandDefinition} commandDefinition The command
  12  *              definition.
  13  * @augments CKEDITOR.event
  14  * @example
  15  * var command = new CKEDITOR.command( editor,
  16  *     {
  17  *         exec : function( editor )
  18  *         {
  19  *             alert( editor.document.getBody().getHtml() );
  20  *         }
  21  *     });
  22  */
  23 CKEDITOR.command = function( editor, commandDefinition )
  24 {
  25         /**
  26          * Lists UI items that are associated to this command. This list can be
  27          * used to interact with the UI on command execution (by the execution code
  28          * itself, for example).
  29          * @type Array
  30          * @example
  31          * alert( 'Number of UI items associated to this command: ' + command.<b>uiItems</b>.length );
  32          */
  33         this.uiItems = [];
  34
  35         /**
  36          * Executes the command.
  37          * @param {Object} [data] Any data to pass to the command. Depends on the
  38          *              command implementation and requirements.
  39          * @returns {Boolean} A boolean indicating that the command has been
  40          *      successfully executed.
  41          * @example
  42          * command.<b>exec()</b>;  // The command gets executed.
  43          */
  44         this.exec = function( data )
  45         {
  46                 if ( this.state == CKEDITOR.TRISTATE_DISABLED )
  47                         return false;
  48
  49                 if ( this.editorFocus )     // Give editor focus if necessary (#4355).
  50                         editor.focus();
  51
  52                 return ( commandDefinition.exec.call( this, editor, data ) !== false );
  53         };
  54
  55         CKEDITOR.tools.extend( this, commandDefinition,
  56                 // Defaults
  57                 /** @lends CKEDITOR.command.prototype */
  58                 {
  59                         /**
  60                          * The editor modes within which the command can be executed. The
  61                          * execution will have no action if the current mode is not listed
  62                          * in this property.
  63                          * @type Object
  64                          * @default { wysiwyg : 1 }
  65                          * @see CKEDITOR.editor.prototype.mode
  66                          * @example
  67                          * // Enable the command in both WYSIWYG and Source modes.
  68                          * command.<b>modes</b> = { wysiwyg : 1, source : 1 };
  69                          * @example
  70                          * // Enable the command in Source mode only.
  71                          * command.<b>modes</b> = { source : 1 };
  72                          */
  73                         modes : { wysiwyg : 1 },
  74
  75                         /**
  76                          * Indicates that the editor will get the focus before executing
  77                          * the command.
  78                          * @type Boolean
  79                          * @default true
  80                          * @example
  81                          * // Do not force the editor to have focus when executing the command.
  82                          * command.<b>editorFocus</b> = false;
  83                          */
  84                         editorFocus : 1,
  85
  86                         /**
  87                          * Indicates the editor state. Possible values are:
  88                          * <ul>
  89                          * <li>{@link CKEDITOR.TRISTATE_DISABLED}: the command is
  90                          *              disabled. It's execution will have no effect. Same as
  91                          *              {@link disable}.</li>
  92                          * <li>{@link CKEDITOR.TRISTATE_ON}: the command is enabled
  93                          *              and currently active in the editor (for context sensitive commands,
  94                          *              for example).</li>
  95                          * <li>{@link CKEDITOR.TRISTATE_OFF}: the command is enabled
  96                          *              and currently inactive in the editor (for context sensitive
  97                          *              commands, for example).</li>
  98                          * </ul>
  99                          * Do not set this property directly, using the {@link #setState}
 100                          * method instead.
 101                          * @type Number
 102                          * @default {@link CKEDITOR.TRISTATE_OFF}
 103                          * @example
 104                          * if ( command.<b>state</b> == CKEDITOR.TRISTATE_DISABLED )
 105                          *     alert( 'This command is disabled' );
 106                          */
 107                         state : CKEDITOR.TRISTATE_OFF
 108                 });
 109
 110         // Call the CKEDITOR.event constructor to initialize this instance.
 111         CKEDITOR.event.call( this );
 112 };
 113
 114 CKEDITOR.command.prototype =
 115 {
 116         /**
 117          * Enables the command for execution. The command state (see
 118          * {@link CKEDITOR.command.prototype.state}) available before disabling it
 119          * is restored.
 120          * @example
 121          * command.<b>enable()</b>;
 122          * command.exec();    // Execute the command.
 123          */
 124         enable : function()
 125         {
 126                 if ( this.state == CKEDITOR.TRISTATE_DISABLED )
 127                         this.setState( ( !this.preserveState || ( typeof this.previousState == 'undefined' ) ) ? CKEDITOR.TRISTATE_OFF : this.previousState );
 128         },
 129
 130         /**
 131          * Disables the command for execution. The command state (see
 132          * {@link CKEDITOR.command.prototype.state}) will be set to
 133          * {@link CKEDITOR.TRISTATE_DISABLED}.
 134          * @example
 135          * command.<b>disable()</b>;
 136          * command.exec();    // "false" - Nothing happens.
 137          */
 138         disable : function()
 139         {
 140                 this.setState( CKEDITOR.TRISTATE_DISABLED );
 141         },
 142
 143         /**
 144          * Sets the command state.
 145          * @param {Number} newState The new state. See {@link #state}.
 146          * @returns {Boolean} Returns "true" if the command state changed.
 147          * @example
 148          * command.<b>setState( CKEDITOR.TRISTATE_ON )</b>;
 149          * command.exec();    // Execute the command.
 150          * command.<b>setState( CKEDITOR.TRISTATE_DISABLED )</b>;
 151          * command.exec();    // "false" - Nothing happens.
 152          * command.<b>setState( CKEDITOR.TRISTATE_OFF )</b>;
 153          * command.exec();    // Execute the command.
 154          */
 155         setState : function( newState )
 156         {
 157                 // Do nothing if there is no state change.
 158                 if ( this.state == newState )
 159                         return false;
 160
 161                 this.previousState = this.state;
 162
 163                 // Set the new state.
 164                 this.state = newState;
 165
 166                 // Fire the "state" event, so other parts of the code can react to the
 167                 // change.
 168                 this.fire( 'state' );
 169
 170                 return true;
 171         },
 172
 173         /**
 174          * Toggles the on/off (active/inactive) state of the command. This is
 175          * mainly used internally by context sensitive commands.
 176          * @example
 177          * command.<b>toggleState()</b>;
 178          */
 179         toggleState : function()
 180         {
 181                 if ( this.state == CKEDITOR.TRISTATE_OFF )
 182                         this.setState( CKEDITOR.TRISTATE_ON );
 183                 else if ( this.state == CKEDITOR.TRISTATE_ON )
 184                         this.setState( CKEDITOR.TRISTATE_OFF );
 185         }
 186 };
 187
 188 CKEDITOR.event.implementOn( CKEDITOR.command.prototype, true );
 189
 190 /**
 191  * Indicates the previous command state.
 192  * @name CKEDITOR.command.prototype.previousState
 193  * @type Number
 194  * @see #state
 195  * @example
 196  * alert( command.<b>previousState</b> );
 197  */
 198
 199 /**
 200  * Fired when the command state changes.
 201  * @name CKEDITOR.command#state
 202  * @event
 203  * @example
 204  * command.on( <b>'state'</b> , function( e )
 205  *     {
 206  *         // Alerts the new state.
 207  *         alert( this.state );
 208  *     });
 209  */