/*
Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved.
For licensing, see LICENSE.html or http://ckeditor.com/license
*/

/**
 * @fileOverview Defines the "virtual" {@link CKEDITOR.commandDefinition} class,
 *		which contains the defintion of a command. This file is for
 *		documentation purposes only.
 */

/**
 * (Virtual Class) Do not call this constructor. This class is not really part
 * of the API.
 * @name CKEDITOR.commandDefinition
 * @class Virtual class that illustrates the features of command objects to be
 *		passed to the {@link CKEDITOR.editor.prototype.addCommand} function.
 * @example
 */

 /**
 * The function to be fired when the commend is executed.
 * @name CKEDITOR.commandDefinition.prototype.exec
 * @function
 * @param {CKEDITOR.editor} editor The editor within which run the command.
 * @param {Object} [data] Additional data to be used to execute the command.
 * @returns {Boolean} Whether the command has been successfully executed.
 *		Defaults to "true", if nothing is returned.
 * @example
 * editorInstance.addCommand( 'sample',
 * {
 *     exec : function( editor )
 *     {
 *         alert( 'Executing a command for the editor name "' + editor.name + '"!' );
 *     }
 * });
 */

/**
 * Whether the command need to be hooked into the redo/undo system.
 * @name  CKEDITOR.commandDefinition.prototype.canUndo
 * @type {Boolean}
 * @default true
 * @field
 * @example
 * editorInstance.addCommand( 'alertName',
 * {
 *     exec : function( editor )
 *     {
 *         alert( editor.name );
 *     },
 *     canUndo : false    // No support for undo/redo
 * });
 */

/**
 * Whether the command is asynchronous, which means that the
 * {@link CKEDITOR.editor#event:afterCommandExec} event will be fired by the
 * command itself manually, and that the return value of this command is not to
 * be returned by the {@link CKEDITOR.command#exec} function.
 * @name  CKEDITOR.commandDefinition.prototype.async
 * @default false
 * @type {Boolean}
 * @example
 * editorInstance.addCommand( 'loadOptions',
 * {
 *     exec : function( editor )
 *     {
 *         // Asynchronous operation below.
 *         CKEDITOR.ajax.loadXml( 'data.xml', function()
 *             {
 *                 editor.fire( 'afterCommandExec' );
 *             ));
 *     },
 *     async : true    // The command need some time to complete after exec function returns.
 * });
 */

/**
 * Whether the command should give focus to the editor before execution.
 * @name  CKEDITOR.commandDefinition.prototype.editorFocus
 * @type {Boolean}
 * @default true
 * @see CKEDITOR.command#editorFocus
 * @example
 * editorInstance.addCommand( 'maximize',
 * {
 *     exec : function( editor )
 *     {
 *         // ...
 *     },
 *     editorFocus : false    // The command doesn't require focusing the editing document.
 * });
 */


/**
 * Whether the command state should be set to {@link CKEDITOR.TRISTATE_DISABLED} on startup.
 * @name  CKEDITOR.commandDefinition.prototype.startDisabled
 * @type {Boolean}
 * @default false
 * @example
 * editorInstance.addCommand( 'unlink',
 * {
 *     exec : function( editor )
 *     {
 *         // ...
 *     },
 *     startDisabled : true    // Command is unavailable until selection is inside a link.
 * });
 */

/**
 * The editor modes within which the command can be executed. The execution
 * will have no action if the current mode is not listed in this property.
 * @name  CKEDITOR.commandDefinition.prototype.modes
 * @type Object
 * @default { wysiwyg : 1 }
 * @see CKEDITOR.command#modes
 * @example
 * editorInstance.addCommand( 'link',
 * {
 *     exec : function( editor )
 *     {
 *         // ...
 *     },
 *     modes : { wysiwyg : 1 }    // Command is available in wysiwyg mode only.
 * });
 */