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