TooltipManager

class

A tooltip manager class for the UI of the editor.

Note: Most likely you do not have to use the TooltipManager API listed below in order to display tooltips. Popular UI components support tooltips out-of-the-box via observable properties (see tooltip and tooltipPosition).

Displaying tooltips

To display a tooltip, set data-cke-tooltip-text attribute on any DOM element:

domElement.dataset.ckeTooltipText = 'My tooltip';

The tooltip will show up whenever the user moves the mouse over the element or the element gets focus in DOM.

Positioning tooltips

To change the position of the tooltip, use the data-cke-tooltip-position attribute (s, se, sw, n, e, or w):

domElement.dataset.ckeTooltipText = 'Tooltip to the north';
domElement.dataset.ckeTooltipPosition = 'n';

Disabling tooltips

In order to disable the tooltip temporarily, use the data-cke-tooltip-disabled attribute:

domElement.dataset.ckeTooltipText = 'Disabled. For now.';
domElement.dataset.ckeTooltipDisabled = 'true';

Instant tooltips

To remove the delay before showing or hiding the tooltip, use the data-cke-tooltip-instant attribute:

domElement.dataset.ckeTooltipInstant = 'true';

Styling tooltips

By default, the tooltip has .ck-tooltip class and its text inner .ck-tooltip__text.

If your tooltip requires custom styling, using data-cke-tooltip-class attribute will add additional class to the balloon displaying the tooltip:

domElement.dataset.ckeTooltipText = 'Tooltip with a red text';
domElement.dataset.ckeTooltipClass = 'my-class';

.ck.ck-tooltip.my-class { color: red }

Note: This class is a singleton. All editor instances re-use the same instance loaded by EditorUI of the first editor.

See source

Properties

Methods

constructor( editor )

Creates an instance of the tooltip manager.
See source (with github icon)
Parameters
editor : Editor
delegate( events ) → EmitterMixinDelegateChain
inherited
module:ui/tooltipmanager~TooltipManager#delegate
Delegates selected events to another Emitter. For instance:
```
emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
```
Copy code
then eventX is delegated (fired by) emitterB and emitterC along with data:
```
emitterA.fire( 'eventX', data );
```
Copy code
and eventY is delegated (fired by) emitterC along with data:
```
emitterA.fire( 'eventY', data );
```
Copy code
See source (with github icon)
Parameters
events : Array<string>
Event names that will be delegated to another emitter.
Returns
EmitterMixinDelegateChain
destroy( editor ) → void

Destroys the tooltip manager.
Note: The manager singleton cannot be destroyed until all editors that use it are destroyed.
See source (with github icon)
Parameters
editor : Editor
The editor the manager was created for.
Returns
void
fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]
inherited

Fires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type describing the event. See BaseEvent.
Parameters
eventOrInfo : GetNameOrEventInfo<TEvent>
The name of the event or EventInfo object if event is delegated.
args : TEvent[ 'args' ]
Additional arguments to be passed to the callbacks.
Returns
GetEventInfo<TEvent>[ 'return' ]
By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).
listenTo( emitter, event, callback, [ options ] ) → void
inherited
module:ui/tooltipmanager~TooltipManager#listenTo:DOM_EMITTER
Registers a callback function to be executed when an event is fired in a specific (emitter) object.
Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.
```
// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );
```
Copy code
An event callback can stop the event and set the return value of the fire method.
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type describing the event. See BaseEvent.
Parameters
emitter : Emitter
The object that fires the event.
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : CallbackOptions
Additional options.
Returns
void
listenTo( emitter, event, callback, [ options ] ) → void
inherited

Registers a callback function to be executed when an event is fired in a specific Emitter or DOM Node. It is backwards compatible with listenTo.
See source (with github icon)
Type parameters
K : extends keyof DomEventMap
Parameters
emitter : Window | EventTarget | Node
The object that fires the event.
event : K
The name of the event.
callback : ( this: this, ev: EventInfo, event: DomEventMap[ K ] ) => void
The function to be called on event.
[ options ] : object
Additional options.
Returns
void
off( event, callback ) → void
inherited

Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).
See source (with github icon)
Parameters
event : string
The name of the event.
callback : Function
The function to stop being called.
Returns
void
on( event, callback, [ options ] ) → void
inherited

