1 | import { CommandRegistry } from '@phosphor/commands';
|
2 | import { ReadonlyJSONObject } from '@phosphor/coreutils';
|
3 | import { Message } from '@phosphor/messaging';
|
4 | import { ISignal } from '@phosphor/signaling';
|
5 | import { ElementDataset, VirtualElement, h } from '@phosphor/virtualdom';
|
6 | import { Widget } from './widget';
|
7 |
|
8 |
|
9 |
|
10 | export declare class Menu extends Widget {
|
11 | |
12 |
|
13 |
|
14 |
|
15 |
|
16 | constructor(options: Menu.IOptions);
|
17 | /**
|
18 | * Dispose of the resources held by the menu.
|
19 | */
|
20 | dispose(): void;
|
21 | /**
|
22 | * A signal emitted just before the menu is closed.
|
23 | *
|
24 | * #### Notes
|
25 | * This signal is emitted when the menu receives a `'close-request'`
|
26 | * message, just before it removes itself from the DOM.
|
27 | *
|
28 | * This signal is not emitted if the menu is already detached from
|
29 | * the DOM when it receives the `'close-request'` message.
|
30 | */
|
31 | readonly aboutToClose: ISignal<this, void>;
|
32 | /**
|
33 | * A signal emitted when a new menu is requested by the user.
|
34 | *
|
35 | * #### Notes
|
36 | * This signal is emitted whenever the user presses the right or left
|
37 | * arrow keys, and a submenu cannot be opened or closed in response.
|
38 | *
|
39 | * This signal is useful when implementing menu bars in order to open
|
40 | * the next or previous menu in response to a user key press.
|
41 | *
|
42 | * This signal is only emitted for the root menu in a hierarchy.
|
43 | */
|
44 | readonly menuRequested: ISignal<this, 'next' | 'previous'>;
|
45 | /**
|
46 | * The command registry used by the menu.
|
47 | */
|
48 | readonly commands: CommandRegistry;
|
49 | /**
|
50 | * The renderer used by the menu.
|
51 | */
|
52 | readonly renderer: Menu.IRenderer;
|
53 | /**
|
54 | * The parent menu of the menu.
|
55 | *
|
56 | * #### Notes
|
57 | * This is `null` unless the menu is an open submenu.
|
58 | */
|
59 | readonly parentMenu: Menu | null;
|
60 | /**
|
61 | * The child menu of the menu.
|
62 | *
|
63 | * #### Notes
|
64 | * This is `null` unless the menu has an open submenu.
|
65 | */
|
66 | readonly childMenu: Menu | null;
|
67 | /**
|
68 | * The root menu of the menu hierarchy.
|
69 | */
|
70 | readonly rootMenu: Menu;
|
71 | /**
|
72 | * The leaf menu of the menu hierarchy.
|
73 | */
|
74 | readonly leafMenu: Menu;
|
75 | /**
|
76 | * The menu content node.
|
77 | *
|
78 | * #### Notes
|
79 | * This is the node which holds the menu item nodes.
|
80 | *
|
81 | * Modifying this node directly can lead to undefined behavior.
|
82 | */
|
83 | readonly contentNode: HTMLUListElement;
|
84 | /**
|
85 | * Get the currently active menu item.
|
86 | */
|
87 | /**
|
88 | * Set the currently active menu item.
|
89 | *
|
90 | * #### Notes
|
91 | * If the item cannot be activated, the item will be set to `null`.
|
92 | */
|
93 | activeItem: Menu.IItem | null;
|
94 | /**
|
95 | * Get the index of the currently active menu item.
|
96 | *
|
97 | * #### Notes
|
98 | * This will be `-1` if no menu item is active.
|
99 | */
|
100 | /**
|
101 | * Set the index of the currently active menu item.
|
102 | *
|
103 | * #### Notes
|
104 | * If the item cannot be activated, the index will be set to `-1`.
|
105 | */
|
106 | activeIndex: number;
|
107 | /**
|
108 | * A read-only array of the menu items in the menu.
|
109 | */
|
110 | readonly items: ReadonlyArray<Menu.IItem>;
|
111 | /**
|
112 | * Activate the next selectable item in the menu.
|
113 | *
|
114 | * #### Notes
|
115 | * If no item is selectable, the index will be set to `-1`.
|
116 | */
|
117 | activateNextItem(): void;
|
118 | /**
|
119 | * Activate the previous selectable item in the menu.
|
120 | *
|
121 | * #### Notes
|
122 | * If no item is selectable, the index will be set to `-1`.
|
123 | */
|
124 | activatePreviousItem(): void;
|
125 | /**
|
126 | * Trigger the active menu item.
|
127 | *
|
128 | * #### Notes
|
129 | * If the active item is a submenu, it will be opened and the first
|
130 | * item will be activated.
|
131 | *
|
132 | * If the active item is a command, the command will be executed.
|
133 | *
|
134 | * If the menu is not attached, this is a no-op.
|
135 | *
|
136 | * If there is no active item, this is a no-op.
|
137 | */
|
138 | triggerActiveItem(): void;
|
139 | /**
|
140 | * Add a menu item to the end of the menu.
|
141 | *
|
142 | * @param options - The options for creating the menu item.
|
143 | *
|
144 | * @returns The menu item added to the menu.
|
145 | */
|
146 | addItem(options: Menu.IItemOptions): Menu.IItem;
|
147 | /**
|
148 | * Insert a menu item into the menu at the specified index.
|
149 | *
|
150 | * @param index - The index at which to insert the item.
|
151 | *
|
152 | * @param options - The options for creating the menu item.
|
153 | *
|
154 | * @returns The menu item added to the menu.
|
155 | *
|
156 | * #### Notes
|
157 | * The index will be clamped to the bounds of the items.
|
158 | */
|
159 | insertItem(index: number, options: Menu.IItemOptions): Menu.IItem;
|
160 | /**
|
161 | * Remove an item from the menu.
|
162 | *
|
163 | * @param item - The item to remove from the menu.
|
164 | *
|
165 | * #### Notes
|
166 | * This is a no-op if the item is not in the menu.
|
167 | */
|
168 | removeItem(item: Menu.IItem): void;
|
169 | /**
|
170 | * Remove the item at a given index from the menu.
|
171 | *
|
172 | * @param index - The index of the item to remove.
|
173 | *
|
174 | * #### Notes
|
175 | * This is a no-op if the index is out of range.
|
176 | */
|
177 | removeItemAt(index: number): void;
|
178 | /**
|
179 | * Remove all menu items from the menu.
|
180 | */
|
181 | clearItems(): void;
|
182 | /**
|
183 | * Open the menu at the specified location.
|
184 | *
|
185 | * @param x - The client X coordinate of the menu location.
|
186 | *
|
187 | * @param y - The client Y coordinate of the menu location.
|
188 | *
|
189 | * @param options - The additional options for opening the menu.
|
190 | *
|
191 | * #### Notes
|
192 | * The menu will be opened at the given location unless it will not
|
193 | * fully fit on the screen. If it will not fit, it will be adjusted
|
194 | * to fit naturally on the screen.
|
195 | *
|
196 | * This is a no-op if the menu is already attached to the DOM.
|
197 | */
|
198 | open(x: number, y: number, options?: Menu.IOpenOptions): void;
|
199 | /**
|
200 | * Handle the DOM events for the menu.
|
201 | *
|
202 | * @param event - The DOM event sent to the menu.
|
203 | *
|
204 | * #### Notes
|
205 | * This method implements the DOM `EventListener` interface and is
|
206 | * called in response to events on the menu's DOM nodes. It should
|
207 | * not be called directly by user code.
|
208 | */
|
209 | handleEvent(event: Event): void;
|
210 | /**
|
211 | * A message handler invoked on a `'before-attach'` message.
|
212 | */
|
213 | protected onBeforeAttach(msg: Message): void;
|
214 | /**
|
215 | * A message handler invoked on an `'after-detach'` message.
|
216 | */
|
217 | protected onAfterDetach(msg: Message): void;
|
218 | /**
|
219 | * A message handler invoked on an `'activate-request'` message.
|
220 | */
|
221 | protected onActivateRequest(msg: Message): void;
|
222 | /**
|
223 | * A message handler invoked on an `'update-request'` message.
|
224 | */
|
225 | protected onUpdateRequest(msg: Message): void;
|
226 | /**
|
227 | * A message handler invoked on a `'close-request'` message.
|
228 | */
|
229 | protected onCloseRequest(msg: Message): void;
|
230 | /**
|
231 | * Handle the `'keydown'` event for the menu.
|
232 | *
|
233 | * #### Notes
|
234 | * This listener is attached to the menu node.
|
235 | */
|
236 | private _evtKeyDown;
|
237 | /**
|
238 | * Handle the `'mouseup'` event for the menu.
|
239 | *
|
240 | * #### Notes
|
241 | * This listener is attached to the menu node.
|
242 | */
|
243 | private _evtMouseUp;
|
244 | /**
|
245 | * Handle the `'mousemove'` event for the menu.
|
246 | *
|
247 | * #### Notes
|
248 | * This listener is attached to the menu node.
|
249 | */
|
250 | private _evtMouseMove;
|
251 | /**
|
252 | * Handle the `'mouseenter'` event for the menu.
|
253 | *
|
254 | * #### Notes
|
255 | * This listener is attached to the menu node.
|
256 | */
|
257 | private _evtMouseEnter;
|
258 | /**
|
259 | * Handle the `'mouseleave'` event for the menu.
|
260 | *
|
261 | * #### Notes
|
262 | * This listener is attached to the menu node.
|
263 | */
|
264 | private _evtMouseLeave;
|
265 | /**
|
266 | * Handle the `'mousedown'` event for the menu.
|
267 | *
|
268 | * #### Notes
|
269 | * This listener is attached to the document node.
|
270 | */
|
271 | private _evtMouseDown;
|
272 | /**
|
273 | * Open the child menu at the active index immediately.
|
274 | *
|
275 | * If a different child menu is already open, it will be closed,
|
276 | * even if the active item is not a valid submenu.
|
277 | */
|
278 | private _openChildMenu;
|
279 | /**
|
280 | * Close the child menu immediately.
|
281 | *
|
282 | * This is a no-op if a child menu is not open.
|
283 | */
|
284 | private _closeChildMenu;
|
285 | /**
|
286 | * Start the open timer, unless it is already pending.
|
287 | */
|
288 | private _startOpenTimer;
|
289 | /**
|
290 | * Start the close timer, unless it is already pending.
|
291 | */
|
292 | private _startCloseTimer;
|
293 | /**
|
294 | * Cancel the open timer, if the timer is pending.
|
295 | */
|
296 | private _cancelOpenTimer;
|
297 | /**
|
298 | * Cancel the close timer, if the timer is pending.
|
299 | */
|
300 | private _cancelCloseTimer;
|
301 | private _childIndex;
|
302 | private _activeIndex;
|
303 | private _openTimerID;
|
304 | private _closeTimerID;
|
305 | private _items;
|
306 | private _childMenu;
|
307 | private _parentMenu;
|
308 | private _aboutToClose;
|
309 | private _menuRequested;
|
310 | }
|
311 | /**
|
312 | * The namespace for the `Menu` class statics.
|
313 | */
|
314 | export declare namespace Menu {
|
315 | |
316 |
|
317 |
|
318 | interface IOptions {
|
319 | |
320 |
|
321 |
|
322 | commands: CommandRegistry;
|
323 | |
324 |
|
325 |
|
326 |
|
327 |
|
328 | renderer?: IRenderer;
|
329 | }
|
330 | |
331 |
|
332 |
|
333 | interface IOpenOptions {
|
334 | |
335 |
|
336 |
|
337 |
|
338 |
|
339 |
|
340 |
|
341 |
|
342 | forceX?: boolean;
|
343 | |
344 |
|
345 |
|
346 |
|
347 |
|
348 |
|
349 |
|
350 |
|
351 | forceY?: boolean;
|
352 | }
|
353 | |
354 |
|
355 |
|
356 | type ItemType = 'command' | 'submenu' | 'separator';
|
357 | |
358 |
|
359 |
|
360 | interface IItemOptions {
|
361 | |
362 |
|
363 |
|
364 |
|
365 |
|
366 | type?: ItemType;
|
367 | |
368 |
|
369 |
|
370 |
|
371 |
|
372 | command?: string;
|
373 | |
374 |
|
375 |
|
376 |
|
377 |
|
378 | args?: ReadonlyJSONObject;
|
379 | |
380 |
|
381 |
|
382 |
|
383 |
|
384 | submenu?: Menu | null;
|
385 | }
|
386 | |
387 |
|
388 |
|
389 |
|
390 |
|
391 |
|
392 | interface IItem {
|
393 | |
394 |
|
395 |
|
396 | readonly type: ItemType;
|
397 | |
398 |
|
399 |
|
400 | readonly command: string;
|
401 | |
402 |
|
403 |
|
404 | readonly args: ReadonlyJSONObject;
|
405 | |
406 |
|
407 |
|
408 | readonly submenu: Menu | null;
|
409 | |
410 |
|
411 |
|
412 | readonly label: string;
|
413 | |
414 |
|
415 |
|
416 | readonly mnemonic: number;
|
417 | |
418 |
|
419 |
|
420 | readonly icon: string;
|
421 | |
422 |
|
423 |
|
424 | readonly iconClass: string;
|
425 | |
426 |
|
427 |
|
428 | readonly iconLabel: string;
|
429 | |
430 |
|
431 |
|
432 | readonly caption: string;
|
433 | |
434 |
|
435 |
|
436 | readonly className: string;
|
437 | |
438 |
|
439 |
|
440 | readonly dataset: CommandRegistry.Dataset;
|
441 | |
442 |
|
443 |
|
444 | readonly isEnabled: boolean;
|
445 | |
446 |
|
447 |
|
448 | readonly isToggled: boolean;
|
449 | |
450 |
|
451 |
|
452 | readonly isVisible: boolean;
|
453 | |
454 |
|
455 |
|
456 | readonly keyBinding: CommandRegistry.IKeyBinding | null;
|
457 | }
|
458 | |
459 |
|
460 |
|
461 | interface IRenderData {
|
462 | |
463 |
|
464 |
|
465 | readonly item: IItem;
|
466 | |
467 |
|
468 |
|
469 | readonly active: boolean;
|
470 | |
471 |
|
472 |
|
473 | readonly collapsed: boolean;
|
474 | }
|
475 | |
476 |
|
477 |
|
478 | interface IRenderer {
|
479 | |
480 |
|
481 |
|
482 |
|
483 |
|
484 |
|
485 |
|
486 | renderItem(data: IRenderData): VirtualElement;
|
487 | }
|
488 | |
489 |
|
490 |
|
491 |
|
492 |
|
493 |
|
494 | class Renderer implements IRenderer {
|
495 | |
496 |
|
497 |
|
498 | constructor();
|
499 | /**
|
500 | * Render the virtual element for a menu item.
|
501 | *
|
502 | * @param data - The data to use for rendering the item.
|
503 | *
|
504 | * @returns A virtual element representing the item.
|
505 | */
|
506 | renderItem(data: IRenderData): VirtualElement;
|
507 | /**
|
508 | * Render the icon element for a menu item.
|
509 | *
|
510 | * @param data - The data to use for rendering the icon.
|
511 | *
|
512 | * @returns A virtual element representing the item icon.
|
513 | */
|
514 | renderIcon(data: IRenderData): VirtualElement;
|
515 | /**
|
516 | * Render the label element for a menu item.
|
517 | *
|
518 | * @param data - The data to use for rendering the label.
|
519 | *
|
520 | * @returns A virtual element representing the item label.
|
521 | */
|
522 | renderLabel(data: IRenderData): VirtualElement;
|
523 | /**
|
524 | * Render the shortcut element for a menu item.
|
525 | *
|
526 | * @param data - The data to use for rendering the shortcut.
|
527 | *
|
528 | * @returns A virtual element representing the item shortcut.
|
529 | */
|
530 | renderShortcut(data: IRenderData): VirtualElement;
|
531 | /**
|
532 | * Render the submenu icon element for a menu item.
|
533 | *
|
534 | * @param data - The data to use for rendering the submenu icon.
|
535 | *
|
536 | * @returns A virtual element representing the submenu icon.
|
537 | */
|
538 | renderSubmenu(data: IRenderData): VirtualElement;
|
539 | /**
|
540 | * Create the class name for the menu item.
|
541 | *
|
542 | * @param data - The data to use for the class name.
|
543 | *
|
544 | * @returns The full class name for the menu item.
|
545 | */
|
546 | createItemClass(data: IRenderData): string;
|
547 | /**
|
548 | * Create the dataset for the menu item.
|
549 | *
|
550 | * @param data - The data to use for creating the dataset.
|
551 | *
|
552 | * @returns The dataset for the menu item.
|
553 | */
|
554 | createItemDataset(data: IRenderData): ElementDataset;
|
555 | /**
|
556 | * Create the class name for the menu item icon.
|
557 | *
|
558 | * @param data - The data to use for the class name.
|
559 | *
|
560 | * @returns The full class name for the item icon.
|
561 | */
|
562 | createIconClass(data: IRenderData): string;
|
563 | /**
|
564 | * Create the render content for the label node.
|
565 | *
|
566 | * @param data - The data to use for the label content.
|
567 | *
|
568 | * @returns The content to add to the label node.
|
569 | */
|
570 | formatLabel(data: IRenderData): h.Child;
|
571 | /**
|
572 | * Create the render content for the shortcut node.
|
573 | *
|
574 | * @param data - The data to use for the shortcut content.
|
575 | *
|
576 | * @returns The content to add to the shortcut node.
|
577 | */
|
578 | formatShortcut(data: IRenderData): h.Child;
|
579 | }
|
580 | /**
|
581 | * The default `Renderer` instance.
|
582 | */
|
583 | const defaultRenderer: Renderer;
|
584 | }
|