focustracker.js 3.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /* global setTimeout, clearTimeout */
  6. /**
  7. * @module utils/focustracker
  8. */
  9. import DomEmitterMixin from './dom/emittermixin';
  10. import ObservableMixin from './observablemixin';
  11. import CKEditorError from './ckeditorerror';
  12. import mix from './mix';
  13. /**
  14. * Allows observing a group of `HTMLElement`s whether at least one of them is focused.
  15. *
  16. * Used by the {@link module:core/editor/editor~Editor} in order to track whether the focus is still within the application,
  17. * or were used outside of its UI.
  18. *
  19. * **Note** `focus` and `blur` listeners use event capturing, so it is only needed to register wrapper `HTMLElement`
  20. * which contain other `focusable` elements. But note that this wrapper element has to be focusable too
  21. * (have e.g. `tabindex="-1"`).
  22. *
  23. * Check out the {@glink framework/guides/deep-dive/ui/focus-tracking "Deep dive into focus tracking" guide} to learn more.
  24. *
  25. * @mixes module:utils/dom/emittermixin~EmitterMixin
  26. * @mixes module:utils/observablemixin~ObservableMixin
  27. */
  28. export default class FocusTracker {
  29. constructor() {
  30. /**
  31. * True when one of the registered elements is focused.
  32. *
  33. * @readonly
  34. * @observable
  35. * @member {Boolean} #isFocused
  36. */
  37. this.set( 'isFocused', false );
  38. /**
  39. * The currently focused element.
  40. *
  41. * While {@link #isFocused `isFocused`} remains `true`, the focus can
  42. * move between different UI elements. This property tracks those
  43. * elements and tells which one is currently focused.
  44. *
  45. * @readonly
  46. * @observable
  47. * @member {HTMLElement|null} #focusedElement
  48. */
  49. this.set( 'focusedElement', null );
  50. /**
  51. * List of registered elements.
  52. *
  53. * @private
  54. * @member {Set.<HTMLElement>}
  55. */
  56. this._elements = new Set();
  57. /**
  58. * Event loop timeout.
  59. *
  60. * @private
  61. * @member {Number}
  62. */
  63. this._nextEventLoopTimeout = null;
  64. }
  65. /**
  66. * Starts tracking the specified element.
  67. *
  68. * @param {HTMLElement} element
  69. */
  70. add( element ) {
  71. if ( this._elements.has( element ) ) {
  72. /**
  73. * This element is already tracked by {@link module:utils/focustracker~FocusTracker}.
  74. *
  75. * @error focusTracker-add-element-already-exist
  76. */
  77. throw new CKEditorError( 'focusTracker-add-element-already-exist: This element is already tracked by FocusTracker.', this );
  78. }
  79. this.listenTo( element, 'focus', () => this._focus( element ), { useCapture: true } );
  80. this.listenTo( element, 'blur', () => this._blur(), { useCapture: true } );
  81. this._elements.add( element );
  82. }
  83. /**
  84. * Stops tracking the specified element and stops listening on this element.
  85. *
  86. * @param {HTMLElement} element
  87. */
  88. remove( element ) {
  89. if ( element === this.focusedElement ) {
  90. this._blur( element );
  91. }
  92. if ( this._elements.has( element ) ) {
  93. this.stopListening( element );
  94. this._elements.delete( element );
  95. }
  96. }
  97. /**
  98. * Destroys the focus tracker by:
  99. * - Disabling all event listeners attached to tracked elements.
  100. * - Removing all tracked elements that were previously added.
  101. */
  102. destroy() {
  103. this.stopListening();
  104. }
  105. /**
  106. * Stores currently focused element and set {#isFocused} as `true`.
  107. *
  108. * @private
  109. * @param {HTMLElement} element Element which has been focused.
  110. */
  111. _focus( element ) {
  112. clearTimeout( this._nextEventLoopTimeout );
  113. this.focusedElement = element;
  114. this.isFocused = true;
  115. }
  116. /**
  117. * Clears currently focused element and set {@link #isFocused} as `false`.
  118. * This method uses `setTimeout` to change order of fires `blur` and `focus` events.
  119. *
  120. * @private
  121. * @fires blur
  122. */
  123. _blur() {
  124. clearTimeout( this._nextEventLoopTimeout );
  125. this._nextEventLoopTimeout = setTimeout( () => {
  126. this.focusedElement = null;
  127. this.isFocused = false;
  128. }, 0 );
  129. }
  130. /**
  131. * @event focus
  132. */
  133. /**
  134. * @event blur
  135. */
  136. }
  137. mix( FocusTracker, DomEmitterMixin );
  138. mix( FocusTracker, ObservableMixin );