Registers a callback function to be executed when an event is fired.
Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type descibing the event. See BaseEvent.
Parameters
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : GetCallbackOptions<TEvent>
Additional options.
Returns
void
once( event, callback, [ options ] ) → void
inherited

Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.
See source (with github icon)
Type parameters
TEvent : extends BaseEvent
The type descibing the event. See BaseEvent.
Parameters
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : GetCallbackOptions<TEvent>
Additional options.
Returns
void
stopDelegating( [ event ], [ emitter ] ) → void
inherited
module:ui/tooltipmanager~TooltipManager#stopDelegating
Stops delegating events. It can be used at different levels:
- To stop delegating all events.
- To stop delegating a specific event to all emitters.
- To stop delegating a specific event to a specific emitter.
See source (with github icon)
Parameters
[ event ] : string
The name of the event to stop delegating. If omitted, stops it all delegations.
[ emitter ] : Emitter
(requires event) The object to stop delegating a particular event to. If omitted, stops delegation of event to all emitters.
Returns
void
stopListening( [ emitter ], [ event ], [ callback ] ) → void
inherited
module:ui/tooltipmanager~TooltipManager#stopListening:DOM_STOP
Stops listening for events. It can be used at different levels: It is backwards compatible with listenTo.
- To stop listening to a specific callback.
- To stop listening to a specific event.
- To stop listening to all events fired by a specific object.
- To stop listening to all events fired by all objects.
See source (with github icon)
Parameters
[ emitter ] : Window | EventTarget | Node | Emitter
The object to stop listening to. If omitted, stops it for all objects.
[ event ] : string
(Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.
[ callback ] : Function
(Requires the event) The function to be removed from the call list for the given event.
Returns
void
_onEnterOrFocus( evt, domEvent ) → void
private

Handles displaying tooltips on mouseenter and focus in DOM.
See source (with github icon)
Parameters
evt : EventInfo
An object containing information about the fired event.
domEvent : any
The DOM event.
Returns
void
_onKeyDown( evt, domEvent ) → void
private

Handles hiding tooltips on keydown in DOM.
See source (with github icon)
Parameters
evt : EventInfo
An object containing information about the fired event.
domEvent : KeyboardEvent
The DOM event.
Returns
void
_onLeaveOrBlur( evt, domEvent ) → void
private

Handles hiding tooltips on mouseleave and blur in DOM.
See source (with github icon)
Parameters
evt : EventInfo
An object containing information about the fired event.
domEvent : any
The DOM event.
Returns
void
_onScroll( evt, domEvent ) → void
private

Handles hiding tooltips on scroll in DOM.
See source (with github icon)
Parameters
evt : unknown
An object containing information about the fired event.
domEvent : any
The DOM event.
Returns
void
_pinTooltip( targetDomElement, options ) → void
private

Pins the tooltip to a specific DOM element.
See source (with github icon)
Parameters
targetDomElement : HTMLElement
Element to be pinned to.
options : TooltipData
Options for the tooltip.
Returns
void
_unpinTooltip() → void
private

Unpins the tooltip and cancels all queued pinning.
See source (with github icon)
Returns
void
_updateTooltipPosition() → void
private

Updates the position of the tooltip so it stays in sync with the element it is pinned to.
Hides the tooltip when the element is no longer visible in DOM or the tooltip text was removed.
See source (with github icon)
Returns
void

Static methods

getPositioningFunctions( position ) → Array<PositioningFunction>
static

Returns balloonPanelView positioning functions for a given position name.
See source (with github icon)
Parameters
position : TooltipPosition
Name of the position (s, se, sw, n, e, or w).
Returns
Array<PositioningFunction>
Positioning functions to be used by the balloonPanelView.

TooltipManager

Displaying tooltips

Positioning tooltips

Disabling tooltips

Instant tooltips

Styling tooltips

Properties

balloonPanelView : BalloonPanelViewreadonly

tooltipTextView : objectreadonly

_currentElementWithTooltip : null | HTMLElement Lock iconprivate

_currentTooltipPosition : null | TooltipPosition Lock iconprivate

_mutationObserver : null | MutationObserverWrapper Lock iconprivate

_pinTooltipDebounced : DebouncedFunc<( targetDomElement: HTMLElement, data: TooltipData ) => void> Lock iconprivate

_unpinTooltipDebounced : DebouncedFunc<VoidFunction> Lock iconprivate

_watchdogExcluded : true Lock iconprivatereadonly

Static properties

defaultBalloonPositions : Record<string, PositioningFunction>static

_editors : Set<Editor> Lock iconprivatestatic

_instance : null | TooltipManager Lock iconprivatestatic

Methods

constructor( editor )

Parameters

delegate( events ) → EmitterMixinDelegateChaininherited

Parameters

Returns

destroy( editor ) → void

Parameters

Returns

fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]inherited

