1 | import { IDisposable } from '@lumino/disposable';
|
2 | import { ISignal } from '@lumino/signaling';
|
3 | import { Widget } from './widget';
|
4 | /**
|
5 | * A class which tracks focus among a set of widgets.
|
6 | *
|
7 | * This class is useful when code needs to keep track of the most
|
8 | * recently focused widget(s) among a set of related widgets.
|
9 | */
|
10 | export declare class FocusTracker<T extends Widget> implements IDisposable {
|
11 | /**
|
12 | * Dispose of the resources held by the tracker.
|
13 | */
|
14 | dispose(): void;
|
15 | /**
|
16 | * A signal emitted when the current widget has changed.
|
17 | */
|
18 | readonly currentChanged: ISignal<this, FocusTracker.IChangedArgs<T>>;
|
19 | /**
|
20 | * A signal emitted when the active widget has changed.
|
21 | */
|
22 | readonly activeChanged: ISignal<this, FocusTracker.IChangedArgs<T>>;
|
23 | /**
|
24 | * A flag indicating whether the tracker is disposed.
|
25 | */
|
26 | readonly isDisposed: boolean;
|
27 | /**
|
28 | * The current widget in the tracker.
|
29 | *
|
30 | * #### Notes
|
31 | * The current widget is the widget among the tracked widgets which
|
32 | * has the *descendant node* which has most recently been focused.
|
33 | *
|
34 | * The current widget will not be updated if the node loses focus. It
|
35 | * will only be updated when a different tracked widget gains focus.
|
36 | *
|
37 | * If the current widget is removed from the tracker, the previous
|
38 | * current widget will be restored.
|
39 | *
|
40 | * This behavior is intended to follow a user's conceptual model of
|
41 | * a semantically "current" widget, where the "last thing of type X"
|
42 | * to be interacted with is the "current instance of X", regardless
|
43 | * of whether that instance still has focus.
|
44 | */
|
45 | readonly currentWidget: T | null;
|
46 | /**
|
47 | * The active widget in the tracker.
|
48 | *
|
49 | * #### Notes
|
50 | * The active widget is the widget among the tracked widgets which
|
51 | * has the *descendant node* which is currently focused.
|
52 | */
|
53 | readonly activeWidget: T | null;
|
54 | /**
|
55 | * A read only array of the widgets being tracked.
|
56 | */
|
57 | readonly widgets: ReadonlyArray<T>;
|
58 | /**
|
59 | * Get the focus number for a particular widget in the tracker.
|
60 | *
|
61 | * @param widget - The widget of interest.
|
62 | *
|
63 | * @returns The focus number for the given widget, or `-1` if the
|
64 | * widget has not had focus since being added to the tracker, or
|
65 | * is not contained by the tracker.
|
66 | *
|
67 | * #### Notes
|
68 | * The focus number indicates the relative order in which the widgets
|
69 | * have gained focus. A widget with a larger number has gained focus
|
70 | * more recently than a widget with a smaller number.
|
71 | *
|
72 | * The `currentWidget` will always have the largest focus number.
|
73 | *
|
74 | * All widgets start with a focus number of `-1`, which indicates that
|
75 | * the widget has not been focused since being added to the tracker.
|
76 | */
|
77 | focusNumber(widget: T): number;
|
78 | /**
|
79 | * Test whether the focus tracker contains a given widget.
|
80 | *
|
81 | * @param widget - The widget of interest.
|
82 | *
|
83 | * @returns `true` if the widget is tracked, `false` otherwise.
|
84 | */
|
85 | has(widget: T): boolean;
|
86 | /**
|
87 | * Add a widget to the focus tracker.
|
88 | *
|
89 | * @param widget - The widget of interest.
|
90 | *
|
91 | * #### Notes
|
92 | * A widget will be automatically removed from the tracker if it
|
93 | * is disposed after being added.
|
94 | *
|
95 | * If the widget is already tracked, this is a no-op.
|
96 | */
|
97 | add(widget: T): void;
|
98 | /**
|
99 | * Remove a widget from the focus tracker.
|
100 | *
|
101 | * #### Notes
|
102 | * If the widget is the `currentWidget`, the previous current widget
|
103 | * will become the new `currentWidget`.
|
104 | *
|
105 | * A widget will be automatically removed from the tracker if it
|
106 | * is disposed after being added.
|
107 | *
|
108 | * If the widget is not tracked, this is a no-op.
|
109 | */
|
110 | remove(widget: T): void;
|
111 | /**
|
112 | * Handle the DOM events for the focus tracker.
|
113 | *
|
114 | * @param event - The DOM event sent to the panel.
|
115 | *
|
116 | * #### Notes
|
117 | * This method implements the DOM `EventListener` interface and is
|
118 | * called in response to events on the tracked nodes. It should
|
119 | * not be called directly by user code.
|
120 | */
|
121 | handleEvent(event: Event): void;
|
122 | /**
|
123 | * Set the current and active widgets for the tracker.
|
124 | */
|
125 | private _setWidgets;
|
126 | /**
|
127 | * Handle the `'focus'` event for a tracked widget.
|
128 | */
|
129 | private _evtFocus;
|
130 | /**
|
131 | * Handle the `'blur'` event for a tracked widget.
|
132 | */
|
133 | private _evtBlur;
|
134 | /**
|
135 | * Handle the `disposed` signal for a tracked widget.
|
136 | */
|
137 | private _onWidgetDisposed;
|
138 | private _counter;
|
139 | private _widgets;
|
140 | private _activeWidget;
|
141 | private _currentWidget;
|
142 | private _numbers;
|
143 | private _nodes;
|
144 | private _activeChanged;
|
145 | private _currentChanged;
|
146 | }
|
147 | /**
|
148 | * The namespace for the `FocusTracker` class statics.
|
149 | */
|
150 | export declare namespace FocusTracker {
|
151 | /**
|
152 | * An arguments object for the changed signals.
|
153 | */
|
154 | interface IChangedArgs<T extends Widget> {
|
155 | /**
|
156 | * The old value for the widget.
|
157 | */
|
158 | oldValue: T | null;
|
159 | /**
|
160 | * The new value for the widget.
|
161 | */
|
162 | newValue: T | null;
|
163 | }
|
164 | }
|
165 | //# sourceMappingURL=focustracker.d.ts.map |
\ | No newline at end of file |