composer.js 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687
  1. /**
  2. * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. 'use strict';
  6. import utils from '../../../utils/utils.js';
  7. import EmitterMixin from '../../../utils/emittermixin.js';
  8. import deleteContents from './deletecontents.js';
  9. import modifySelection from './modifyselection.js';
  10. /**
  11. * Set of frequently used tools to work with a document.
  12. * The instance of composer is available in {@link engine.treeModel.Document#composer}.
  13. *
  14. * By default this class implements only a very basic version of those algorithms. However, all its methods can be extended
  15. * by features by listening to related events. The default action of those events are implemented
  16. * by functions available in the {@link engine.treeModel.composer} namespace, so they can be reused
  17. * in the algorithms implemented by features.
  18. *
  19. * @member engine.treeModel.composer
  20. * @mixes utils.EmitterMixin
  21. */
  22. export default class Composer {
  23. /**
  24. * Creates an instance of the composer.
  25. */
  26. constructor() {
  27. this.on( 'deleteContents', ( evt, data ) => deleteContents( data.batch, data.selection ) );
  28. this.on( 'modifySelection', ( evt, data ) => modifySelection( data.selection, data.options ) );
  29. }
  30. /**
  31. * See {@link engine.treeModel.composer.deleteContents}.
  32. *
  33. * Note: For the sake of predictability, the resulting selection should always be collapsed.
  34. * In cases where a feature wants to modify deleting behavior so selection isn't collapsed
  35. * (e.g. a table feature may want to keep row selection after pressing <kbd>Backspace</kbd>),
  36. * then that behavior should be implemented in the view's listener. At the same time, the table feature
  37. * will need to modify this method's behavior too, e.g. to "delete contents and then collapse
  38. * the selection inside the last selected cell" or "delete the row and collapse selection somewhere near".
  39. * That needs to be done in order to ensure that other features which use `deleteContents()` work well with tables.
  40. *
  41. * @fires engine.treeModel.composer.Composer#deleteContents
  42. * @param {engine.treeModel.Batch} batch Batch to which deltas will be added.
  43. * @param {engine.treeModel.Selection} selection Selection of which the content should be deleted.
  44. */
  45. deleteContents( batch, selection ) {
  46. this.fire( 'deleteContents', { batch, selection } );
  47. }
  48. /**
  49. * See {@link engine.treeModel.composer.modifySelection}.
  50. *
  51. * @fires engine.treeModel.composer.Composer#modifySelection
  52. * @param {engine.treeModel.Selection} The selection to modify.
  53. * @param {Object} options See {@link engine.treeModel.composer.modifySelection}'s options.
  54. */
  55. modifySelection( selection, options ) {
  56. this.fire( 'modifySelection', { selection, options } );
  57. }
  58. }
  59. utils.mix( Composer, EmitterMixin );
  60. /**
  61. * Event fired when {@link engine.treeModel.composer.Composer#deleteContents} method is called.
  62. * The {@link engine.treeModel.composer.deleteContents default action of the composer} is implemented as a
  63. * listener to that event so it can be fully customized by the features.
  64. *
  65. * @event engine.treeModel.composer.Composer#deleteContents
  66. * @param {Object} data
  67. * @param {engine.treeModel.Batch} data.batch
  68. * @param {engine.treeModel.Selection} data.selection
  69. */
  70. /**
  71. * Event fired when {@link engine.treeModel.composer.Composer#modifySelection} method is called.
  72. * The {@link engine.treeModel.composer.modifySelection default action of the composer} is implemented as a
  73. * listener to that event so it can be fully customized by the features.
  74. *
  75. * @event engine.treeModel.composer.Composer#modifySelection
  76. * @param {Object} data
  77. * @param {engine.treeModel.Selection} data.selection
  78. * @param {Object} data.options See {@link engine.treeModel.composer.modifySelection}'s options.
  79. */