1 | import { IRestorable } from '@jupyterlab/statedb';
|
2 | import { IDisposable } from '@lumino/disposable';
|
3 | import { ISignal } from '@lumino/signaling';
|
4 | import { Widget } from '@lumino/widgets';
|
5 |
|
6 |
|
7 |
|
8 |
|
9 |
|
10 | export interface IWidgetTracker<T extends Widget = Widget> extends IDisposable {
|
11 | |
12 |
|
13 |
|
14 | readonly widgetAdded: ISignal<this, T>;
|
15 | |
16 |
|
17 |
|
18 |
|
19 |
|
20 |
|
21 |
|
22 | readonly currentWidget: T | null;
|
23 | |
24 |
|
25 |
|
26 |
|
27 |
|
28 |
|
29 | readonly currentChanged: ISignal<this, T | null>;
|
30 | |
31 |
|
32 |
|
33 | readonly size: number;
|
34 | |
35 |
|
36 |
|
37 |
|
38 |
|
39 |
|
40 |
|
41 |
|
42 |
|
43 |
|
44 |
|
45 | readonly restored: Promise<void>;
|
46 | |
47 |
|
48 |
|
49 | readonly widgetUpdated: ISignal<this, T>;
|
50 | |
51 |
|
52 |
|
53 |
|
54 |
|
55 |
|
56 |
|
57 |
|
58 | find(fn: (obj: T) => boolean): T | undefined;
|
59 | |
60 |
|
61 |
|
62 |
|
63 |
|
64 | forEach(fn: (obj: T) => void): void;
|
65 | |
66 |
|
67 |
|
68 |
|
69 |
|
70 | filter(fn: (obj: T) => boolean): T[];
|
71 | |
72 |
|
73 |
|
74 |
|
75 |
|
76 | has(obj: Widget): boolean;
|
77 | |
78 |
|
79 |
|
80 |
|
81 |
|
82 |
|
83 | inject(obj: T): void;
|
84 | }
|
85 |
|
86 |
|
87 |
|
88 |
|
89 |
|
90 |
|
91 |
|
92 |
|
93 |
|
94 |
|
95 |
|
96 |
|
97 | export declare class WidgetTracker<T extends Widget = Widget> implements IWidgetTracker<T>, IRestorable<T> {
|
98 | |
99 |
|
100 |
|
101 |
|
102 |
|
103 | constructor(options: WidgetTracker.IOptions);
|
104 | /**
|
105 | * A namespace for all tracked widgets, (e.g., `notebook`).
|
106 | */
|
107 | readonly namespace: string;
|
108 | /**
|
109 | * A signal emitted when the current widget changes.
|
110 | */
|
111 | get currentChanged(): ISignal<this, T | null>;
|
112 | /**
|
113 | * The current widget is the most recently focused or added widget.
|
114 | *
|
115 | * #### Notes
|
116 | * It is the most recently focused widget, or the most recently added
|
117 | * widget if no widget has taken focus.
|
118 | */
|
119 | get currentWidget(): T | null;
|
120 | /**
|
121 | * A promise resolved when the tracker has been restored.
|
122 | */
|
123 | get restored(): Promise<void>;
|
124 | /**
|
125 | * The number of widgets held by the tracker.
|
126 | */
|
127 | get size(): number;
|
128 | /**
|
129 | * A signal emitted when a widget is added.
|
130 | *
|
131 | * #### Notes
|
132 | * This signal will only fire when a widget is added to the tracker. It will
|
133 | * not fire if a widget is injected into the tracker.
|
134 | */
|
135 | get widgetAdded(): ISignal<this, T>;
|
136 | /**
|
137 | * A signal emitted when a widget is updated.
|
138 | */
|
139 | get widgetUpdated(): ISignal<this, T>;
|
140 | /**
|
141 | * Add a new widget to the tracker.
|
142 | *
|
143 | * @param widget - The widget being added.
|
144 | *
|
145 | * #### Notes
|
146 | * The widget passed into the tracker is added synchronously; its existence in
|
147 | * the tracker can be checked with the `has()` method. The promise this method
|
148 | * returns resolves after the widget has been added and saved to an underlying
|
149 | * restoration connector, if one is available.
|
150 | *
|
151 | * The newly added widget becomes the current widget unless the focus tracker
|
152 | * already had a focused widget.
|
153 | */
|
154 | add(widget: T): Promise<void>;
|
155 | /**
|
156 | * Test whether the tracker is disposed.
|
157 | */
|
158 | get isDisposed(): boolean;
|
159 | /**
|
160 | * Dispose of the resources held by the tracker.
|
161 | */
|
162 | dispose(): void;
|
163 | /**
|
164 | * Find the first widget in the tracker that satisfies a filter function.
|
165 | *
|
166 | * @param - fn The filter function to call on each widget.
|
167 | *
|
168 | * #### Notes
|
169 | * If no widget is found, the value returned is `undefined`.
|
170 | */
|
171 | find(fn: (widget: T) => boolean): T | undefined;
|
172 | /**
|
173 | * Iterate through each widget in the tracker.
|
174 | *
|
175 | * @param fn - The function to call on each widget.
|
176 | */
|
177 | forEach(fn: (widget: T) => void): void;
|
178 | /**
|
179 | * Filter the widgets in the tracker based on a predicate.
|
180 | *
|
181 | * @param fn - The function by which to filter.
|
182 | */
|
183 | filter(fn: (widget: T) => boolean): T[];
|
184 | /**
|
185 | * Inject a foreign widget into the widget tracker.
|
186 | *
|
187 | * @param widget - The widget to inject into the tracker.
|
188 | *
|
189 | * #### Notes
|
190 | * Injected widgets will not have their state saved by the tracker.
|
191 | *
|
192 | * The primary use case for widget injection is for a plugin that offers a
|
193 | * sub-class of an extant plugin to have its instances share the same commands
|
194 | * as the parent plugin (since most relevant commands will use the
|
195 | * `currentWidget` of the parent plugin's widget tracker). In this situation,
|
196 | * the sub-class plugin may well have its own widget tracker for layout and
|
197 | * state restoration in addition to injecting its widgets into the parent
|
198 | * plugin's widget tracker.
|
199 | */
|
200 | inject(widget: T): Promise<void>;
|
201 | /**
|
202 | * Check if this tracker has the specified widget.
|
203 | *
|
204 | * @param widget - The widget whose existence is being checked.
|
205 | */
|
206 | has(widget: Widget): boolean;
|
207 | /**
|
208 | * Restore the widgets in this tracker's namespace.
|
209 | *
|
210 | * @param options - The configuration options that describe restoration.
|
211 | *
|
212 | * @returns A promise that resolves when restoration has completed.
|
213 | *
|
214 | * #### Notes
|
215 | * This function should not typically be invoked by client code.
|
216 | * Its primary use case is to be invoked by a restorer.
|
217 | */
|
218 | restore(options?: IRestorable.IOptions<T>): Promise<any>;
|
219 | /**
|
220 | * Save the restore options for this tracker, but do not restore yet.
|
221 | *
|
222 | * @param options - The configuration options that describe restoration.
|
223 | *
|
224 | * ### Notes
|
225 | * This function is useful when starting the shell in 'single-document' mode,
|
226 | * to avoid restoring all useless widgets. It should not ordinarily be called
|
227 | * by client code.
|
228 | */
|
229 | defer(options: IRestorable.IOptions<T>): void;
|
230 | /**
|
231 | * Save the restore data for a given widget.
|
232 | *
|
233 | * @param widget - The widget being saved.
|
234 | */
|
235 | save(widget: T): Promise<void>;
|
236 | /**
|
237 | * Handle the current change event.
|
238 | *
|
239 | * #### Notes
|
240 | * The default implementation is a no-op.
|
241 | */
|
242 | protected onCurrentChanged(value: T | null): void;
|
243 | private _currentChanged;
|
244 | private _deferred;
|
245 | private _focusTracker;
|
246 | private _pool;
|
247 | private _isDisposed;
|
248 | private _widgetAdded;
|
249 | private _widgetUpdated;
|
250 | }
|
251 | /**
|
252 | * A namespace for `WidgetTracker` statics.
|
253 | */
|
254 | export declare namespace WidgetTracker {
|
255 | |
256 |
|
257 |
|
258 | interface IOptions {
|
259 | |
260 |
|
261 |
|
262 | namespace: string;
|
263 | }
|
264 | }
|