1 /*
  2 Copyright (c) 2003-2012, 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  */
130