1 | import { CommandLinker } from '@jupyterlab/apputils';
|
2 | import { DocumentRegistry } from '@jupyterlab/docregistry';
|
3 | import { ServiceManager } from '@jupyterlab/services';
|
4 | import { ContextMenuSvg } from '@jupyterlab/ui-components';
|
5 | import { IIterator } from '@lumino/algorithm';
|
6 | import { Application, IPlugin } from '@lumino/application';
|
7 | import { Token } from '@lumino/coreutils';
|
8 | import { ISignal } from '@lumino/signaling';
|
9 | import { Widget } from '@lumino/widgets';
|
10 | /**
|
11 | * The type for all JupyterFrontEnd application plugins.
|
12 | *
|
13 | * @typeparam T - The type that the plugin `provides` upon being activated.
|
14 | *
|
15 | * @typeparam U - The type of the application shell.
|
16 | *
|
17 | * @typeparam V - The type that defines the application formats.
|
18 | */
|
19 | export declare type JupyterFrontEndPlugin<T, U extends JupyterFrontEnd.IShell = JupyterFrontEnd.IShell, V extends string = 'desktop' | 'mobile'> = IPlugin<JupyterFrontEnd<U, V>, T>;
|
20 | /**
|
21 | * The base Jupyter front-end application class.
|
22 | *
|
23 | * @typeparam `T` - The `shell` type. Defaults to `JupyterFrontEnd.IShell`.
|
24 | *
|
25 | * @typeparam `U` - The type for supported format names. Defaults to `string`.
|
26 | *
|
27 | * #### Notes
|
28 | * This type is useful as a generic application against which front-end plugins
|
29 | * can be authored. It inherits from the Lumino `Application`.
|
30 | */
|
31 | export declare abstract class JupyterFrontEnd<T extends JupyterFrontEnd.IShell = JupyterFrontEnd.IShell, U extends string = 'desktop' | 'mobile'> extends Application<T> {
|
32 | /**
|
33 | * Construct a new JupyterFrontEnd object.
|
34 | */
|
35 | constructor(options: JupyterFrontEnd.IOptions<T>);
|
36 | /**
|
37 | * The name of this Jupyter front-end application.
|
38 | */
|
39 | abstract readonly name: string;
|
40 | /**
|
41 | * A namespace/prefix plugins may use to denote their provenance.
|
42 | */
|
43 | abstract readonly namespace: string;
|
44 | /**
|
45 | * The version of this Jupyter front-end application.
|
46 | */
|
47 | abstract readonly version: string;
|
48 | /**
|
49 | * The command linker used by the application.
|
50 | */
|
51 | readonly commandLinker: CommandLinker;
|
52 | /**
|
53 | * The application context menu.
|
54 | */
|
55 | readonly contextMenu: ContextMenuSvg;
|
56 | /**
|
57 | * The document registry instance used by the application.
|
58 | */
|
59 | readonly docRegistry: DocumentRegistry;
|
60 | /**
|
61 | * Promise that resolves when state is first restored.
|
62 | */
|
63 | readonly restored: Promise<void>;
|
64 | /**
|
65 | * The service manager used by the application.
|
66 | */
|
67 | readonly serviceManager: ServiceManager;
|
68 | /**
|
69 | * The application form factor, e.g., `desktop` or `mobile`.
|
70 | */
|
71 | get format(): U;
|
72 | set format(format: U);
|
73 | /**
|
74 | * A signal that emits when the application form factor changes.
|
75 | */
|
76 | get formatChanged(): ISignal<this, U>;
|
77 | /**
|
78 | * Walks up the DOM hierarchy of the target of the active `contextmenu`
|
79 | * event, testing each HTMLElement ancestor for a user-supplied function. This can
|
80 | * be used to find an HTMLElement on which to operate, given a context menu click.
|
81 | *
|
82 | * @param fn - a function that takes an `HTMLElement` and returns a
|
83 | * boolean for whether it is the element the requester is seeking.
|
84 | *
|
85 | * @returns an HTMLElement or undefined, if none is found.
|
86 | */
|
87 | contextMenuHitTest(fn: (node: HTMLElement) => boolean): HTMLElement | undefined;
|
88 | /**
|
89 | * A method invoked on a document `'contextmenu'` event.
|
90 | */
|
91 | protected evtContextMenu(event: MouseEvent): void;
|
92 | private _contextMenuEvent;
|
93 | private _format;
|
94 | private _formatChanged;
|
95 | }
|
96 | /**
|
97 | * The namespace for `JupyterFrontEnd` class statics.
|
98 | */
|
99 | export declare namespace JupyterFrontEnd {
|
100 | /**
|
101 | * The options used to initialize a JupyterFrontEnd.
|
102 | */
|
103 | interface IOptions<T extends IShell = IShell, U = any> extends Application.IOptions<T> {
|
104 | /**
|
105 | * The document registry instance used by the application.
|
106 | */
|
107 | docRegistry?: DocumentRegistry;
|
108 | /**
|
109 | * The command linker used by the application.
|
110 | */
|
111 | commandLinker?: CommandLinker;
|
112 | /**
|
113 | * The service manager used by the application.
|
114 | */
|
115 | serviceManager?: ServiceManager;
|
116 | /**
|
117 | * Promise that resolves when state is first restored, returning layout
|
118 | * description.
|
119 | */
|
120 | restored?: Promise<U>;
|
121 | }
|
122 | /**
|
123 | * A minimal shell type for Jupyter front-end applications.
|
124 | */
|
125 | interface IShell extends Widget {
|
126 | /**
|
127 | * Activates a widget inside the application shell.
|
128 | *
|
129 | * @param id - The ID of the widget being activated.
|
130 | */
|
131 | activateById(id: string): void;
|
132 | /**
|
133 | * Add a widget to the application shell.
|
134 | *
|
135 | * @param widget - The widget being added.
|
136 | *
|
137 | * @param area - Optional region in the shell into which the widget should
|
138 | * be added.
|
139 | *
|
140 | * @param options - Optional flags the shell might use when opening the
|
141 | * widget, as defined in the `DocumentRegistry`.
|
142 | */
|
143 | add(widget: Widget, area?: string, options?: DocumentRegistry.IOpenOptions): void;
|
144 | /**
|
145 | * The focused widget in the application shell.
|
146 | *
|
147 | * #### Notes
|
148 | * Different shell implementations have latitude to decide what "current"
|
149 | * or "focused" mean, depending on their user interface characteristics.
|
150 | */
|
151 | readonly currentWidget: Widget | null;
|
152 | /**
|
153 | * Returns an iterator for the widgets inside the application shell.
|
154 | *
|
155 | * @param area - Optional regions in the shell whose widgets are iterated.
|
156 | */
|
157 | widgets(area?: string): IIterator<Widget>;
|
158 | }
|
159 | /**
|
160 | * Is JupyterLab in document mode?
|
161 | *
|
162 | * @param path - Full URL of JupyterLab
|
163 | * @param paths - The current IPaths object hydrated from PageConfig.
|
164 | */
|
165 | function inDocMode(path: string, paths: IPaths): boolean;
|
166 | /**
|
167 | * The application paths dictionary token.
|
168 | */
|
169 | const IPaths: Token<IPaths>;
|
170 | /**
|
171 | * An interface for URL and directory paths used by a Jupyter front-end.
|
172 | */
|
173 | interface IPaths {
|
174 | /**
|
175 | * The urls used by the application.
|
176 | */
|
177 | readonly urls: {
|
178 | readonly base: string;
|
179 | readonly notFound?: string;
|
180 | readonly app: string;
|
181 | readonly doc: string;
|
182 | readonly static: string;
|
183 | readonly settings: string;
|
184 | readonly themes: string;
|
185 | readonly translations: string;
|
186 | readonly hubPrefix?: string;
|
187 | readonly hubHost?: string;
|
188 | readonly hubUser?: string;
|
189 | readonly hubServerName?: string;
|
190 | };
|
191 | /**
|
192 | * The server directories used by the application, for user information
|
193 | * only.
|
194 | *
|
195 | * #### Notes
|
196 | * These are for user information and user interface hints only and should
|
197 | * not be relied on in code. A server may set these to empty strings if it
|
198 | * does not want to expose this information.
|
199 | *
|
200 | * Examples of appropriate use include displaying a help dialog for a user
|
201 | * listing the paths, or a tooltip in a filebrowser displaying the server
|
202 | * root. Examples of inappropriate use include using one of these paths in a
|
203 | * terminal command, generating code using these paths, or using one of
|
204 | * these paths in a request to the server (it would be better to write a
|
205 | * server extension to handle these cases).
|
206 | */
|
207 | readonly directories: {
|
208 | readonly appSettings: string;
|
209 | readonly schemas: string;
|
210 | readonly static: string;
|
211 | readonly templates: string;
|
212 | readonly themes: string;
|
213 | readonly userSettings: string;
|
214 | readonly serverRoot: string;
|
215 | readonly workspaces: string;
|
216 | };
|
217 | }
|
218 | /**
|
219 | * The application tree resolver token.
|
220 | *
|
221 | * #### Notes
|
222 | * Not all Jupyter front-end applications will have a tree resolver
|
223 | * implemented on the client-side. This token should not be required as a
|
224 | * dependency if it is possible to make it an optional dependency.
|
225 | */
|
226 | const ITreeResolver: Token<ITreeResolver>;
|
227 | /**
|
228 | * An interface for a front-end tree route resolver.
|
229 | */
|
230 | interface ITreeResolver {
|
231 | /**
|
232 | * A promise that resolves to the routed tree paths or null.
|
233 | */
|
234 | readonly paths: Promise<ITreeResolver.Paths>;
|
235 | }
|
236 | /**
|
237 | * A namespace for tree resolver types.
|
238 | */
|
239 | namespace ITreeResolver {
|
240 | /**
|
241 | * The browser and file paths if the tree resolver encountered and handled
|
242 | * a tree URL or `null` if not. Empty string paths should be ignored.
|
243 | */
|
244 | type Paths = {
|
245 | browser: string;
|
246 | file: string;
|
247 | } | null;
|
248 | }
|
249 | }
|
250 | /**
|
251 | * A namespace for the context menu override.
|
252 | */
|
253 | export declare namespace JupyterFrontEndContextMenu {
|
254 | /**
|
255 | * An id for a private context-menu-info ersatz command.
|
256 | */
|
257 | const contextMenu = "__internal:context-menu-info";
|
258 | }
|