1 | import { IObservableDisposable } from '@lumino/disposable';
|
2 | import { ConflatableMessage, IMessageHandler, Message } from '@lumino/messaging';
|
3 | import { ISignal } from '@lumino/signaling';
|
4 | import { Layout } from './layout';
|
5 | import { Title } from './title';
|
6 | /**
|
7 | * The base class of the lumino widget hierarchy.
|
8 | *
|
9 | * #### Notes
|
10 | * This class will typically be subclassed in order to create a useful
|
11 | * widget. However, it can be used directly to host externally created
|
12 | * content.
|
13 | */
|
14 | export declare class Widget implements IMessageHandler, IObservableDisposable {
|
15 | /**
|
16 | * Construct a new widget.
|
17 | *
|
18 | * @param options - The options for initializing the widget.
|
19 | */
|
20 | constructor(options?: Widget.IOptions);
|
21 | /**
|
22 | * Dispose of the widget and its descendant widgets.
|
23 | *
|
24 | * #### Notes
|
25 | * It is unsafe to use the widget after it has been disposed.
|
26 | *
|
27 | * All calls made to this method after the first are a no-op.
|
28 | */
|
29 | dispose(): void;
|
30 | /**
|
31 | * A signal emitted when the widget is disposed.
|
32 | */
|
33 | get disposed(): ISignal<this, void>;
|
34 | /**
|
35 | * Get the DOM node owned by the widget.
|
36 | */
|
37 | readonly node: HTMLElement;
|
38 | /**
|
39 | * Test whether the widget has been disposed.
|
40 | */
|
41 | get isDisposed(): boolean;
|
42 | /**
|
43 | * Test whether the widget's node is attached to the DOM.
|
44 | */
|
45 | get isAttached(): boolean;
|
46 | /**
|
47 | * Test whether the widget is explicitly hidden.
|
48 | */
|
49 | get isHidden(): boolean;
|
50 | /**
|
51 | * Test whether the widget is visible.
|
52 | *
|
53 | * #### Notes
|
54 | * A widget is visible when it is attached to the DOM, is not
|
55 | * explicitly hidden, and has no explicitly hidden ancestors.
|
56 | */
|
57 | get isVisible(): boolean;
|
58 | /**
|
59 | * The title object for the widget.
|
60 | *
|
61 | * #### Notes
|
62 | * The title object is used by some container widgets when displaying
|
63 | * the widget alongside some title, such as a tab panel or side bar.
|
64 | *
|
65 | * Since not all widgets will use the title, it is created on demand.
|
66 | *
|
67 | * The `owner` property of the title is set to this widget.
|
68 | */
|
69 | get title(): Title<Widget>;
|
70 | /**
|
71 | * Get the id of the widget's DOM node.
|
72 | */
|
73 | get id(): string;
|
74 | /**
|
75 | * Set the id of the widget's DOM node.
|
76 | */
|
77 | set id(value: string);
|
78 | /**
|
79 | * The dataset for the widget's DOM node.
|
80 | */
|
81 | get dataset(): DOMStringMap;
|
82 | /**
|
83 | * Get the method for hiding the widget.
|
84 | */
|
85 | get hiddenMode(): Widget.HiddenMode;
|
86 | /**
|
87 | * Set the method for hiding the widget.
|
88 | */
|
89 | set hiddenMode(value: Widget.HiddenMode);
|
90 | /**
|
91 | * Get the parent of the widget.
|
92 | */
|
93 | get parent(): Widget | null;
|
94 | /**
|
95 | * Set the parent of the widget.
|
96 | *
|
97 | * #### Notes
|
98 | * Children are typically added to a widget by using a layout, which
|
99 | * means user code will not normally set the parent widget directly.
|
100 | *
|
101 | * The widget will be automatically removed from its old parent.
|
102 | *
|
103 | * This is a no-op if there is no effective parent change.
|
104 | */
|
105 | set parent(value: Widget | null);
|
106 | /**
|
107 | * Get the layout for the widget.
|
108 | */
|
109 | get layout(): Layout | null;
|
110 | /**
|
111 | * Set the layout for the widget.
|
112 | *
|
113 | * #### Notes
|
114 | * The layout is single-use only. It cannot be changed after the
|
115 | * first assignment.
|
116 | *
|
117 | * The layout is disposed automatically when the widget is disposed.
|
118 | */
|
119 | set layout(value: Layout | null);
|
120 | /**
|
121 | * Create an iterator over the widget's children.
|
122 | *
|
123 | * @returns A new iterator over the children of the widget.
|
124 | *
|
125 | * #### Notes
|
126 | * The widget must have a populated layout in order to have children.
|
127 | *
|
128 | * If a layout is not installed, the returned iterator will be empty.
|
129 | */
|
130 | children(): IterableIterator<Widget>;
|
131 | /**
|
132 | * Test whether a widget is a descendant of this widget.
|
133 | *
|
134 | * @param widget - The descendant widget of interest.
|
135 | *
|
136 | * @returns `true` if the widget is a descendant, `false` otherwise.
|
137 | */
|
138 | contains(widget: Widget): boolean;
|
139 | /**
|
140 | * Test whether the widget's DOM node has the given class name.
|
141 | *
|
142 | * @param name - The class name of interest.
|
143 | *
|
144 | * @returns `true` if the node has the class, `false` otherwise.
|
145 | */
|
146 | hasClass(name: string): boolean;
|
147 | /**
|
148 | * Add a class name to the widget's DOM node.
|
149 | *
|
150 | * @param name - The class name to add to the node.
|
151 | *
|
152 | * #### Notes
|
153 | * If the class name is already added to the node, this is a no-op.
|
154 | *
|
155 | * The class name must not contain whitespace.
|
156 | */
|
157 | addClass(name: string): void;
|
158 | /**
|
159 | * Remove a class name from the widget's DOM node.
|
160 | *
|
161 | * @param name - The class name to remove from the node.
|
162 | *
|
163 | * #### Notes
|
164 | * If the class name is not yet added to the node, this is a no-op.
|
165 | *
|
166 | * The class name must not contain whitespace.
|
167 | */
|
168 | removeClass(name: string): void;
|
169 | /**
|
170 | * Toggle a class name on the widget's DOM node.
|
171 | *
|
172 | * @param name - The class name to toggle on the node.
|
173 | *
|
174 | * @param force - Whether to force add the class (`true`) or force
|
175 | * remove the class (`false`). If not provided, the presence of
|
176 | * the class will be toggled from its current state.
|
177 | *
|
178 | * @returns `true` if the class is now present, `false` otherwise.
|
179 | *
|
180 | * #### Notes
|
181 | * The class name must not contain whitespace.
|
182 | */
|
183 | toggleClass(name: string, force?: boolean): boolean;
|
184 | /**
|
185 | * Post an `'update-request'` message to the widget.
|
186 | *
|
187 | * #### Notes
|
188 | * This is a simple convenience method for posting the message.
|
189 | */
|
190 | update(): void;
|
191 | /**
|
192 | * Post a `'fit-request'` message to the widget.
|
193 | *
|
194 | * #### Notes
|
195 | * This is a simple convenience method for posting the message.
|
196 | */
|
197 | fit(): void;
|
198 | /**
|
199 | * Post an `'activate-request'` message to the widget.
|
200 | *
|
201 | * #### Notes
|
202 | * This is a simple convenience method for posting the message.
|
203 | */
|
204 | activate(): void;
|
205 | /**
|
206 | * Send a `'close-request'` message to the widget.
|
207 | *
|
208 | * #### Notes
|
209 | * This is a simple convenience method for sending the message.
|
210 | */
|
211 | close(): void;
|
212 | /**
|
213 | * Show the widget and make it visible to its parent widget.
|
214 | *
|
215 | * #### Notes
|
216 | * This causes the {`false`.
isHidden} property to be |
217 | *
|
218 | * If the widget is not explicitly hidden, this is a no-op.
|
219 | */
|
220 | show(): void;
|
221 | /**
|
222 | * Hide the widget and make it hidden to its parent widget.
|
223 | *
|
224 | * #### Notes
|
225 | * This causes the {@link isHidden} property to be `true`.
|
226 | *
|
227 | * If the widget is explicitly hidden, this is a no-op.
|
228 | */
|
229 | hide(): void;
|
230 | /**
|
231 | * Show or hide the widget according to a boolean value.
|
232 | *
|
233 | * @param hidden - `true` to hide the widget, or `false` to show it.
|
234 | *
|
235 | * #### Notes
|
236 | * This is a convenience method for `hide()` and `show()`.
|
237 | */
|
238 | setHidden(hidden: boolean): void;
|
239 | /**
|
240 | * Test whether the given widget flag is set.
|
241 | *
|
242 | * #### Notes
|
243 | * This will not typically be called directly by user code.
|
244 | */
|
245 | testFlag(flag: Widget.Flag): boolean;
|
246 | /**
|
247 | * Set the given widget flag.
|
248 | *
|
249 | * #### Notes
|
250 | * This will not typically be called directly by user code.
|
251 | */
|
252 | setFlag(flag: Widget.Flag): void;
|
253 | /**
|
254 | * Clear the given widget flag.
|
255 | *
|
256 | * #### Notes
|
257 | * This will not typically be called directly by user code.
|
258 | */
|
259 | clearFlag(flag: Widget.Flag): void;
|
260 | /**
|
261 | * Process a message sent to the widget.
|
262 | *
|
263 | * @param msg - The message sent to the widget.
|
264 | *
|
265 | * #### Notes
|
266 | * Subclasses may reimplement this method as needed.
|
267 | */
|
268 | processMessage(msg: Message): void;
|
269 | /**
|
270 | * Invoke the message processing routine of the widget's layout.
|
271 | *
|
272 | * @param msg - The message to dispatch to the layout.
|
273 | *
|
274 | * #### Notes
|
275 | * This is a no-op if the widget does not have a layout.
|
276 | *
|
277 | * This will not typically be called directly by user code.
|
278 | */
|
279 | protected notifyLayout(msg: Message): void;
|
280 | /**
|
281 | * A message handler invoked on a `'close-request'` message.
|
282 | *
|
283 | * #### Notes
|
284 | * The default implementation unparents or detaches the widget.
|
285 | */
|
286 | protected onCloseRequest(msg: Message): void;
|
287 | /**
|
288 | * A message handler invoked on a `'resize'` message.
|
289 | *
|
290 | * #### Notes
|
291 | * The default implementation of this handler is a no-op.
|
292 | */
|
293 | protected onResize(msg: Widget.ResizeMessage): void;
|
294 | /**
|
295 | * A message handler invoked on an `'update-request'` message.
|
296 | *
|
297 | * #### Notes
|
298 | * The default implementation of this handler is a no-op.
|
299 | */
|
300 | protected onUpdateRequest(msg: Message): void;
|
301 | /**
|
302 | * A message handler invoked on a `'fit-request'` message.
|
303 | *
|
304 | * #### Notes
|
305 | * The default implementation of this handler is a no-op.
|
306 | */
|
307 | protected onFitRequest(msg: Message): void;
|
308 | /**
|
309 | * A message handler invoked on an `'activate-request'` message.
|
310 | *
|
311 | * #### Notes
|
312 | * The default implementation of this handler is a no-op.
|
313 | */
|
314 | protected onActivateRequest(msg: Message): void;
|
315 | /**
|
316 | * A message handler invoked on a `'before-show'` message.
|
317 | *
|
318 | * #### Notes
|
319 | * The default implementation of this handler is a no-op.
|
320 | */
|
321 | protected onBeforeShow(msg: Message): void;
|
322 | /**
|
323 | * A message handler invoked on an `'after-show'` message.
|
324 | *
|
325 | * #### Notes
|
326 | * The default implementation of this handler is a no-op.
|
327 | */
|
328 | protected onAfterShow(msg: Message): void;
|
329 | /**
|
330 | * A message handler invoked on a `'before-hide'` message.
|
331 | *
|
332 | * #### Notes
|
333 | * The default implementation of this handler is a no-op.
|
334 | */
|
335 | protected onBeforeHide(msg: Message): void;
|
336 | /**
|
337 | * A message handler invoked on an `'after-hide'` message.
|
338 | *
|
339 | * #### Notes
|
340 | * The default implementation of this handler is a no-op.
|
341 | */
|
342 | protected onAfterHide(msg: Message): void;
|
343 | /**
|
344 | * A message handler invoked on a `'before-attach'` message.
|
345 | *
|
346 | * #### Notes
|
347 | * The default implementation of this handler is a no-op.
|
348 | */
|
349 | protected onBeforeAttach(msg: Message): void;
|
350 | /**
|
351 | * A message handler invoked on an `'after-attach'` message.
|
352 | *
|
353 | * #### Notes
|
354 | * The default implementation of this handler is a no-op.
|
355 | */
|
356 | protected onAfterAttach(msg: Message): void;
|
357 | /**
|
358 | * A message handler invoked on a `'before-detach'` message.
|
359 | *
|
360 | * #### Notes
|
361 | * The default implementation of this handler is a no-op.
|
362 | */
|
363 | protected onBeforeDetach(msg: Message): void;
|
364 | /**
|
365 | * A message handler invoked on an `'after-detach'` message.
|
366 | *
|
367 | * #### Notes
|
368 | * The default implementation of this handler is a no-op.
|
369 | */
|
370 | protected onAfterDetach(msg: Message): void;
|
371 | /**
|
372 | * A message handler invoked on a `'child-added'` message.
|
373 | *
|
374 | * #### Notes
|
375 | * The default implementation of this handler is a no-op.
|
376 | */
|
377 | protected onChildAdded(msg: Widget.ChildMessage): void;
|
378 | /**
|
379 | * A message handler invoked on a `'child-removed'` message.
|
380 | *
|
381 | * #### Notes
|
382 | * The default implementation of this handler is a no-op.
|
383 | */
|
384 | protected onChildRemoved(msg: Widget.ChildMessage): void;
|
385 | private _toggleHidden;
|
386 | private _flags;
|
387 | private _layout;
|
388 | private _parent;
|
389 | private _disposed;
|
390 | private _hiddenMode;
|
391 | }
|
392 | /**
|
393 | * The namespace for the `Widget` class statics.
|
394 | */
|
395 | export declare namespace Widget {
|
396 | /**
|
397 | * An options object for initializing a widget.
|
398 | */
|
399 | interface IOptions {
|
400 | /**
|
401 | * The optional node to use for the widget.
|
402 | *
|
403 | * If a node is provided, the widget will assume full ownership
|
404 | * and control of the node, as if it had created the node itself.
|
405 | *
|
406 | * The default is a new `<div>`.
|
407 | */
|
408 | node?: HTMLElement;
|
409 | /**
|
410 | * The optional element tag, used for constructing the widget's node.
|
411 | *
|
412 | * If a pre-constructed node is provided via the `node` arg, this
|
413 | * value is ignored.
|
414 | */
|
415 | tag?: keyof HTMLElementTagNameMap;
|
416 | }
|
417 | /**
|
418 | * The method for hiding the widget.
|
419 | *
|
420 | * The default is Display.
|
421 | *
|
422 | * Using `Scale` will often increase performance as most browsers will not
|
423 | * trigger style computation for the `transform` action. This should be used
|
424 | * sparingly and tested, since increasing the number of composition layers
|
425 | * may slow things down.
|
426 | *
|
427 | * To ensure the transformation does not trigger style recomputation, you
|
428 | * may need to set the widget CSS style `will-change: transform`. This
|
429 | * should be used only when needed as it may overwhelm the browser with a
|
430 | * high number of layers. See
|
431 | * https://developer.mozilla.org/en-US/docs/Web/CSS/will-change
|
432 | */
|
433 | enum HiddenMode {
|
434 | /**
|
435 | * Set a `lm-mod-hidden` CSS class to hide the widget using `display:none`
|
436 | * CSS from the standard Lumino CSS.
|
437 | */
|
438 | Display = 0,
|
439 | /**
|
440 | * Hide the widget by setting the `transform` to `'scale(0)'`.
|
441 | */
|
442 | Scale = 1,
|
443 | /**
|
444 | *Hide the widget by setting the `content-visibility` to `'hidden'`.
|
445 | */
|
446 | ContentVisibility = 2
|
447 | }
|
448 | /**
|
449 | * An enum of widget bit flags.
|
450 | */
|
451 | enum Flag {
|
452 | /**
|
453 | * The widget has been disposed.
|
454 | */
|
455 | IsDisposed = 1,
|
456 | /**
|
457 | * The widget is attached to the DOM.
|
458 | */
|
459 | IsAttached = 2,
|
460 | /**
|
461 | * The widget is hidden.
|
462 | */
|
463 | IsHidden = 4,
|
464 | /**
|
465 | * The widget is visible.
|
466 | */
|
467 | IsVisible = 8,
|
468 | /**
|
469 | * A layout cannot be set on the widget.
|
470 | */
|
471 | DisallowLayout = 16
|
472 | }
|
473 | /**
|
474 | * A collection of stateless messages related to widgets.
|
475 | */
|
476 | namespace Msg {
|
477 | /**
|
478 | * A singleton `'before-show'` message.
|
479 | *
|
480 | * #### Notes
|
481 | * This message is sent to a widget before it becomes visible.
|
482 | *
|
483 | * This message is **not** sent when the widget is being attached.
|
484 | */
|
485 | const BeforeShow: Message;
|
486 | /**
|
487 | * A singleton `'after-show'` message.
|
488 | *
|
489 | * #### Notes
|
490 | * This message is sent to a widget after it becomes visible.
|
491 | *
|
492 | * This message is **not** sent when the widget is being attached.
|
493 | */
|
494 | const AfterShow: Message;
|
495 | /**
|
496 | * A singleton `'before-hide'` message.
|
497 | *
|
498 | * #### Notes
|
499 | * This message is sent to a widget before it becomes not-visible.
|
500 | *
|
501 | * This message is **not** sent when the widget is being detached.
|
502 | */
|
503 | const BeforeHide: Message;
|
504 | /**
|
505 | * A singleton `'after-hide'` message.
|
506 | *
|
507 | * #### Notes
|
508 | * This message is sent to a widget after it becomes not-visible.
|
509 | *
|
510 | * This message is **not** sent when the widget is being detached.
|
511 | */
|
512 | const AfterHide: Message;
|
513 | /**
|
514 | * A singleton `'before-attach'` message.
|
515 | *
|
516 | * #### Notes
|
517 | * This message is sent to a widget before it is attached.
|
518 | */
|
519 | const BeforeAttach: Message;
|
520 | /**
|
521 | * A singleton `'after-attach'` message.
|
522 | *
|
523 | * #### Notes
|
524 | * This message is sent to a widget after it is attached.
|
525 | */
|
526 | const AfterAttach: Message;
|
527 | /**
|
528 | * A singleton `'before-detach'` message.
|
529 | *
|
530 | * #### Notes
|
531 | * This message is sent to a widget before it is detached.
|
532 | */
|
533 | const BeforeDetach: Message;
|
534 | /**
|
535 | * A singleton `'after-detach'` message.
|
536 | *
|
537 | * #### Notes
|
538 | * This message is sent to a widget after it is detached.
|
539 | */
|
540 | const AfterDetach: Message;
|
541 | /**
|
542 | * A singleton `'parent-changed'` message.
|
543 | *
|
544 | * #### Notes
|
545 | * This message is sent to a widget when its parent has changed.
|
546 | */
|
547 | const ParentChanged: Message;
|
548 | /**
|
549 | * A singleton conflatable `'update-request'` message.
|
550 | *
|
551 | * #### Notes
|
552 | * This message can be dispatched to supporting widgets in order to
|
553 | * update their content based on the current widget state. Not all
|
554 | * widgets will respond to messages of this type.
|
555 | *
|
556 | * For widgets with a layout, this message will inform the layout to
|
557 | * update the position and size of its child widgets.
|
558 | */
|
559 | const UpdateRequest: ConflatableMessage;
|
560 | /**
|
561 | * A singleton conflatable `'fit-request'` message.
|
562 | *
|
563 | * #### Notes
|
564 | * For widgets with a layout, this message will inform the layout to
|
565 | * recalculate its size constraints to fit the space requirements of
|
566 | * its child widgets, and to update their position and size. Not all
|
567 | * layouts will respond to messages of this type.
|
568 | */
|
569 | const FitRequest: ConflatableMessage;
|
570 | /**
|
571 | * A singleton conflatable `'activate-request'` message.
|
572 | *
|
573 | * #### Notes
|
574 | * This message should be dispatched to a widget when it should
|
575 | * perform the actions necessary to activate the widget, which
|
576 | * may include focusing its node or descendant node.
|
577 | */
|
578 | const ActivateRequest: ConflatableMessage;
|
579 | /**
|
580 | * A singleton conflatable `'close-request'` message.
|
581 | *
|
582 | * #### Notes
|
583 | * This message should be dispatched to a widget when it should close
|
584 | * and remove itself from the widget hierarchy.
|
585 | */
|
586 | const CloseRequest: ConflatableMessage;
|
587 | }
|
588 | /**
|
589 | * A message class for child related messages.
|
590 | */
|
591 | class ChildMessage extends Message {
|
592 | /**
|
593 | * Construct a new child message.
|
594 | *
|
595 | * @param type - The message type.
|
596 | *
|
597 | * @param child - The child widget for the message.
|
598 | */
|
599 | constructor(type: string, child: Widget);
|
600 | /**
|
601 | * The child widget for the message.
|
602 | */
|
603 | readonly child: Widget;
|
604 | }
|
605 | /**
|
606 | * A message class for `'resize'` messages.
|
607 | */
|
608 | class ResizeMessage extends Message {
|
609 | /**
|
610 | * Construct a new resize message.
|
611 | *
|
612 | * @param width - The **offset width** of the widget, or `-1` if
|
613 | * the width is not known.
|
614 | *
|
615 | * @param height - The **offset height** of the widget, or `-1` if
|
616 | * the height is not known.
|
617 | */
|
618 | constructor(width: number, height: number);
|
619 | /**
|
620 | * The offset width of the widget.
|
621 | *
|
622 | * #### Notes
|
623 | * This will be `-1` if the width is unknown.
|
624 | */
|
625 | readonly width: number;
|
626 | /**
|
627 | * The offset height of the widget.
|
628 | *
|
629 | * #### Notes
|
630 | * This will be `-1` if the height is unknown.
|
631 | */
|
632 | readonly height: number;
|
633 | }
|
634 | /**
|
635 | * The namespace for the `ResizeMessage` class statics.
|
636 | */
|
637 | namespace ResizeMessage {
|
638 | /**
|
639 | * A singleton `'resize'` message with an unknown size.
|
640 | */
|
641 | const UnknownSize: ResizeMessage;
|
642 | }
|
643 | /**
|
644 | * Attach a widget to a host DOM node.
|
645 | *
|
646 | * @param widget - The widget of interest.
|
647 | *
|
648 | * @param host - The DOM node to use as the widget's host.
|
649 | *
|
650 | * @param ref - The child of `host` to use as the reference element.
|
651 | * If this is provided, the widget will be inserted before this
|
652 | * node in the host. The default is `null`, which will cause the
|
653 | * widget to be added as the last child of the host.
|
654 | *
|
655 | * #### Notes
|
656 | * This will throw an error if the widget is not a root widget, if
|
657 | * the widget is already attached, or if the host is not attached
|
658 | * to the DOM.
|
659 | */
|
660 | function attach(widget: Widget, host: HTMLElement, ref?: HTMLElement | null): void;
|
661 | /**
|
662 | * Detach the widget from its host DOM node.
|
663 | *
|
664 | * @param widget - The widget of interest.
|
665 | *
|
666 | * #### Notes
|
667 | * This will throw an error if the widget is not a root widget,
|
668 | * or if the widget is not attached to the DOM.
|
669 | */
|
670 | function detach(widget: Widget): void;
|
671 | }
|