8
0

command.js 3.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122
  1. /**
  2. * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module core/command
  7. */
  8. import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
  9. import mix from '@ckeditor/ckeditor5-utils/src/mix';
  10. /**
  11. * The base class for CKEditor commands.
  12. *
  13. * Commands are the main way to manipulate editor contents and state. They are mostly used by UI elements (or by other
  14. * commands) to make changes in the model. Commands are available in every part of code that has access to
  15. * the {@link module:core/editor/editor~Editor editor} instance.
  16. *
  17. * Instances of registered commands can be retrieved from {@link module:core/editor/editor~Editor#commands}.
  18. * The easiest way to execute a command is through {@link module:core/editor/editor~Editor#execute}.
  19. *
  20. * @mixes module:utils/observablemixin~ObservableMixin
  21. */
  22. export default class Command {
  23. /**
  24. * Creates a new `Command` instance.
  25. *
  26. * @param {module:core/editor/editor~Editor} editor Editor on which this command will be used.
  27. */
  28. constructor( editor ) {
  29. /**
  30. * The editor on which this command will be used.
  31. *
  32. * @readonly
  33. * @member {module:core/editor/editor~Editor}
  34. */
  35. this.editor = editor;
  36. /**
  37. * The value of a command. Concrete command class should define what it represents.
  38. *
  39. * For example, the `bold` command's value is whether the selection starts in a bolded text.
  40. * And the value of the `link` command may be an object with links details.
  41. *
  42. * It's possible for a command to have no value (e.g. for stateless actions such as `uploadImage`).
  43. *
  44. * @observable
  45. * @readonly
  46. * @member #value
  47. */
  48. this.set( 'value', undefined );
  49. /**
  50. * Flag indicating whether a command is enabled or disabled.
  51. * A disabled command should do nothing when executed.
  52. *
  53. * @observable
  54. * @readonly
  55. * @member {Boolean} #isEnabled
  56. */
  57. this.set( 'isEnabled', false );
  58. this.decorate( 'execute' );
  59. // By default every command is refreshed when changes are applied to the model.
  60. this.listenTo( this.editor.document, 'changesDone', () => {
  61. this.refresh();
  62. } );
  63. this.on( 'execute', evt => {
  64. if ( !this.isEnabled ) {
  65. evt.stop();
  66. }
  67. }, { priority: 'high' } );
  68. }
  69. /**
  70. * Refreshes the command. The command should update its {@link #isEnabled} and {@link #value} property
  71. * in this method.
  72. *
  73. * This method is automatically called when
  74. * {@link module:engine/model/document~Document#event:changesDone any changes are applied to the model}.
  75. */
  76. refresh() {
  77. this.isEnabled = true;
  78. }
  79. /**
  80. * Executes the command.
  81. *
  82. * A command may accept parameters. They will be passed from {@link module:core/editor/editor~Editor#execute}
  83. * to the command.
  84. *
  85. * The `execute()` method will automatically abort when the command is disabled ({@link #isEnabled} is `false`).
  86. * This behavior is implemented by a high priority listener to the {@link #event:execute} event.
  87. *
  88. * @fires execute
  89. */
  90. execute() {}
  91. /**
  92. * Destroys the command.
  93. */
  94. destroy() {
  95. this.stopListening();
  96. }
  97. /**
  98. * Event fired by the {@link #execute} method. The command action is a listener to this event so it's
  99. * possible to change/cancel the behavior of the command by listening to this event.
  100. *
  101. * See {@link module:utils/observablemixin~ObservableMixin.decorate} for more information and samples.
  102. *
  103. * **Note:** This event is fired even if command is disabled. However, it is automatically blocked
  104. * by a high priority listener in order to prevent command execution.
  105. *
  106. * @event execute
  107. */
  108. }
  109. mix( Command, ObservableMixin );