Type parameters

Parameters

Returns

listenTo( emitter, event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

listenTo( emitter, event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

off( event, callback ) → voidinherited

Parameters

Returns

on( event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

once( event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

stopDelegating( [ event ], [ emitter ] ) → voidinherited

Parameters

Returns

stopListening( [ emitter ], [ event ], [ callback ] ) → voidinherited

Parameters

Returns

_onEnterOrFocus( evt, domEvent ) → void Lock iconprivate

Parameters

Returns

_onKeyDown( evt, domEvent ) → void Lock iconprivate

Parameters

Returns

_onLeaveOrBlur( evt, domEvent ) → void Lock iconprivate

Parameters

Returns

_onScroll( evt, domEvent ) → void Lock iconprivate

Parameters

Returns

_pinTooltip( targetDomElement, options ) → void Lock iconprivate

Parameters

Returns

_unpinTooltip() → void Lock iconprivate

Returns

_updateTooltipPosition() → void Lock iconprivate

Returns

Static methods

getPositioningFunctions( position ) → Array<PositioningFunction>static

Parameters

Returns

`balloonPanelView : BalloonPanelView`
readonly

`tooltipTextView : object`
readonly

`_currentElementWithTooltip : null | HTMLElement`
private

`_currentTooltipPosition : null | TooltipPosition`
private

`_mutationObserver : null | MutationObserverWrapper`
private

`_pinTooltipDebounced : DebouncedFunc<( targetDomElement: HTMLElement, data: TooltipData ) => void>`
private

`_unpinTooltipDebounced : DebouncedFunc<VoidFunction>`
private

`_watchdogExcluded : true`
privatereadonly

`defaultBalloonPositions : Record<string, PositioningFunction>`
static

`_editors : Set<Editor>`
privatestatic

`_instance : null | TooltipManager`
privatestatic

`constructor( editor )`

`delegate( events ) → EmitterMixinDelegateChain`
inherited

`destroy( editor ) → void`

`fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]`
inherited

`listenTo( emitter, event, callback, [ options ] ) → void`
inherited

`listenTo( emitter, event, callback, [ options ] ) → void`
inherited

`off( event, callback ) → void`
inherited

`on( event, callback, [ options ] ) → void`
inherited

`once( event, callback, [ options ] ) → void`
inherited

`stopDelegating( [ event ], [ emitter ] ) → void`
inherited

`stopListening( [ emitter ], [ event ], [ callback ] ) → void`
inherited

`_onEnterOrFocus( evt, domEvent ) → void`
private

`_onKeyDown( evt, domEvent ) → void`
private

`_onLeaveOrBlur( evt, domEvent ) → void`
private

`_onScroll( evt, domEvent ) → void`
private

`_pinTooltip( targetDomElement, options ) → void`
private

`_unpinTooltip() → void`
private

`_updateTooltipPosition() → void`
private

`getPositioningFunctions( position ) → Array<PositioningFunction>`
static