_source/core/commanddefinition.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  * @fileOverview Defines the "virtual" {@link CKEDITOR.commandDefinition} class,\r
   8  *              which contains the defintion of a command. This file is for\r
   9  *              documentation purposes only.\r
  10  */\r
  11 \r
  12 /**\r
  13  * (Virtual Class) Do not call this constructor. This class is not really part\r
  14  * of the API.\r
  15  * @name CKEDITOR.commandDefinition\r
  16  * @class Virtual class that illustrates the features of command objects to be\r
  17  *              passed to the {@link CKEDITOR.editor.prototype.addCommand} function.\r
  18  * @example\r
  19  */\r
  20 \r
  21  /**\r
  22  * The function to be fired when the commend is executed.\r
  23  * @name CKEDITOR.commandDefinition.prototype.exec\r
  24  * @function\r
  25  * @param {CKEDITOR.editor} editor The editor within which run the command.\r
  26  * @param {Object} [data] Additional data to be used to execute the command.\r
  27  * @returns {Boolean} Whether the command has been successfully executed.\r
  28  *              Defaults to "true", if nothing is returned.\r
  29  * @example\r
  30  * editorInstance.addCommand( 'sample',\r
  31  * {\r
  32  *     exec : function( editor )\r
  33  *     {\r
  34  *         alert( 'Executing a command for the editor name "' + editor.name + '"!' );\r
  35  *     }\r
  36  * });\r
  37  */\r
  38 \r
  39 /**\r
  40  * Whether the command need to be hooked into the redo/undo system.\r
  41  * @name  CKEDITOR.commandDefinition.prototype.canUndo\r
  42  * @type {Boolean}\r
  43  * @default true\r
  44  * @field\r
  45  * @example\r
  46  * editorInstance.addCommand( 'alertName',\r
  47  * {\r
  48  *     exec : function( editor )\r
  49  *     {\r
  50  *         alert( editor.name );\r
  51  *     },\r
  52  *     canUndo : false    // No support for undo/redo\r
  53  * });\r
  54  */\r
  55 \r
  56 /**\r
  57  * Whether the command is asynchronous, which means that the\r
  58  * {@link CKEDITOR.editor#event:afterCommandExec} event will be fired by the\r
  59  * command itself manually, and that the return value of this command is not to\r
  60  * be returned by the {@link CKEDITOR.command#exec} function.\r
  61  * @name  CKEDITOR.commandDefinition.prototype.async\r
  62  * @default false\r
  63  * @type {Boolean}\r
  64  * @example\r
  65  * editorInstance.addCommand( 'loadOptions',\r
  66  * {\r
  67  *     exec : function( editor )\r
  68  *     {\r
  69  *         // Asynchronous operation below.\r
  70  *         CKEDITOR.ajax.loadXml( 'data.xml', function()\r
  71  *             {\r
  72  *                 editor.fire( 'afterCommandExec' );\r
  73  *             ));\r
  74  *     },\r
  75  *     async : true    // The command need some time to complete after exec function returns.\r
  76  * });\r
  77  */\r
  78 \r
  79 /**\r
  80  * Whether the command should give focus to the editor before execution.\r
  81  * @name  CKEDITOR.commandDefinition.prototype.editorFocus\r
  82  * @type {Boolean}\r
  83  * @default true\r
  84  * @see CKEDITOR.command#editorFocus\r
  85  * @example\r
  86  * editorInstance.addCommand( 'maximize',\r
  87  * {\r
  88  *     exec : function( editor )\r
  89  *     {\r
  90  *         // ...\r
  91  *     },\r
  92  *     editorFocus : false    // The command doesn't require focusing the editing document.\r
  93  * });\r
  94  */\r
  95 \r
  96 \r
  97 /**\r
  98  * Whether the command state should be set to {@link CKEDITOR.TRISTATE_DISABLED} on startup.\r
  99  * @name  CKEDITOR.commandDefinition.prototype.startDisabled\r
 100  * @type {Boolean}\r
 101  * @default false\r
 102  * @example\r
 103  * editorInstance.addCommand( 'unlink',\r
 104  * {\r
 105  *     exec : function( editor )\r
 106  *     {\r
 107  *         // ...\r
 108  *     },\r
 109  *     startDisabled : true    // Command is unavailable until selection is inside a link.\r
 110  * });\r
 111  */\r
 112 \r
 113 /**\r
 114  * The editor modes within which the command can be executed. The execution\r
 115  * will have no action if the current mode is not listed in this property.\r
 116  * @name  CKEDITOR.commandDefinition.prototype.modes\r
 117  * @type Object\r
 118  * @default { wysiwyg : 1 }\r
 119  * @see CKEDITOR.command#modes\r
 120  * @example\r
 121  * editorInstance.addCommand( 'link',\r
 122  * {\r
 123  *     exec : function( editor )\r
 124  *     {\r
 125  *         // ...\r
 126  *     },\r
 127  *     modes : { wysiwyg : 1 }    // Command is available in wysiwyg mode only.\r
 128  * });\r
 129  */\r