[Summary view] [Print] [Text view]

   1  /*

   2  Copyright (c) 2003-2010, 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. It just illustrates the features of command objects to be

  15   *        passed to the {@link CKEDITOR.editor.prototype.addCommand} function.

  16   * @name CKEDITOR.commandDefinition

  17   * @constructor

  18   * @example

  19   */
  20  
  21   /**

  22   * Executes the command.

  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.canUndo

  42   * @type {Boolean} If not defined or 'true' both hook into undo system, set it

  43   *        to 'false' explicitly  keep it out.

  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 the 'afterCommandExec' event

  58   * will be fired by the command itself manually, and the 'exec' function return value

  59   * of this command is not to be returned.

  60   * @name  CKEDITOR.commandDefinition.async

  61   * @type {Boolean} If defined as 'true', the command is asynchronous.

  62   * @example

  63   * editorInstance.addCommand( 'alertName',

  64   * {

  65   *     exec : function( editor )

  66   *     {

  67   *         // Asynchronous operation below.

  68   *         CKEDITOR.ajax.loadXml( 'data.xml' );

  69   *     },

  70   *     async : true    // The command need some time to complete after exec function returns.

  71   * });

  72   */
  73  
  74  /**

  75   * Whether the command should give focus to the editor before execution.

  76   * @name  CKEDITOR.commandDefinition.editorFocus

  77   * @type {Boolean}

  78   * @example

  79   * editorInstance.addCommand( 'maximize',

  80   * {

  81   *     exec : function( editor )

  82   *     {

  83   *     },

  84   *     editorFocus : false    // The command doesn't require focusing the editing document.

  85   * });

  86   */
  87  
  88  
  89  /**

  90   * Whether the command state should be set to {@link CKEDITOR.TRISTATE_DISABLED} on startup.

  91   * @name  CKEDITOR.commandDefinition.startDisabled

  92   * @type {Boolean}

  93   * @default false

  94   * @example

  95   * editorInstance.addCommand( 'unlink',

  96   * {

  97   *     exec : function( editor )

  98   *     {

  99   *     },

 100   *     startDisabled : true    // Command is unavailable until selection is inside a link.

 101   * });

 102   */