1 | import { ReadonlyJSONObject } from '@lumino/coreutils';
|
2 | import { CommandRegistry } from '@lumino/commands';
|
3 | import { Message } from '@lumino/messaging';
|
4 | import { ElementDataset, h, VirtualElement } from '@lumino/virtualdom';
|
5 | import { Widget } from './widget';
|
6 | /**
|
7 | * A widget which displays command items as a searchable palette.
|
8 | */
|
9 | export declare class CommandPalette extends Widget {
|
10 | /**
|
11 | * Construct a new command palette.
|
12 | *
|
13 | * @param options - The options for initializing the palette.
|
14 | */
|
15 | constructor(options: CommandPalette.IOptions);
|
16 | /**
|
17 | * Dispose of the resources held by the widget.
|
18 | */
|
19 | dispose(): void;
|
20 | /**
|
21 | * The command registry used by the command palette.
|
22 | */
|
23 | readonly commands: CommandRegistry;
|
24 | /**
|
25 | * The renderer used by the command palette.
|
26 | */
|
27 | readonly renderer: CommandPalette.IRenderer;
|
28 | /**
|
29 | * The command palette search node.
|
30 | *
|
31 | * #### Notes
|
32 | * This is the node which contains the search-related elements.
|
33 | */
|
34 | readonly searchNode: HTMLDivElement;
|
35 | /**
|
36 | * The command palette input node.
|
37 | *
|
38 | * #### Notes
|
39 | * This is the actual input node for the search area.
|
40 | */
|
41 | readonly inputNode: HTMLInputElement;
|
42 | /**
|
43 | * The command palette content node.
|
44 | *
|
45 | * #### Notes
|
46 | * This is the node which holds the command item nodes.
|
47 | *
|
48 | * Modifying this node directly can lead to undefined behavior.
|
49 | */
|
50 | readonly contentNode: HTMLUListElement;
|
51 | /**
|
52 | * A read-only array of the command items in the palette.
|
53 | */
|
54 | readonly items: ReadonlyArray<CommandPalette.IItem>;
|
55 | /**
|
56 | * Add a command item to the command palette.
|
57 | *
|
58 | * @param options - The options for creating the command item.
|
59 | *
|
60 | * @returns The command item added to the palette.
|
61 | */
|
62 | addItem(options: CommandPalette.IItemOptions): CommandPalette.IItem;
|
63 | /**
|
64 | * Adds command items to the command palette.
|
65 | *
|
66 | * @param items - An array of options for creating each command item.
|
67 | *
|
68 | * @returns The command items added to the palette.
|
69 | */
|
70 | addItems(items: CommandPalette.IItemOptions[]): CommandPalette.IItem[];
|
71 | /**
|
72 | * Remove an item from the command palette.
|
73 | *
|
74 | * @param item - The item to remove from the palette.
|
75 | *
|
76 | * #### Notes
|
77 | * This is a no-op if the item is not in the palette.
|
78 | */
|
79 | removeItem(item: CommandPalette.IItem): void;
|
80 | /**
|
81 | * Remove the item at a given index from the command palette.
|
82 | *
|
83 | * @param index - The index of the item to remove.
|
84 | *
|
85 | * #### Notes
|
86 | * This is a no-op if the index is out of range.
|
87 | */
|
88 | removeItemAt(index: number): void;
|
89 | /**
|
90 | * Remove all items from the command palette.
|
91 | */
|
92 | clearItems(): void;
|
93 | /**
|
94 | * Clear the search results and schedule an update.
|
95 | *
|
96 | * #### Notes
|
97 | * This should be called whenever the search results of the palette
|
98 | * should be updated.
|
99 | *
|
100 | * This is typically called automatically by the palette as needed,
|
101 | * but can be called manually if the input text is programatically
|
102 | * changed.
|
103 | *
|
104 | * The rendered results are updated asynchronously.
|
105 | */
|
106 | refresh(): void;
|
107 | /**
|
108 | * Handle the DOM events for the command palette.
|
109 | *
|
110 | * @param event - The DOM event sent to the command palette.
|
111 | *
|
112 | * #### Notes
|
113 | * This method implements the DOM `EventListener` interface and is
|
114 | * called in response to events on the command palette's DOM node.
|
115 | * It should not be called directly by user code.
|
116 | */
|
117 | handleEvent(event: Event): void;
|
118 | /**
|
119 | * A message handler invoked on a `'before-attach'` message.
|
120 | */
|
121 | protected onBeforeAttach(msg: Message): void;
|
122 | /**
|
123 | * A message handler invoked on an `'after-detach'` message.
|
124 | */
|
125 | protected onAfterDetach(msg: Message): void;
|
126 | /**
|
127 | * A message handler invoked on an `'activate-request'` message.
|
128 | */
|
129 | protected onActivateRequest(msg: Message): void;
|
130 | /**
|
131 | * A message handler invoked on an `'update-request'` message.
|
132 | */
|
133 | protected onUpdateRequest(msg: Message): void;
|
134 | /**
|
135 | * Handle the `'click'` event for the command palette.
|
136 | */
|
137 | private _evtClick;
|
138 | /**
|
139 | * Handle the `'keydown'` event for the command palette.
|
140 | */
|
141 | private _evtKeyDown;
|
142 | /**
|
143 | * Activate the next enabled command item.
|
144 | */
|
145 | private _activateNextItem;
|
146 | /**
|
147 | * Activate the previous enabled command item.
|
148 | */
|
149 | private _activatePreviousItem;
|
150 | /**
|
151 | * Execute the command item at the given index, if possible.
|
152 | */
|
153 | private _execute;
|
154 | /**
|
155 | * Toggle the focused modifier based on the input node focus state.
|
156 | */
|
157 | private _toggleFocused;
|
158 | /**
|
159 | * A signal handler for generic command changes.
|
160 | */
|
161 | private _onGenericChange;
|
162 | private _activeIndex;
|
163 | private _items;
|
164 | private _results;
|
165 | }
|
166 | /**
|
167 | * The namespace for the `CommandPalette` class statics.
|
168 | */
|
169 | export declare namespace CommandPalette {
|
170 | /**
|
171 | * An options object for creating a command palette.
|
172 | */
|
173 | interface IOptions {
|
174 | /**
|
175 | * The command registry for use with the command palette.
|
176 | */
|
177 | commands: CommandRegistry;
|
178 | /**
|
179 | * A custom renderer for use with the command palette.
|
180 | *
|
181 | * The default is a shared renderer instance.
|
182 | */
|
183 | renderer?: IRenderer;
|
184 | }
|
185 | /**
|
186 | * An options object for creating a command item.
|
187 | */
|
188 | interface IItemOptions {
|
189 | /**
|
190 | * The category for the item.
|
191 | */
|
192 | category: string;
|
193 | /**
|
194 | * The command to execute when the item is triggered.
|
195 | */
|
196 | command: string;
|
197 | /**
|
198 | * The arguments for the command.
|
199 | *
|
200 | * The default value is an empty object.
|
201 | */
|
202 | args?: ReadonlyJSONObject;
|
203 | /**
|
204 | * The rank for the command item.
|
205 | *
|
206 | * The rank is used as a tie-breaker when ordering command items
|
207 | * for display. Items are sorted in the following order:
|
208 | * 1. Text match (lower is better)
|
209 | * 2. Category (locale order)
|
210 | * 3. Rank (lower is better)
|
211 | * 4. Label (locale order)
|
212 | *
|
213 | * The default rank is `Infinity`.
|
214 | */
|
215 | rank?: number;
|
216 | }
|
217 | /**
|
218 | * An object which represents an item in a command palette.
|
219 | *
|
220 | * #### Notes
|
221 | * Item objects are created automatically by a command palette.
|
222 | */
|
223 | interface IItem {
|
224 | /**
|
225 | * The command to execute when the item is triggered.
|
226 | */
|
227 | readonly command: string;
|
228 | /**
|
229 | * The arguments for the command.
|
230 | */
|
231 | readonly args: ReadonlyJSONObject;
|
232 | /**
|
233 | * The category for the command item.
|
234 | */
|
235 | readonly category: string;
|
236 | /**
|
237 | * The rank for the command item.
|
238 | */
|
239 | readonly rank: number;
|
240 | /**
|
241 | * The display label for the command item.
|
242 | */
|
243 | readonly label: string;
|
244 | /**
|
245 | * The display caption for the command item.
|
246 | */
|
247 | readonly caption: string;
|
248 | /**
|
249 | * The icon renderer for the command item.
|
250 | */
|
251 | readonly icon: VirtualElement.IRenderer | undefined | string;
|
252 | /**
|
253 | * The icon class for the command item.
|
254 | */
|
255 | readonly iconClass: string;
|
256 | /**
|
257 | * The icon label for the command item.
|
258 | */
|
259 | readonly iconLabel: string;
|
260 | /**
|
261 | * The extra class name for the command item.
|
262 | */
|
263 | readonly className: string;
|
264 | /**
|
265 | * The dataset for the command item.
|
266 | */
|
267 | readonly dataset: CommandRegistry.Dataset;
|
268 | /**
|
269 | * Whether the command item is enabled.
|
270 | */
|
271 | readonly isEnabled: boolean;
|
272 | /**
|
273 | * Whether the command item is toggled.
|
274 | */
|
275 | readonly isToggled: boolean;
|
276 | /**
|
277 | * Whether the command item is toggleable.
|
278 | */
|
279 | readonly isToggleable: boolean;
|
280 | /**
|
281 | * Whether the command item is visible.
|
282 | */
|
283 | readonly isVisible: boolean;
|
284 | /**
|
285 | * The key binding for the command item.
|
286 | */
|
287 | readonly keyBinding: CommandRegistry.IKeyBinding | null;
|
288 | }
|
289 | /**
|
290 | * The render data for a command palette header.
|
291 | */
|
292 | interface IHeaderRenderData {
|
293 | /**
|
294 | * The category of the header.
|
295 | */
|
296 | readonly category: string;
|
297 | /**
|
298 | * The indices of the matched characters in the category.
|
299 | */
|
300 | readonly indices: ReadonlyArray<number> | null;
|
301 | }
|
302 | /**
|
303 | * The render data for a command palette item.
|
304 | */
|
305 | interface IItemRenderData {
|
306 | /**
|
307 | * The command palette item to render.
|
308 | */
|
309 | readonly item: IItem;
|
310 | /**
|
311 | * The indices of the matched characters in the label.
|
312 | */
|
313 | readonly indices: ReadonlyArray<number> | null;
|
314 | /**
|
315 | * Whether the item is the active item.
|
316 | */
|
317 | readonly active: boolean;
|
318 | }
|
319 | /**
|
320 | * The render data for a command palette empty message.
|
321 | */
|
322 | interface IEmptyMessageRenderData {
|
323 | /**
|
324 | * The query which failed to match any commands.
|
325 | */
|
326 | query: string;
|
327 | }
|
328 | /**
|
329 | * A renderer for use with a command palette.
|
330 | */
|
331 | interface IRenderer {
|
332 | /**
|
333 | * Render the virtual element for a command palette header.
|
334 | *
|
335 | * @param data - The data to use for rendering the header.
|
336 | *
|
337 | * @returns A virtual element representing the header.
|
338 | */
|
339 | renderHeader(data: IHeaderRenderData): VirtualElement;
|
340 | /**
|
341 | * Render the virtual element for a command palette item.
|
342 | *
|
343 | * @param data - The data to use for rendering the item.
|
344 | *
|
345 | * @returns A virtual element representing the item.
|
346 | *
|
347 | * #### Notes
|
348 | * The command palette will not render invisible items.
|
349 | */
|
350 | renderItem(data: IItemRenderData): VirtualElement;
|
351 | /**
|
352 | * Render the empty results message for a command palette.
|
353 | *
|
354 | * @param data - The data to use for rendering the message.
|
355 | *
|
356 | * @returns A virtual element representing the message.
|
357 | */
|
358 | renderEmptyMessage(data: IEmptyMessageRenderData): VirtualElement;
|
359 | }
|
360 | /**
|
361 | * The default implementation of `IRenderer`.
|
362 | */
|
363 | class Renderer implements IRenderer {
|
364 | /**
|
365 | * Render the virtual element for a command palette header.
|
366 | *
|
367 | * @param data - The data to use for rendering the header.
|
368 | *
|
369 | * @returns A virtual element representing the header.
|
370 | */
|
371 | renderHeader(data: IHeaderRenderData): VirtualElement;
|
372 | /**
|
373 | * Render the virtual element for a command palette item.
|
374 | *
|
375 | * @param data - The data to use for rendering the item.
|
376 | *
|
377 | * @returns A virtual element representing the item.
|
378 | */
|
379 | renderItem(data: IItemRenderData): VirtualElement;
|
380 | /**
|
381 | * Render the empty results message for a command palette.
|
382 | *
|
383 | * @param data - The data to use for rendering the message.
|
384 | *
|
385 | * @returns A virtual element representing the message.
|
386 | */
|
387 | renderEmptyMessage(data: IEmptyMessageRenderData): VirtualElement;
|
388 | /**
|
389 | * Render the icon for a command palette item.
|
390 | *
|
391 | * @param data - The data to use for rendering the icon.
|
392 | *
|
393 | * @returns A virtual element representing the icon.
|
394 | */
|
395 | renderItemIcon(data: IItemRenderData): VirtualElement;
|
396 | /**
|
397 | * Render the content for a command palette item.
|
398 | *
|
399 | * @param data - The data to use for rendering the content.
|
400 | *
|
401 | * @returns A virtual element representing the content.
|
402 | */
|
403 | renderItemContent(data: IItemRenderData): VirtualElement;
|
404 | /**
|
405 | * Render the label for a command palette item.
|
406 | *
|
407 | * @param data - The data to use for rendering the label.
|
408 | *
|
409 | * @returns A virtual element representing the label.
|
410 | */
|
411 | renderItemLabel(data: IItemRenderData): VirtualElement;
|
412 | /**
|
413 | * Render the caption for a command palette item.
|
414 | *
|
415 | * @param data - The data to use for rendering the caption.
|
416 | *
|
417 | * @returns A virtual element representing the caption.
|
418 | */
|
419 | renderItemCaption(data: IItemRenderData): VirtualElement;
|
420 | /**
|
421 | * Render the shortcut for a command palette item.
|
422 | *
|
423 | * @param data - The data to use for rendering the shortcut.
|
424 | *
|
425 | * @returns A virtual element representing the shortcut.
|
426 | */
|
427 | renderItemShortcut(data: IItemRenderData): VirtualElement;
|
428 | /**
|
429 | * Create the class name for the command palette item.
|
430 | *
|
431 | * @param data - The data to use for the class name.
|
432 | *
|
433 | * @returns The full class name for the command palette item.
|
434 | */
|
435 | createItemClass(data: IItemRenderData): string;
|
436 | /**
|
437 | * Create the dataset for the command palette item.
|
438 | *
|
439 | * @param data - The data to use for creating the dataset.
|
440 | *
|
441 | * @returns The dataset for the command palette item.
|
442 | */
|
443 | createItemDataset(data: IItemRenderData): ElementDataset;
|
444 | /**
|
445 | * Create the class name for the command item icon.
|
446 | *
|
447 | * @param data - The data to use for the class name.
|
448 | *
|
449 | * @returns The full class name for the item icon.
|
450 | */
|
451 | createIconClass(data: IItemRenderData): string;
|
452 | /**
|
453 | * Create the render content for the header node.
|
454 | *
|
455 | * @param data - The data to use for the header content.
|
456 | *
|
457 | * @returns The content to add to the header node.
|
458 | */
|
459 | formatHeader(data: IHeaderRenderData): h.Child;
|
460 | /**
|
461 | * Create the render content for the empty message node.
|
462 | *
|
463 | * @param data - The data to use for the empty message content.
|
464 | *
|
465 | * @returns The content to add to the empty message node.
|
466 | */
|
467 | formatEmptyMessage(data: IEmptyMessageRenderData): h.Child;
|
468 | /**
|
469 | * Create the render content for the item shortcut node.
|
470 | *
|
471 | * @param data - The data to use for the shortcut content.
|
472 | *
|
473 | * @returns The content to add to the shortcut node.
|
474 | */
|
475 | formatItemShortcut(data: IItemRenderData): h.Child;
|
476 | /**
|
477 | * Create the render content for the item label node.
|
478 | *
|
479 | * @param data - The data to use for the label content.
|
480 | *
|
481 | * @returns The content to add to the label node.
|
482 | */
|
483 | formatItemLabel(data: IItemRenderData): h.Child;
|
484 | /**
|
485 | * Create the render content for the item caption node.
|
486 | *
|
487 | * @param data - The data to use for the caption content.
|
488 | *
|
489 | * @returns The content to add to the caption node.
|
490 | */
|
491 | formatItemCaption(data: IItemRenderData): h.Child;
|
492 | }
|
493 | /**
|
494 | * The default `Renderer` instance.
|
495 | */
|
496 | const defaultRenderer: Renderer;
|
497 | }
|
498 | //# sourceMappingURL=commandpalette.d.ts.map |
\ | No newline at end of file |