_source/core/command.js

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