@lumino/widgets
Version:
Lumino Widgets
541 lines (540 loc) • 15.7 kB
TypeScript
import { Message } from '@lumino/messaging';
import { ISignal } from '@lumino/signaling';
import { DockLayout } from './docklayout';
import { TabBar } from './tabbar';
import { Widget } from './widget';
/**
* A widget which provides a flexible docking area for widgets.
*
* #### Notes
* See also the related [example](../../examples/dockpanel/index.html) and
* its [source](https://github.com/jupyterlab/lumino/tree/main/examples/example-dockpanel).
*/
export declare class DockPanel extends Widget {
/**
* Construct a new dock panel.
*
* @param options - The options for initializing the panel.
*/
constructor(options?: DockPanel.IOptions);
/**
* Dispose of the resources held by the panel.
*/
dispose(): void;
/**
* The method for hiding widgets.
*/
get hiddenMode(): Widget.HiddenMode;
/**
* Set the method for hiding widgets.
*/
set hiddenMode(v: Widget.HiddenMode);
/**
* A signal emitted when the layout configuration is modified.
*
* #### Notes
* This signal is emitted whenever the current layout configuration
* may have changed.
*
* This signal is emitted asynchronously in a collapsed fashion, so
* that multiple synchronous modifications results in only a single
* emit of the signal.
*/
get layoutModified(): ISignal<this, void>;
/**
* A signal emitted when the add button on a tab bar is clicked.
*
*/
get addRequested(): ISignal<this, TabBar<Widget>>;
/**
* The overlay used by the dock panel.
*/
readonly overlay: DockPanel.IOverlay;
/**
* The renderer used by the dock panel.
*/
get renderer(): DockPanel.IRenderer;
/**
* Get the spacing between the widgets.
*/
get spacing(): number;
/**
* Set the spacing between the widgets.
*/
set spacing(value: number);
/**
* Get the mode for the dock panel.
*/
get mode(): DockPanel.Mode;
/**
* Set the mode for the dock panel.
*
* #### Notes
* Changing the mode is a destructive operation with respect to the
* panel's layout configuration. If layout state must be preserved,
* save the current layout config before changing the mode.
*/
set mode(value: DockPanel.Mode);
/**
* Whether the tabs can be dragged / moved at runtime.
*/
get tabsMovable(): boolean;
/**
* Enable / Disable draggable / movable tabs.
*/
set tabsMovable(value: boolean);
/**
* Whether the tabs are constrained to their source dock panel
*/
get tabsConstrained(): boolean;
/**
* Constrain/Allow tabs to be dragged outside of this dock panel
*/
set tabsConstrained(value: boolean);
/**
* Whether the add buttons for each tab bar are enabled.
*/
get addButtonEnabled(): boolean;
/**
* Set whether the add buttons for each tab bar are enabled.
*/
set addButtonEnabled(value: boolean);
/**
* Whether the dock panel is empty.
*/
get isEmpty(): boolean;
/**
* Create an iterator over the user widgets in the panel.
*
* @returns A new iterator over the user widgets in the panel.
*
* #### Notes
* This iterator does not include the generated tab bars.
*/
widgets(): IterableIterator<Widget>;
/**
* Create an iterator over the selected widgets in the panel.
*
* @returns A new iterator over the selected user widgets.
*
* #### Notes
* This iterator yields the widgets corresponding to the current tab
* of each tab bar in the panel.
*/
selectedWidgets(): IterableIterator<Widget>;
/**
* Create an iterator over the tab bars in the panel.
*
* @returns A new iterator over the tab bars in the panel.
*
* #### Notes
* This iterator does not include the user widgets.
*/
tabBars(): IterableIterator<TabBar<Widget>>;
/**
* Create an iterator over the handles in the panel.
*
* @returns A new iterator over the handles in the panel.
*/
handles(): IterableIterator<HTMLDivElement>;
/**
* Select a specific widget in the dock panel.
*
* @param widget - The widget of interest.
*
* #### Notes
* This will make the widget the current widget in its tab area.
*/
selectWidget(widget: Widget): void;
/**
* Activate a specified widget in the dock panel.
*
* @param widget - The widget of interest.
*
* #### Notes
* This will select and activate the given widget.
*/
activateWidget(widget: Widget): void;
/**
* Save the current layout configuration of the dock panel.
*
* @returns A new config object for the current layout state.
*
* #### Notes
* The return value can be provided to the `restoreLayout` method
* in order to restore the layout to its current configuration.
*/
saveLayout(): DockPanel.ILayoutConfig;
/**
* Restore the layout to a previously saved configuration.
*
* @param config - The layout configuration to restore.
*
* #### Notes
* Widgets which currently belong to the layout but which are not
* contained in the config will be unparented.
*
* The dock panel automatically reverts to `'multiple-document'`
* mode when a layout config is restored.
*/
restoreLayout(config: DockPanel.ILayoutConfig): void;
/**
* Add a widget to the dock panel.
*
* @param widget - The widget to add to the dock panel.
*
* @param options - The additional options for adding the widget.
*
* #### Notes
* If the panel is in single document mode, the options are ignored
* and the widget is always added as tab in the hidden tab bar.
*/
addWidget(widget: Widget, options?: DockPanel.IAddOptions): void;
/**
* Process a message sent to the widget.
*
* @param msg - The message sent to the widget.
*/
processMessage(msg: Message): void;
/**
* Handle the DOM events for the dock panel.
*
* @param event - The DOM event sent to the panel.
*
* #### Notes
* This method implements the DOM `EventListener` interface and is
* called in response to events on the panel's DOM node. It should
* not be called directly by user code.
*/
handleEvent(event: Event): void;
/**
* A message handler invoked on a `'before-attach'` message.
*/
protected onBeforeAttach(msg: Message): void;
/**
* A message handler invoked on an `'after-detach'` message.
*/
protected onAfterDetach(msg: Message): void;
/**
* A message handler invoked on a `'child-added'` message.
*/
protected onChildAdded(msg: Widget.ChildMessage): void;
/**
* A message handler invoked on a `'child-removed'` message.
*/
protected onChildRemoved(msg: Widget.ChildMessage): void;
/**
* Handle the `'lm-dragenter'` event for the dock panel.
*/
private _evtDragEnter;
/**
* Handle the `'lm-dragleave'` event for the dock panel.
*/
private _evtDragLeave;
/**
* Handle the `'lm-dragover'` event for the dock panel.
*/
private _evtDragOver;
/**
* Handle the `'lm-drop'` event for the dock panel.
*/
private _evtDrop;
/**
* Handle the `'keydown'` event for the dock panel.
*/
private _evtKeyDown;
/**
* Handle the `'pointerdown'` event for the dock panel.
*/
private _evtPointerDown;
/**
* Handle the `'pointermove'` event for the dock panel.
*/
private _evtPointerMove;
/**
* Handle the `'pointerup'` event for the dock panel.
*/
private _evtPointerUp;
/**
* Release the mouse grab for the dock panel.
*/
private _releaseMouse;
/**
* Show the overlay indicator at the given client position.
*
* Returns the drop zone at the specified client position.
*
* #### Notes
* If the position is not over a valid zone, the overlay is hidden.
*/
private _showOverlay;
/**
* Create a new tab bar for use by the panel.
*/
private _createTabBar;
/**
* Create a new handle for use by the panel.
*/
private _createHandle;
/**
* Handle the `tabMoved` signal from a tab bar.
*/
private _onTabMoved;
/**
* Handle the `currentChanged` signal from a tab bar.
*/
private _onCurrentChanged;
/**
* Handle the `addRequested` signal from a tab bar.
*/
private _onTabAddRequested;
/**
* Handle the `tabActivateRequested` signal from a tab bar.
*/
private _onTabActivateRequested;
/**
* Handle the `tabCloseRequested` signal from a tab bar.
*/
private _onTabCloseRequested;
/**
* Handle the `tabDetachRequested` signal from a tab bar.
*/
private _onTabDetachRequested;
private _edges;
private _document;
private _mode;
private _drag;
private _renderer;
private _tabsMovable;
private _tabsConstrained;
private _addButtonEnabled;
private _pressData;
private _layoutModified;
private _addRequested;
}
/**
* The namespace for the `DockPanel` class statics.
*/
export declare namespace DockPanel {
/**
* An options object for creating a dock panel.
*/
interface IOptions {
/**
* The document to use with the dock panel.
*
* The default is the global `document` instance.
*/
document?: Document | ShadowRoot;
/**
* The overlay to use with the dock panel.
*
* The default is a new `Overlay` instance.
*/
overlay?: IOverlay;
/**
* The renderer to use for the dock panel.
*
* The default is a shared renderer instance.
*/
renderer?: IRenderer;
/**
* The spacing between the items in the panel.
*
* The default is `4`.
*/
spacing?: number;
/**
* The mode for the dock panel.
*
* The default is `'multiple-document'`.
*/
mode?: DockPanel.Mode;
/**
* The sizes of the edge drop zones, in pixels.
* If not given, default values will be used.
*/
edges?: IEdges;
/**
* The method for hiding widgets.
*
* The default is `Widget.HiddenMode.Display`.
*/
hiddenMode?: Widget.HiddenMode;
/**
* Allow tabs to be draggable / movable by user.
*
* The default is `'true'`.
*/
tabsMovable?: boolean;
/**
* Constrain tabs to this dock panel
*
* The default is `'false'`.
*/
tabsConstrained?: boolean;
/**
* Enable add buttons in each of the dock panel's tab bars.
*
* The default is `'false'`.
*/
addButtonEnabled?: boolean;
}
/**
* The sizes of the edge drop zones, in pixels.
*/
interface IEdges {
/**
* The size of the top edge drop zone.
*/
top: number;
/**
* The size of the right edge drop zone.
*/
right: number;
/**
* The size of the bottom edge drop zone.
*/
bottom: number;
/**
* The size of the left edge drop zone.
*/
left: number;
}
/**
* A type alias for the supported dock panel modes.
*/
type Mode = /**
* The single document mode.
*
* In this mode, only a single widget is visible at a time, and that
* widget fills the available layout space. No tab bars are visible.
*/ 'single-document'
/**
* The multiple document mode.
*
* In this mode, multiple documents are displayed in separate tab
* areas, and those areas can be individually resized by the user.
*/
| 'multiple-document';
/**
* A type alias for a layout configuration object.
*/
type ILayoutConfig = DockLayout.ILayoutConfig;
/**
* A type alias for the supported insertion modes.
*/
type InsertMode = DockLayout.InsertMode;
/**
* A type alias for the add widget options.
*/
type IAddOptions = DockLayout.IAddOptions;
/**
* An object which holds the geometry for overlay positioning.
*/
interface IOverlayGeometry {
/**
* The distance between the overlay and parent top edges.
*/
top: number;
/**
* The distance between the overlay and parent left edges.
*/
left: number;
/**
* The distance between the overlay and parent right edges.
*/
right: number;
/**
* The distance between the overlay and parent bottom edges.
*/
bottom: number;
}
/**
* An object which manages the overlay node for a dock panel.
*/
interface IOverlay {
/**
* The DOM node for the overlay.
*/
readonly node: HTMLDivElement;
/**
* Show the overlay using the given overlay geometry.
*
* @param geo - The desired geometry for the overlay.
*
* #### Notes
* The given geometry values assume the node will use absolute
* positioning.
*
* This is called on every mouse move event during a drag in order
* to update the position of the overlay. It should be efficient.
*/
show(geo: IOverlayGeometry): void;
/**
* Hide the overlay node.
*
* @param delay - The delay (in ms) before hiding the overlay.
* A delay value <= 0 should hide the overlay immediately.
*
* #### Notes
* This is called whenever the overlay node should been hidden.
*/
hide(delay: number): void;
}
/**
* A concrete implementation of `IOverlay`.
*
* This is the default overlay implementation for a dock panel.
*/
class Overlay implements IOverlay {
/**
* Construct a new overlay.
*/
constructor();
/**
* The DOM node for the overlay.
*/
readonly node: HTMLDivElement;
/**
* Show the overlay using the given overlay geometry.
*
* @param geo - The desired geometry for the overlay.
*/
show(geo: IOverlayGeometry): void;
/**
* Hide the overlay node.
*
* @param delay - The delay (in ms) before hiding the overlay.
* A delay value <= 0 will hide the overlay immediately.
*/
hide(delay: number): void;
private _timer;
private _hidden;
}
/**
* A type alias for a dock panel renderer;
*/
type IRenderer = DockLayout.IRenderer;
/**
* The default implementation of `IRenderer`.
*/
class Renderer implements IRenderer {
/**
* Create a new tab bar for use with a dock panel.
*
* @returns A new tab bar for a dock panel.
*/
createTabBar(document?: Document | ShadowRoot): TabBar<Widget>;
/**
* Create a new handle node for use with a dock panel.
*
* @returns A new handle node for a dock panel.
*/
createHandle(): HTMLDivElement;
}
/**
* The default `Renderer` instance.
*/
const defaultRenderer: Renderer;
}