Creates a new Command instance.
The editor on which this command will be used.
Protected_A flag indicating whether a command's isEnabled state should be changed depending on where the document
selection is placed.
By default, it is set to true. If the document selection is placed in a
module:engine/model/model~Model#canEditAt non-editable place (such as non-editable root), the command becomes disabled.
The flag should be changed to false in a concrete command's constructor if the command should not change its isEnabled
accordingly to the document selection.
ReadonlyeditorThe editor on which this command will be used.
ReadonlyisFlag indicating whether a command is enabled or disabled. A disabled command will do nothing when executed.
A given command class should control this value by overriding the #refresh refresh() method.
It is possible to disable a command "from outside" using #forceDisabled method.
ReadonlyvalueThe value of the command. A given command class should define what it represents for it.
For example, the 'bold' command's value indicates whether the selection starts in a bolded text.
And the value of the 'link' command may be an object with link details.
It is possible for a command to have no value (e.g. for stateless actions such as 'uploadImage').
A given command class should control this value by overriding the #refresh refresh() method.
A flag indicating whether a command execution changes the editor data or not.
Commands with affectsData set to false will not be automatically disabled in
the module:core/editor/editor~Editor#isReadOnly read-only mode and
{@glink features/read-only#related-features other editor modes} with restricted user write permissions.
Note: You do not have to set it for your every command. It is true by default.
Static_Internal
Command class is commonly put in config.plugins array.
This property helps with better error detection.
Clears forced disable previously set through #forceDisabled. See #forceDisabled.
Unique identifier, equal to the one passed in #forceDisabled call.
Destroys the command.
Executes the command.
A command may accept parameters. They will be passed from module:core/editor/editor~Editor#execute editor.execute()
to the command.
The execute() method will automatically abort when the command is disabled (#isEnabled is false).
This behavior is implemented by a high priority listener to the #event:execute event.
In order to see how to disable a command from "outside" see the #isEnabled documentation.
This method may return a value, which would be forwarded all the way down to the
module:core/editor/editor~Editor#execute editor.execute().
Disables the command.
Command may be disabled by multiple features or algorithms (at once). When disabling a command, unique id should be passed (e.g. the feature name). The same identifier should be used when #clearForceDisabled enabling back the command. The command becomes enabled only after all features #clearForceDisabled enabled it back.
Disabling and enabling a command:
command.isEnabled; // -> true
command.forceDisabled( 'MyFeature' );
command.isEnabled; // -> false
command.clearForceDisabled( 'MyFeature' );
command.isEnabled; // -> true
Command disabled by multiple features:
command.forceDisabled( 'MyFeature' );
command.forceDisabled( 'OtherFeature' );
command.clearForceDisabled( 'MyFeature' );
command.isEnabled; // -> false
command.clearForceDisabled( 'OtherFeature' );
command.isEnabled; // -> true
Multiple disabling with the same identifier is redundant:
command.forceDisabled( 'MyFeature' );
command.forceDisabled( 'MyFeature' );
command.clearForceDisabled( 'MyFeature' );
command.isEnabled; // -> true
Note: some commands or algorithms may have more complex logic when it comes to enabling or disabling certain commands, so the command might be still disabled after #clearForceDisabled was used.
Unique identifier for disabling. Use the same id when #clearForceDisabled enabling back the command.
Refreshes the command. The command should update its #isEnabled and #value properties in this method.
This method is automatically called when module:engine/model/document~ModelDocument#event:change any changes are applied to the document.
Base class for the CKEditor commands.
Commands are the main way to manipulate the editor contents and state. They are mostly used by UI elements (or by other commands) to make changes in the model. Commands are available in every part of the code that has access to the module:core/editor/editor~Editor editor instance.
Instances of registered commands can be retrieved from module:core/editor/editor~Editor#commands
editor.commands. The easiest way to execute a command is through module:core/editor/editor~Editor#executeeditor.execute().By default, commands are disabled when the editor is in the module:core/editor/editor~Editor#isReadOnly read-only mode but commands with the module:core/command~Command#affectsData
affectsDataflag set tofalsewill not be disabled.