UNPKG

8.81 kBTypeScriptView Raw
1import { IRestorable } from '@jupyterlab/statedb';
2import { IDisposable } from '@lumino/disposable';
3import { ISignal } from '@lumino/signaling';
4import { Widget } from '@lumino/widgets';
5/**
6 * A tracker that tracks widgets.
7 *
8 * @typeparam T - The type of widget being tracked. Defaults to `Widget`.
9 */
10export interface IWidgetTracker<T extends Widget = Widget> extends IDisposable {
11 /**
12 * A signal emitted when a widget is added.
13 */
14 readonly widgetAdded: ISignal<this, T>;
15 /**
16 * The current widget is the most recently focused or added widget.
17 *
18 * #### Notes
19 * It is the most recently focused widget, or the most recently added
20 * widget if no widget has taken focus.
21 */
22 readonly currentWidget: T | null;
23 /**
24 * A signal emitted when the current instance changes.
25 *
26 * #### Notes
27 * If the last instance being tracked is disposed, `null` will be emitted.
28 */
29 readonly currentChanged: ISignal<this, T | null>;
30 /**
31 * The number of instances held by the tracker.
32 */
33 readonly size: number;
34 /**
35 * A promise that is resolved when the widget tracker has been
36 * restored from a serialized state.
37 *
38 * #### Notes
39 * Most client code will not need to use this, since they can wait
40 * for the whole application to restore. However, if an extension
41 * wants to perform actions during the application restoration, but
42 * after the restoration of another widget tracker, they can use
43 * this promise.
44 */
45 readonly restored: Promise<void>;
46 /**
47 * A signal emitted when a widget is updated.
48 */
49 readonly widgetUpdated: ISignal<this, T>;
50 /**
51 * Find the first instance in the tracker that satisfies a filter function.
52 *
53 * @param - fn The filter function to call on each instance.
54 *
55 * #### Notes
56 * If nothing is found, the value returned is `undefined`.
57 */
58 find(fn: (obj: T) => boolean): T | undefined;
59 /**
60 * Iterate through each instance in the tracker.
61 *
62 * @param fn - The function to call on each instance.
63 */
64 forEach(fn: (obj: T) => void): void;
65 /**
66 * Filter the instances in the tracker based on a predicate.
67 *
68 * @param fn - The function by which to filter.
69 */
70 filter(fn: (obj: T) => boolean): T[];
71 /**
72 * Check if this tracker has the specified instance.
73 *
74 * @param obj - The object whose existence is being checked.
75 */
76 has(obj: Widget): boolean;
77 /**
78 * Inject an instance into the widget tracker without the tracker handling
79 * its restoration lifecycle.
80 *
81 * @param obj - The instance to inject into the tracker.
82 */
83 inject(obj: T): void;
84}
85/**
86 * A class that keeps track of widget instances on an Application shell.
87 *
88 * @typeparam T - The type of widget being tracked. Defaults to `Widget`.
89 *
90 * #### Notes
91 * The API surface area of this concrete implementation is substantially larger
92 * than the widget tracker interface it implements. The interface is intended
93 * for export by JupyterLab plugins that create widgets and have clients who may
94 * wish to keep track of newly created widgets. This class, however, can be used
95 * internally by plugins to restore state as well.
96 */
97export declare class WidgetTracker<T extends Widget = Widget> implements IWidgetTracker<T>, IRestorable<T> {
98 /**
99 * Create a new widget tracker.
100 *
101 * @param options - The instantiation options for a widget tracker.
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 */
254export declare namespace WidgetTracker {
255 /**
256 * The instantiation options for a widget tracker.
257 */
258 interface IOptions {
259 /**
260 * A namespace for all tracked widgets, (e.g., `notebook`).
261 */
262 namespace: string;
263 }
264}