sources/core/commanddefinition.js

   1 /**
   2  * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
   3  * For licensing, see LICENSE.md 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 that illustrates the features of command objects to be
  14  * passed to the {@link CKEDITOR.editor#addCommand} function.
  15  *
  16  * @class CKEDITOR.commandDefinition
  17  * @abstract
  18  */
  19
  20 /**
  21  * The function to be fired when the commend is executed.
  22  *
  23  *              editorInstance.addCommand( 'sample', {
  24  *                      exec: function( editor ) {
  25  *                              alert( 'Executing a command for the editor name "' + editor.name + '"!' );
  26  *                      }
  27  *              } );
  28  *
  29  * @method exec
  30  * @param {CKEDITOR.editor} editor The editor within which to run the command.
  31  * @param {Object} [data] Additional data to be used to execute the command.
  32  * @returns {Boolean} Whether the command has been successfully executed.
  33  * Defaults to `true` if nothing is returned.
  34  */
  35
  36 /**
  37  * Whether the command needs to be hooked into the redo/undo system.
  38  *
  39  *              editorInstance.addCommand( 'alertName', {
  40  *                      exec: function( editor ) {
  41  *                              alert( editor.name );
  42  *                      },
  43  *                      canUndo: false // No support for undo/redo.
  44  *              } );
  45  *
  46  * @property {Boolean} [canUndo=true]
  47  */
  48
  49 /**
  50  * Whether the command is asynchronous, which means that the
  51  * {@link CKEDITOR.editor#event-afterCommandExec} event will be fired by the
  52  * command itself manually, and that the return value of this command is not to
  53  * be returned by the {@link #exec} function.
  54  *
  55  *              editorInstance.addCommand( 'loadoptions', {
  56  *                      exec: function( editor ) {
  57  *                              var cmd = this;
  58  *                              // Asynchronous operation below.
  59  *                              CKEDITOR.ajax.loadXml( 'data.xml', function() {
  60  *                                      editor.fire( 'afterCommandExec', {
  61  *                                              name: 'loadoptions',
  62  *                                              command: cmd
  63  *                                      } );
  64  *                              } );
  65  *                      },
  66  *                      async: true // The command needs some time to complete after the exec function returns.
  67  *              } );
  68  *
  69  * @property {Boolean} [async=false]
  70  */
  71
  72 /**
  73  * Whether the command should give focus to the editor before execution.
  74  *
  75  *              editorInstance.addCommand( 'maximize', {
  76  *                              exec: function( editor ) {
  77  *                              // ...
  78  *                      },
  79  *                      editorFocus: false // The command does not require focusing the editing document.
  80  *              } );
  81  *
  82  * See also {@link CKEDITOR.command#editorFocus}.
  83  *
  84  * @property {Boolean} [editorFocus=true]
  85  */
  86
  87
  88 /**
  89  * Whether the command state should be set to {@link CKEDITOR#TRISTATE_DISABLED} on startup.
  90  *
  91  *              editorInstance.addCommand( 'unlink', {
  92  *                      exec: function( editor ) {
  93  *                              // ...
  94  *                      },
  95  *                      startDisabled: true // The command is unavailable until the selection is inside a link.
  96  *              } );
  97  *
  98  * @property {Boolean} [startDisabled=false]
  99  */
 100
 101 /**
 102  * Indicates that this command is sensitive to the selection context.
 103  * If `true`, the {@link CKEDITOR.command#method-refresh} method will be
 104  * called for this command on selection changes, with a single parameter
 105  * representing the current elements path.
 106  *
 107  * @property {Boolean} [contextSensitive=true]
 108  */
 109
 110 /**
 111  * Defined by the command definition, a function to determine the command state. It will be invoked
 112  * when the editor has its `states` or `selection` changed.
 113  *
 114  * **Note:** The function provided must be calling {@link CKEDITOR.command#setState} in all circumstances
 115  * if it is intended to update the command state.
 116  *
 117  * @method refresh
 118  * @param {CKEDITOR.editor} editor
 119  * @param {CKEDITOR.dom.elementPath} path
 120  */
 121
 122 /**
 123  * Sets the element name used to reflect the command state on selection changes.
 124  * If the selection is in a place where the element is not allowed, the command
 125  * will be disabled.
 126  * Setting this property overrides {@link #contextSensitive} to `true`.
 127  *
 128  * @property {Boolean} [context=true]
 129  */
 130
 131 /**
 132  * The editor modes within which the command can be executed. The execution
 133  * will have no action if the current mode is not listed in this property.
 134  *
 135  *              editorInstance.addCommand( 'link', {
 136  *                      exec: function( editor ) {
 137  *                              // ...
 138  *                      },
 139  *                      modes: { wysiwyg:1 } // The command is available in wysiwyg mode only.
 140  *              } );
 141  *
 142  * See also {@link CKEDITOR.command#modes}.
 143  *
 144  * @property {Object} [modes={ wysiwyg:1 }]
 145  */
 146
 147 /**
 148  * Whether the command should be enabled in the {@link CKEDITOR.editor#setReadOnly read-only mode}.
 149  *
 150  * @since 4.0
 151  * @property {Boolean} [readOnly=false]
 152  */
 153
 154 /**
 155  * A property that should be set when a command has no keystroke assigned by {@link CKEDITOR.editor#setKeystroke}, but
 156  * the keystroke is still supported. For example: `cut`, `copy` and `paste` commands are handled that way.
 157  * This property is used when displaying keystroke information in tooltips and context menus. It is used by
 158  * {@link CKEDITOR.editor#getCommandKeystroke}.
 159  *
 160  * @since 4.6.0
 161  * @property {Number} fakeKeystroke
 162  */