@phosphor/widgets

  • Version 1.9.3
  • Published
  • 750 kB
  • 11 dependencies
  • BSD-3-Clause license

Install

npm i @phosphor/widgets
yarn add @phosphor/widgets
pnpm add @phosphor/widgets

Overview

PhosphorJS - Widgets

Index

Classes

Namespaces

Classes

class BoxLayout

class BoxLayout extends PanelLayout {}
  • A layout which arranges its widgets in a single row or column.

constructor

constructor(options?: BoxLayout.IOptions);
  • Construct a new box layout.

    Parameter options

    The options for initializing the layout.

property alignment

alignment: BoxLayout.Alignment;
  • Set the content alignment for the box layout.

    #### Notes This is the alignment of the widgets in the layout direction.

    The alignment has no effect if the widgets can expand to fill the entire box layout.

property direction

direction: BoxLayout.Direction;
  • Set the layout direction for the box layout.

property spacing

spacing: number;
  • Set the inter-element spacing for the box layout.

method attachWidget

protected attachWidget: (index: number, widget: Widget) => void;
  • Attach a widget to the parent's DOM node.

    Parameter index

    The current index of the widget in the layout.

    Parameter widget

    The widget to attach to the parent.

    #### Notes This is a reimplementation of the superclass method.

method detachWidget

protected detachWidget: (index: number, widget: Widget) => void;
  • Detach a widget from the parent's DOM node.

    Parameter index

    The previous index of the widget in the layout.

    Parameter widget

    The widget to detach from the parent.

    #### Notes This is a reimplementation of the superclass method.

method dispose

dispose: () => void;
  • Dispose of the resources held by the layout.

method init

protected init: () => void;
  • Perform layout initialization which requires the parent widget.

method moveWidget

protected moveWidget: (
fromIndex: number,
toIndex: number,
widget: Widget
) => void;
  • Move a widget in the parent's DOM node.

    Parameter fromIndex

    The previous index of the widget in the layout.

    Parameter toIndex

    The current index of the widget in the layout.

    Parameter widget

    The widget to move in the parent.

    #### Notes This is a reimplementation of the superclass method.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

method onBeforeShow

protected onBeforeShow: (msg: any) => void;
  • A message handler invoked on a 'before-show' message.

method onChildHidden

protected onChildHidden: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-hidden' message.

method onChildShown

protected onChildShown: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-shown' message.

method onFitRequest

protected onFitRequest: (msg: any) => void;
  • A message handler invoked on a 'fit-request' message.

method onResize

protected onResize: (msg: Widget.ResizeMessage) => void;
  • A message handler invoked on a 'resize' message.

method onUpdateRequest

protected onUpdateRequest: (msg: any) => void;
  • A message handler invoked on an 'update-request' message.

class BoxPanel

class BoxPanel extends Panel {}
  • A panel which arranges its widgets in a single row or column.

    #### Notes This class provides a convenience wrapper around a [[BoxLayout]].

constructor

constructor(options?: BoxPanel.IOptions);
  • Construct a new box panel.

    Parameter options

    The options for initializing the box panel.

property alignment

alignment: BoxLayout.Alignment;
  • Set the content alignment for the box panel.

    #### Notes This is the alignment of the widgets in the layout direction.

    The alignment has no effect if the widgets can expand to fill the entire box layout.

property direction

direction: BoxLayout.Direction;
  • Set the layout direction for the box panel.

property spacing

spacing: number;
  • Set the inter-element spacing for the box panel.

method onChildAdded

protected onChildAdded: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-added' message.

method onChildRemoved

protected onChildRemoved: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-removed' message.

class BoxSizer

class BoxSizer {}
  • A sizer object for use with the box engine layout functions.

    #### Notes A box sizer holds the geometry information for an object along an arbitrary layout orientation.

    For best performance, this class should be treated as a raw data struct. It should not typically be subclassed.

property done

done: boolean;
  • An internal storage property for the layout algorithm.

    #### Notes This value is used as temporary storage by the layout algorithm.

    Changing this value will have no effect.

property maxSize

maxSize: number;
  • The maximum size of the sizer.

    #### Notes The sizer will never be sized greater than this value, even if it means the sizer will underflow the available layout space.

    It is assumed that this value lies in the range [0, Infinity] and that it is >= to [[minSize]]. Failure to adhere to this constraint will yield undefined results.

    The default value is Infinity.

property minSize

minSize: number;
  • The minimum size of the sizer.

    #### Notes The sizer will never be sized less than this value, even if it means the sizer will overflow the available layout space.

    It is assumed that this value lies in the range [0, Infinity) and that it is <= to [[maxSize]]. Failure to adhere to this constraint will yield undefined results.

    The default value is 0.

property size

size: number;
  • The computed size of the sizer.

    #### Notes This value is the output of a call to [[boxCalc]]. It represents the computed size for the object along the layout orientation, and will always lie in the range [minSize, maxSize].

    This value is output only.

    Changing this value will have no effect.

property sizeHint

sizeHint: number;
  • The preferred size for the sizer.

    #### Notes The sizer will be given this initial size subject to its size bounds. The sizer will not deviate from this size unless such deviation is required to fit into the available layout space.

    There is no limit to this value, but it will be clamped to the bounds defined by [[minSize]] and [[maxSize]].

    The default value is 0.

property stretch

stretch: number;
  • The stretch factor for the sizer.

    #### Notes This controls how much the sizer stretches relative to its sibling sizers when layout space is distributed. A stretch factor of zero is special and will cause the sizer to only be resized after all other sizers with a stretch factor greater than zero have been resized to their limits.

    It is assumed that this value is an integer that lies in the range [0, Infinity). Failure to adhere to this constraint will yield undefined results.

    The default value is 1.

class CommandPalette

class CommandPalette extends Widget {}
  • A widget which displays command items as a searchable palette.

constructor

constructor(options: CommandPalette.IOptions);
  • Construct a new command palette.

    Parameter options

    The options for initializing the palette.

property commands

readonly commands: any;
  • The command registry used by the command palette.

property contentNode

readonly contentNode: HTMLUListElement;
  • The command palette content node.

    #### Notes This is the node which holds the command item nodes.

    Modifying this node directly can lead to undefined behavior.

property inputNode

readonly inputNode: HTMLInputElement;
  • The command palette input node.

    #### Notes This is the actual input node for the search area.

property items

readonly items: readonly CommandPalette.IItem[];
  • A read-only array of the command items in the palette.

property renderer

readonly renderer: CommandPalette.IRenderer;
  • The renderer used by the command palette.

property searchNode

readonly searchNode: HTMLDivElement;
  • The command palette search node.

    #### Notes This is the node which contains the search-related elements.

method addItem

addItem: (options: CommandPalette.IItemOptions) => CommandPalette.IItem;
  • Add a command item to the command palette.

    Parameter options

    The options for creating the command item.

    Returns

    The command item added to the palette.

method clearItems

clearItems: () => void;
  • Remove all items from the command palette.

method dispose

dispose: () => void;
  • Dispose of the resources held by the widget.

method handleEvent

handleEvent: (event: Event) => void;
  • Handle the DOM events for the command palette.

    Parameter event

    The DOM event sent to the command palette.

    #### Notes This method implements the DOM EventListener interface and is called in response to events on the command palette's DOM node. It should not be called directly by user code.

method onActivateRequest

protected onActivateRequest: (msg: any) => void;
  • A message handler invoked on an 'activate-request' message.

method onAfterDetach

protected onAfterDetach: (msg: any) => void;
  • A message handler invoked on an 'after-detach' message.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

method onUpdateRequest

protected onUpdateRequest: (msg: any) => void;
  • A message handler invoked on an 'update-request' message.

method refresh

refresh: () => void;
  • Clear the search results and schedule an update.

    #### Notes This should be called whenever the search results of the palette should be updated.

    This is typically called automatically by the palette as needed, but can be called manually if the input text is programatically changed.

    The rendered results are updated asynchronously.

method removeItem

removeItem: (item: CommandPalette.IItem) => void;
  • Remove an item from the command palette.

    Parameter item

    The item to remove from the palette.

    #### Notes This is a no-op if the item is not in the palette.

method removeItemAt

removeItemAt: (index: number) => void;
  • Remove the item at a given index from the command palette.

    Parameter index

    The index of the item to remove.

    #### Notes This is a no-op if the index is out of range.

class ContextMenu

class ContextMenu {}
  • An object which implements a universal context menu.

    #### Notes The items shown in the context menu are determined by CSS selector matching against the DOM hierarchy at the site of the mouse click. This is similar in concept to how keyboard shortcuts are matched in the command registry.

constructor

constructor(options: ContextMenu.IOptions);
  • Construct a new context menu.

    Parameter options

    The options for initializing the menu.

property menu

readonly menu: Menu;
  • The menu widget which displays the matched context items.

method addItem

addItem: (options: ContextMenu.IItemOptions) => any;
  • Add an item to the context menu.

    Parameter options

    The options for creating the item.

    Returns

    A disposable which will remove the item from the menu.

method open

open: (event: MouseEvent) => boolean;
  • Open the context menu in response to a 'contextmenu' event.

    Parameter event

    The 'contextmenu' event of interest.

    Returns

    true if the menu was opened, or false if no items matched the event and the menu was not opened.

    #### Notes This method will populate the context menu with items which match the propagation path of the event, then open the menu at the mouse position indicated by the event.

class DockLayout

class DockLayout extends Layout {}
  • A layout which provides a flexible docking arrangement.

    #### Notes The consumer of this layout is responsible for handling all signals from the generated tab bars and managing the visibility of widgets and tab bars as needed.

constructor

constructor(options: DockLayout.IOptions);
  • Construct a new dock layout.

    Parameter options

    The options for initializing the layout.

property isEmpty

readonly isEmpty: boolean;
  • Whether the dock layout is empty.

property renderer

readonly renderer: DockLayout.IRenderer;
  • The renderer used by the dock layout.

property spacing

spacing: number;
  • Set the inter-element spacing for the dock layout.

method addWidget

addWidget: (widget: Widget, options?: DockLayout.IAddOptions) => void;
  • Add a widget to the dock layout.

    Parameter widget

    The widget to add to the dock layout.

    Parameter options

    The additional options for adding the widget.

    #### Notes The widget will be moved if it is already contained in the layout.

    An error will be thrown if the reference widget is invalid.

method attachWidget

protected attachWidget: (widget: Widget) => void;
  • Attach the widget to the layout parent widget.

    Parameter widget

    The widget to attach to the parent.

    #### Notes This is a no-op if the widget is already attached.

method detachWidget

protected detachWidget: (widget: Widget) => void;
  • Detach the widget from the layout parent widget.

    Parameter widget

    The widget to detach from the parent.

    #### Notes This is a no-op if the widget is not attached.

method dispose

dispose: () => void;
  • Dispose of the resources held by the layout.

    #### Notes This will clear and dispose all widgets in the layout.

method handles

handles: () => any;
  • Create an iterator over the handles in the layout.

    Returns

    A new iterator over the handles in the layout.

method hitTestTabAreas

hitTestTabAreas: (
clientX: number,
clientY: number
) => DockLayout.ITabAreaGeometry | null;
  • Find the tab area which contains the given client position.

    Parameter clientX

    The client X position of interest.

    Parameter clientY

    The client Y position of interest.

    Returns

    The geometry of the tab area at the given position, or null if there is no tab area at the given position.

method init

protected init: () => void;
  • Perform layout initialization which requires the parent widget.

method iter

iter: () => any;
  • Create an iterator over all widgets in the layout.

    Returns

    A new iterator over the widgets in the layout.

    #### Notes This iterator includes the generated tab bars.

method moveHandle

moveHandle: (handle: HTMLDivElement, offsetX: number, offsetY: number) => void;
  • Move a handle to the given offset position.

    Parameter handle

    The handle to move.

    Parameter offsetX

    The desired offset X position of the handle.

    Parameter offsetY

    The desired offset Y position of the handle.

    #### Notes If the given handle is not contained in the layout, this is no-op.

    The handle will be moved as close as possible to the desired position without violating any of the layout constraints.

    Only one of the coordinates is used depending on the orientation of the handle. This method accepts both coordinates to make it easy to invoke from a mouse move event without needing to know the handle orientation.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

method onBeforeShow

protected onBeforeShow: (msg: any) => void;
  • A message handler invoked on a 'before-show' message.

method onChildHidden

protected onChildHidden: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-hidden' message.

method onChildShown

protected onChildShown: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-shown' message.

method onFitRequest

protected onFitRequest: (msg: any) => void;
  • A message handler invoked on a 'fit-request' message.

method onResize

protected onResize: (msg: Widget.ResizeMessage) => void;
  • A message handler invoked on a 'resize' message.

method onUpdateRequest

protected onUpdateRequest: (msg: any) => void;
  • A message handler invoked on an 'update-request' message.

method removeWidget

removeWidget: (widget: Widget) => void;
  • Remove a widget from the layout.

    Parameter widget

    The widget to remove from the layout.

    #### Notes A widget is automatically removed from the layout when its parent is set to null. This method should only be invoked directly when removing a widget from a layout which has yet to be installed on a parent widget.

    This method does *not* modify the widget's parent.

method restoreLayout

restoreLayout: (config: DockLayout.ILayoutConfig) => void;
  • Restore the layout to a previously saved configuration.

    Parameter 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.

method saveLayout

saveLayout: () => DockLayout.ILayoutConfig;
  • Save the current configuration of the dock layout.

    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.

method selectedWidgets

selectedWidgets: () => any;
  • Create an iterator over the selected widgets in the layout.

    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 layout.

method tabBars

tabBars: () => any;
  • Create an iterator over the tab bars in the layout.

    Returns

    A new iterator over the tab bars in the layout.

    #### Notes This iterator does not include the user widgets.

method widgets

widgets: () => any;
  • Create an iterator over the user widgets in the layout.

    Returns

    A new iterator over the user widgets in the layout.

    #### Notes This iterator does not include the generated tab bars.

class DockPanel

class DockPanel extends Widget {}
  • A widget which provides a flexible docking area for widgets.

constructor

constructor(options?: DockPanel.IOptions);
  • Construct a new dock panel.

    Parameter options

    The options for initializing the panel.

property isEmpty

readonly isEmpty: boolean;
  • Whether the dock panel is empty.

property layoutModified

readonly layoutModified: any;
  • 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.

property mode

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.

property overlay

readonly overlay: DockPanel.IOverlay;
  • The overlay used by the dock panel.

property renderer

readonly renderer: DockLayout.IRenderer;
  • The renderer used by the dock panel.

property spacing

spacing: number;
  • Set the spacing between the widgets.

method activateWidget

activateWidget: (widget: Widget) => void;
  • Activate a specified widget in the dock panel.

    Parameter widget

    The widget of interest.

    #### Notes This will select and activate the given widget.

method addWidget

addWidget: (widget: Widget, options?: DockPanel.IAddOptions) => void;
  • Add a widget to the dock panel.

    Parameter widget

    The widget to add to the dock panel.

    Parameter 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.

method dispose

dispose: () => void;
  • Dispose of the resources held by the panel.

method handleEvent

handleEvent: (event: Event) => void;
  • Handle the DOM events for the dock panel.

    Parameter 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.

method handles

handles: () => any;
  • Create an iterator over the handles in the panel.

    Returns

    A new iterator over the handles in the panel.

method onAfterDetach

protected onAfterDetach: (msg: any) => void;
  • A message handler invoked on an 'after-detach' message.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

method onChildAdded

protected onChildAdded: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-added' message.

method onChildRemoved

protected onChildRemoved: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-removed' message.

method processMessage

processMessage: (msg: any) => void;
  • Process a message sent to the widget.

    Parameter msg

    The message sent to the widget.

method restoreLayout

restoreLayout: (config: DockPanel.ILayoutConfig) => void;
  • Restore the layout to a previously saved configuration.

    Parameter 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.

method saveLayout

saveLayout: () => DockPanel.ILayoutConfig;
  • 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.

method selectedWidgets

selectedWidgets: () => any;
  • 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.

method selectWidget

selectWidget: (widget: Widget) => void;
  • Select a specific widget in the dock panel.

    Parameter widget

    The widget of interest.

    #### Notes This will make the widget the current widget in its tab area.

method tabBars

tabBars: () => any;
  • 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.

method widgets

widgets: () => any;
  • 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.

class FocusTracker

class FocusTracker<T extends Widget> implements IDisposable {}
  • A class which tracks focus among a set of widgets.

    This class is useful when code needs to keep track of the most recently focused widget(s) among a set of related widgets.

constructor

constructor();
  • Construct a new focus tracker.

property activeChanged

readonly activeChanged: any;
  • A signal emitted when the active widget has changed.

property activeWidget

readonly activeWidget: Widget;
  • The active widget in the tracker.

    #### Notes The active widget is the widget among the tracked widgets which has the *descendant node* which is currently focused.

property currentChanged

readonly currentChanged: any;
  • A signal emitted when the current widget has changed.

property currentWidget

readonly currentWidget: Widget;
  • The current widget in the tracker.

    #### Notes The current widget is the widget among the tracked widgets which has the *descendant node* which has most recently been focused.

    The current widget will not be updated if the node loses focus. It will only be updated when a different tracked widget gains focus.

    If the current widget is removed from the tracker, the previous current widget will be restored.

    This behavior is intended to follow a user's conceptual model of a semantically "current" widget, where the "last thing of type X" to be interacted with is the "current instance of X", regardless of whether that instance still has focus.

property isDisposed

readonly isDisposed: boolean;
  • A flag indicating whether the tracker is disposed.

property widgets

readonly widgets: readonly T[];
  • A read only array of the widgets being tracked.

method add

add: (widget: T) => void;
  • Add a widget to the focus tracker.

    Parameter widget

    The widget of interest.

    #### Notes A widget will be automatically removed from the tracker if it is disposed after being added.

    If the widget is already tracked, this is a no-op.

method dispose

dispose: () => void;
  • Dispose of the resources held by the tracker.

method focusNumber

focusNumber: (widget: T) => number;
  • Get the focus number for a particular widget in the tracker.

    Parameter widget

    The widget of interest.

    Returns

    The focus number for the given widget, or -1 if the widget has not had focus since being added to the tracker, or is not contained by the tracker.

    #### Notes The focus number indicates the relative order in which the widgets have gained focus. A widget with a larger number has gained focus more recently than a widget with a smaller number.

    The currentWidget will always have the largest focus number.

    All widgets start with a focus number of -1, which indicates that the widget has not been focused since being added to the tracker.

method handleEvent

handleEvent: (event: Event) => void;
  • Handle the DOM events for the focus tracker.

    Parameter 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 tracked nodes. It should not be called directly by user code.

method has

has: (widget: T) => boolean;
  • Test whether the focus tracker contains a given widget.

    Parameter widget

    The widget of interest.

    Returns

    true if the widget is tracked, false otherwise.

method remove

remove: (widget: T) => void;
  • Remove a widget from the focus tracker.

    #### Notes If the widget is the currentWidget, the previous current widget will become the new currentWidget.

    A widget will be automatically removed from the tracker if it is disposed after being added.

    If the widget is not tracked, this is a no-op.

class GridLayout

class GridLayout extends Layout {}
  • A layout which arranges its widgets in a grid.

constructor

constructor(options?: GridLayout.IOptions);
  • Construct a new grid layout.

    Parameter options

    The options for initializing the layout.

property columnCount

columnCount: number;
  • Set the number of columns in the layout.

    #### Notes The minimum column count is 1.

property columnSpacing

columnSpacing: number;
  • Set the col spacing for the layout.

property rowCount

rowCount: number;
  • Set the number of rows in the layout.

    #### Notes The minimum row count is 1.

property rowSpacing

rowSpacing: number;
  • Set the row spacing for the layout.

method addWidget

addWidget: (widget: Widget) => void;
  • Add a widget to the grid layout.

    Parameter widget

    The widget to add to the layout.

    #### Notes If the widget is already contained in the layout, this is no-op.

method attachWidget

protected attachWidget: (widget: Widget) => void;
  • Attach a widget to the parent's DOM node.

    Parameter widget

    The widget to attach to the parent.

method columnStretch

columnStretch: (index: number) => number;
  • Get the stretch factor for a specific column.

    Parameter index

    The column index of interest.

    Returns

    The stretch factor for the column.

    #### Notes This returns -1 if the index is out of range.

method detachWidget

protected detachWidget: (widget: Widget) => void;
  • Detach a widget from the parent's DOM node.

    Parameter widget

    The widget to detach from the parent.

method dispose

dispose: () => void;
  • Dispose of the resources held by the layout.

method init

protected init: () => void;
  • Perform layout initialization which requires the parent widget.

method iter

iter: () => any;
  • Create an iterator over the widgets in the layout.

    Returns

    A new iterator over the widgets in the layout.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

method onBeforeShow

protected onBeforeShow: (msg: any) => void;
  • A message handler invoked on a 'before-show' message.

method onChildHidden

protected onChildHidden: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-hidden' message.

method onChildShown

protected onChildShown: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-shown' message.

method onFitRequest

protected onFitRequest: (msg: any) => void;
  • A message handler invoked on a 'fit-request' message.

method onResize

protected onResize: (msg: Widget.ResizeMessage) => void;
  • A message handler invoked on a 'resize' message.

method onUpdateRequest

protected onUpdateRequest: (msg: any) => void;
  • A message handler invoked on an 'update-request' message.

method removeWidget

removeWidget: (widget: Widget) => void;
  • Remove a widget from the grid layout.

    Parameter widget

    The widget to remove from the layout.

    #### Notes A widget is automatically removed from the layout when its parent is set to null. This method should only be invoked directly when removing a widget from a layout which has yet to be installed on a parent widget.

    This method does *not* modify the widget's parent.

method rowStretch

rowStretch: (index: number) => number;
  • Get the stretch factor for a specific row.

    Parameter index

    The row index of interest.

    Returns

    The stretch factor for the row.

    #### Notes This returns -1 if the index is out of range.

method setColumnStretch

setColumnStretch: (index: number, value: number) => void;
  • Set the stretch factor for a specific column.

    Parameter index

    The column index of interest.

    Parameter value

    The stretch factor for the column.

    #### Notes This is a no-op if the index is out of range.

method setRowStretch

setRowStretch: (index: number, value: number) => void;
  • Set the stretch factor for a specific row.

    Parameter index

    The row index of interest.

    Parameter value

    The stretch factor for the row.

    #### Notes This is a no-op if the index is out of range.

class Layout

abstract class Layout implements IIterable<Widget>, IDisposable {}
  • An abstract base class for creating Phosphor layouts.

    #### Notes A layout is used to add widgets to a parent and to arrange those widgets within the parent's DOM node.

    This class implements the base functionality which is required of nearly all layouts. It must be subclassed in order to be useful.

    Notably, this class does not define a uniform interface for adding widgets to the layout. A subclass should define that API in a way which is meaningful for its intended use.

constructor

constructor(options?: Layout.IOptions);
  • Construct a new layout.

    Parameter options

    The options for initializing the layout.

property fitPolicy

fitPolicy: Layout.FitPolicy;
  • Set the fit policy for the layout.

    #### Notes The fit policy controls the computed size constraints which are applied to the parent widget by the layout.

    Some layout implementations may ignore the fit policy.

    Changing the fit policy will clear the current size constraint for the parent widget and then re-fit the parent.

property isDisposed

readonly isDisposed: boolean;
  • Test whether the layout is disposed.

property parent

parent: Widget;
  • Set the parent widget of the layout.

    #### Notes This is set automatically when installing the layout on the parent widget. The parent widget should not be set directly by user code.

method dispose

dispose: () => void;
  • Dispose of the resources held by the layout.

    #### Notes This should be reimplemented to clear and dispose of the widgets.

    All reimplementations should call the superclass method.

    This method is called automatically when the parent is disposed.

method init

protected init: () => void;
  • Perform layout initialization which requires the parent widget.

    #### Notes This method is invoked immediately after the layout is installed on the parent widget.

    The default implementation reparents all of the widgets to the layout parent widget.

    Subclasses should reimplement this method and attach the child widget nodes to the parent widget's node.

method iter

abstract iter: () => any;
  • Create an iterator over the widgets in the layout.

    Returns

    A new iterator over the widgets in the layout.

    #### Notes This abstract method must be implemented by a subclass.

method onAfterAttach

protected onAfterAttach: (msg: any) => void;
  • A message handler invoked on an 'after-attach' message.

    #### Notes The default implementation of this method forwards the message to all widgets. It assumes all widget nodes are attached to the parent widget node.

    This may be reimplemented by subclasses as needed.

method onAfterDetach

protected onAfterDetach: (msg: any) => void;
  • A message handler invoked on an 'after-detach' message.

    #### Notes The default implementation of this method forwards the message to all widgets. It assumes all widget nodes are attached to the parent widget node.

    This may be reimplemented by subclasses as needed.

method onAfterHide

protected onAfterHide: (msg: any) => void;
  • A message handler invoked on an 'after-hide' message.

    #### Notes The default implementation of this method forwards the message to all non-hidden widgets. It assumes all widget nodes are attached to the parent widget node.

    This may be reimplemented by subclasses as needed.

method onAfterShow

protected onAfterShow: (msg: any) => void;
  • A message handler invoked on an 'after-show' message.

    #### Notes The default implementation of this method forwards the message to all non-hidden widgets. It assumes all widget nodes are attached to the parent widget node.

    This may be reimplemented by subclasses as needed.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

    #### Notes The default implementation of this method forwards the message to all widgets. It assumes all widget nodes are attached to the parent widget node.

    This may be reimplemented by subclasses as needed.

method onBeforeDetach

protected onBeforeDetach: (msg: any) => void;
  • A message handler invoked on a 'before-detach' message.

    #### Notes The default implementation of this method forwards the message to all widgets. It assumes all widget nodes are attached to the parent widget node.

    This may be reimplemented by subclasses as needed.

method onBeforeHide

protected onBeforeHide: (msg: any) => void;
  • A message handler invoked on a 'before-hide' message.

    #### Notes The default implementation of this method forwards the message to all non-hidden widgets. It assumes all widget nodes are attached to the parent widget node.

    This may be reimplemented by subclasses as needed.

method onBeforeShow

protected onBeforeShow: (msg: any) => void;
  • A message handler invoked on a 'before-show' message.

    #### Notes The default implementation of this method forwards the message to all non-hidden widgets. It assumes all widget nodes are attached to the parent widget node.

    This may be reimplemented by subclasses as needed.

method onChildHidden

protected onChildHidden: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-hidden' message.

    #### Notes The default implementation of this handler is a no-op.

method onChildRemoved

protected onChildRemoved: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-removed' message.

    #### Notes This will remove the child widget from the layout.

    Subclasses should **not** typically reimplement this method.

method onChildShown

protected onChildShown: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-shown' message.

    #### Notes The default implementation of this handler is a no-op.

method onFitRequest

protected onFitRequest: (msg: any) => void;
  • A message handler invoked on a 'fit-request' message.

    #### Notes The default implementation of this handler is a no-op.

method onResize

protected onResize: (msg: Widget.ResizeMessage) => void;
  • A message handler invoked on a 'resize' message.

    #### Notes The layout should ensure that its widgets are resized according to the specified layout space, and that they are sent a 'resize' message if appropriate.

    The default implementation of this method sends an UnknownSize resize message to all widgets.

    This may be reimplemented by subclasses as needed.

method onUpdateRequest

protected onUpdateRequest: (msg: any) => void;
  • A message handler invoked on an 'update-request' message.

    #### Notes The layout should ensure that its widgets are resized according to the available layout space, and that they are sent a 'resize' message if appropriate.

    The default implementation of this method sends an UnknownSize resize message to all widgets.

    This may be reimplemented by subclasses as needed.

method processParentMessage

processParentMessage: (msg: any) => void;
  • Process a message sent to the parent widget.

    Parameter msg

    The message sent to the parent widget.

    #### Notes This method is called by the parent widget to process a message.

    Subclasses may reimplement this method as needed.

method removeWidget

abstract removeWidget: (widget: Widget) => void;
  • Remove a widget from the layout.

    Parameter widget

    The widget to remove from the layout.

    #### Notes A widget is automatically removed from the layout when its parent is set to null. This method should only be invoked directly when removing a widget from a layout which has yet to be installed on a parent widget.

    This method should *not* modify the widget's parent.

class LayoutItem

class LayoutItem implements IDisposable {}
  • An object which assists in the absolute layout of widgets.

    #### Notes This class is useful when implementing a layout which arranges its widgets using absolute positioning.

    This class is used by nearly all of the built-in Phosphor layouts.

constructor

constructor(widget: Widget);
  • Construct a new layout item.

    Parameter widget

    The widget to be managed by the item.

    #### Notes The widget will be set to absolute positioning.

property isAttached

readonly isAttached: boolean;
  • Whether the managed widget is attached.

property isDisposed

readonly isDisposed: boolean;
  • Whether the layout item is disposed.

property isHidden

readonly isHidden: boolean;
  • Whether the managed widget is hidden.

property isVisible

readonly isVisible: boolean;
  • Whether the managed widget is visible.

property maxHeight

readonly maxHeight: number;
  • The computed maximum height of the widget.

    #### Notes This value can be updated by calling the fit method.

property maxWidth

readonly maxWidth: number;
  • The computed maximum width of the widget.

    #### Notes This value can be updated by calling the fit method.

property minHeight

readonly minHeight: number;
  • The computed minimum height of the widget.

    #### Notes This value can be updated by calling the fit method.

property minWidth

readonly minWidth: number;
  • The computed minimum width of the widget.

    #### Notes This value can be updated by calling the fit method.

property widget

readonly widget: Widget;
  • The widget managed by the layout item.

method dispose

dispose: () => void;
  • Dispose of the the layout item.

    #### Notes This will reset the positioning of the widget.

method fit

fit: () => void;
  • Update the computed size limits of the managed widget.

method update

update: (left: number, top: number, width: number, height: number) => void;
  • Update the position and size of the managed widget.

    Parameter left

    The left edge position of the layout box.

    Parameter top

    The top edge position of the layout box.

    Parameter width

    The width of the layout box.

    Parameter height

    The height of the layout box.

class Menu extends Widget {}
  • A widget which displays items as a canonical menu.

constructor(options: Menu.IOptions);
  • Construct a new menu.

    Parameter options

    The options for initializing the menu.

readonly aboutToClose: any;
  • A signal emitted just before the menu is closed.

    #### Notes This signal is emitted when the menu receives a 'close-request' message, just before it removes itself from the DOM.

    This signal is not emitted if the menu is already detached from the DOM when it receives the 'close-request' message.

activeIndex: number;
  • Set the index of the currently active menu item.

    #### Notes If the item cannot be activated, the index will be set to -1.

activeItem: Menu.IItem;
  • Set the currently active menu item.

    #### Notes If the item cannot be activated, the item will be set to null.

readonly childMenu: Menu;
  • The child menu of the menu.

    #### Notes This is null unless the menu has an open submenu.

readonly commands: any;
  • The command registry used by the menu.

readonly contentNode: HTMLUListElement;
  • The menu content node.

    #### Notes This is the node which holds the menu item nodes.

    Modifying this node directly can lead to undefined behavior.

readonly items: readonly Menu.IItem[];
  • A read-only array of the menu items in the menu.

readonly leafMenu: Menu;
  • The leaf menu of the menu hierarchy.

readonly menuRequested: any;
  • A signal emitted when a new menu is requested by the user.

    #### Notes This signal is emitted whenever the user presses the right or left arrow keys, and a submenu cannot be opened or closed in response.

    This signal is useful when implementing menu bars in order to open the next or previous menu in response to a user key press.

    This signal is only emitted for the root menu in a hierarchy.

readonly parentMenu: Menu;
  • The parent menu of the menu.

    #### Notes This is null unless the menu is an open submenu.

readonly renderer: Menu.IRenderer;
  • The renderer used by the menu.

readonly rootMenu: Menu;
  • The root menu of the menu hierarchy.

activateNextItem: () => void;
  • Activate the next selectable item in the menu.

    #### Notes If no item is selectable, the index will be set to -1.

activatePreviousItem: () => void;
  • Activate the previous selectable item in the menu.

    #### Notes If no item is selectable, the index will be set to -1.

addItem: (options: Menu.IItemOptions) => Menu.IItem;
  • Add a menu item to the end of the menu.

    Parameter options

    The options for creating the menu item.

    Returns

    The menu item added to the menu.

clearItems: () => void;
  • Remove all menu items from the menu.

dispose: () => void;
  • Dispose of the resources held by the menu.

handleEvent: (event: Event) => void;
  • Handle the DOM events for the menu.

    Parameter event

    The DOM event sent to the menu.

    #### Notes This method implements the DOM EventListener interface and is called in response to events on the menu's DOM nodes. It should not be called directly by user code.

insertItem: (index: number, options: Menu.IItemOptions) => Menu.IItem;
  • Insert a menu item into the menu at the specified index.

    Parameter index

    The index at which to insert the item.

    Parameter options

    The options for creating the menu item.

    Returns

    The menu item added to the menu.

    #### Notes The index will be clamped to the bounds of the items.

protected onActivateRequest: (msg: any) => void;
  • A message handler invoked on an 'activate-request' message.

protected onAfterDetach: (msg: any) => void;
  • A message handler invoked on an 'after-detach' message.

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

protected onCloseRequest: (msg: any) => void;
  • A message handler invoked on a 'close-request' message.

protected onUpdateRequest: (msg: any) => void;
  • A message handler invoked on an 'update-request' message.

open: (x: number, y: number, options?: Menu.IOpenOptions) => void;
  • Open the menu at the specified location.

    Parameter x

    The client X coordinate of the menu location.

    Parameter y

    The client Y coordinate of the menu location.

    Parameter options

    The additional options for opening the menu.

    #### Notes The menu will be opened at the given location unless it will not fully fit on the screen. If it will not fit, it will be adjusted to fit naturally on the screen.

    This is a no-op if the menu is already attached to the DOM.

removeItem: (item: Menu.IItem) => void;
  • Remove an item from the menu.

    Parameter item

    The item to remove from the menu.

    #### Notes This is a no-op if the item is not in the menu.

removeItemAt: (index: number) => void;
  • Remove the item at a given index from the menu.

    Parameter index

    The index of the item to remove.

    #### Notes This is a no-op if the index is out of range.

triggerActiveItem: () => void;
  • Trigger the active menu item.

    #### Notes If the active item is a submenu, it will be opened and the first item will be activated.

    If the active item is a command, the command will be executed.

    If the menu is not attached, this is a no-op.

    If there is no active item, this is a no-op.

class MenuBar extends Widget {}
  • A widget which displays menus as a canonical menu bar.

constructor(options?: MenuBar.IOptions);
  • Construct a new menu bar.

    Parameter options

    The options for initializing the menu bar.

activeIndex: number;
  • Set the index of the currently active menu.

    #### Notes If the menu cannot be activated, the index will be set to -1.

activeMenu: Menu;
  • Set the currently active menu.

    #### Notes If the menu does not exist, the menu will be set to null.

readonly childMenu: Menu;
  • The child menu of the menu bar.

    #### Notes This will be null if the menu bar does not have an open menu.

readonly contentNode: HTMLUListElement;
  • Get the menu bar content node.

    #### Notes This is the node which holds the menu title nodes.

    Modifying this node directly can lead to undefined behavior.

readonly menus: readonly Menu[];
  • A read-only array of the menus in the menu bar.

readonly renderer: MenuBar.IRenderer;
  • The renderer used by the menu bar.

addMenu: (menu: Menu) => void;
  • Add a menu to the end of the menu bar.

    Parameter menu

    The menu to add to the menu bar.

    #### Notes If the menu is already added to the menu bar, it will be moved.

clearMenus: () => void;
  • Remove all menus from the menu bar.

dispose: () => void;
  • Dispose of the resources held by the widget.

handleEvent: (event: Event) => void;
  • Handle the DOM events for the menu bar.

    Parameter event

    The DOM event sent to the menu bar.

    #### Notes This method implements the DOM EventListener interface and is called in response to events on the menu bar's DOM nodes. It should not be called directly by user code.

insertMenu: (index: number, menu: Menu) => void;
  • Insert a menu into the menu bar at the specified index.

    Parameter index

    The index at which to insert the menu.

    Parameter menu

    The menu to insert into the menu bar.

    #### Notes The index will be clamped to the bounds of the menus.

    If the menu is already added to the menu bar, it will be moved.

protected onActivateRequest: (msg: any) => void;
  • A message handler invoked on an 'activate-request' message.

protected onAfterDetach: (msg: any) => void;
  • A message handler invoked on an 'after-detach' message.

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

protected onUpdateRequest: (msg: any) => void;
  • A message handler invoked on an 'update-request' message.

openActiveMenu: () => void;
  • Open the active menu and activate its first menu item.

    #### Notes If there is no active menu, this is a no-op.

removeMenu: (menu: Menu) => void;
  • Remove a menu from the menu bar.

    Parameter menu

    The menu to remove from the menu bar.

    #### Notes This is a no-op if the menu is not in the menu bar.

removeMenuAt: (index: number) => void;
  • Remove the menu at a given index from the menu bar.

    Parameter index

    The index of the menu to remove.

    #### Notes This is a no-op if the index is out of range.

class Panel

class Panel extends Widget {}
  • A simple and convenient panel widget class.

    #### Notes This class is suitable as a base class for implementing a variety of convenience panel widgets, but can also be used directly with CSS to arrange a collection of widgets.

    This class provides a convenience wrapper around a [[PanelLayout]].

constructor

constructor(options?: Panel.IOptions);
  • Construct a new panel.

    Parameter options

    The options for initializing the panel.

property widgets

readonly widgets: readonly Widget[];
  • A read-only array of the widgets in the panel.

method addWidget

addWidget: (widget: Widget) => void;
  • Add a widget to the end of the panel.

    Parameter widget

    The widget to add to the panel.

    #### Notes If the widget is already contained in the panel, it will be moved.

method insertWidget

insertWidget: (index: number, widget: Widget) => void;
  • Insert a widget at the specified index.

    Parameter index

    The index at which to insert the widget.

    Parameter widget

    The widget to insert into to the panel.

    #### Notes If the widget is already contained in the panel, it will be moved.

class PanelLayout

class PanelLayout extends Layout {}
  • A concrete layout implementation suitable for many use cases.

    #### Notes This class is suitable as a base class for implementing a variety of layouts, but can also be used directly with standard CSS to layout a collection of widgets.

property widgets

readonly widgets: readonly Widget[];
  • A read-only array of the widgets in the layout.

method addWidget

addWidget: (widget: Widget) => void;
  • Add a widget to the end of the layout.

    Parameter widget

    The widget to add to the layout.

    #### Notes If the widget is already contained in the layout, it will be moved.

method attachWidget

protected attachWidget: (index: number, widget: Widget) => void;
  • Attach a widget to the parent's DOM node.

    Parameter index

    The current index of the widget in the layout.

    Parameter widget

    The widget to attach to the parent.

    #### Notes This method is called automatically by the panel layout at the appropriate time. It should not be called directly by user code.

    The default implementation adds the widgets's node to the parent's node at the proper location, and sends the appropriate attach messages to the widget if the parent is attached to the DOM.

    Subclasses may reimplement this method to control how the widget's node is added to the parent's node.

method detachWidget

protected detachWidget: (index: number, widget: Widget) => void;
  • Detach a widget from the parent's DOM node.

    Parameter index

    The previous index of the widget in the layout.

    Parameter widget

    The widget to detach from the parent.

    #### Notes This method is called automatically by the panel layout at the appropriate time. It should not be called directly by user code.

    The default implementation removes the widget's node from the parent's node, and sends the appropriate detach messages to the widget if the parent is attached to the DOM.

    Subclasses may reimplement this method to control how the widget's node is removed from the parent's node.

method dispose

dispose: () => void;
  • Dispose of the resources held by the layout.

    #### Notes This will clear and dispose all widgets in the layout.

    All reimplementations should call the superclass method.

    This method is called automatically when the parent is disposed.

method init

protected init: () => void;
  • Perform layout initialization which requires the parent widget.

method insertWidget

insertWidget: (index: number, widget: Widget) => void;
  • Insert a widget into the layout at the specified index.

    Parameter index

    The index at which to insert the widget.

    Parameter widget

    The widget to insert into the layout.

    #### Notes The index will be clamped to the bounds of the widgets.

    If the widget is already added to the layout, it will be moved.

    #### Undefined Behavior An index which is non-integral.

method iter

iter: () => any;
  • Create an iterator over the widgets in the layout.

    Returns

    A new iterator over the widgets in the layout.

method moveWidget

protected moveWidget: (
fromIndex: number,
toIndex: number,
widget: Widget
) => void;
  • Move a widget in the parent's DOM node.

    Parameter fromIndex

    The previous index of the widget in the layout.

    Parameter toIndex

    The current index of the widget in the layout.

    Parameter widget

    The widget to move in the parent.

    #### Notes This method is called automatically by the panel layout at the appropriate time. It should not be called directly by user code.

    The default implementation moves the widget's node to the proper location in the parent's node and sends the appropriate attach and detach messages to the widget if the parent is attached to the DOM.

    Subclasses may reimplement this method to control how the widget's node is moved in the parent's node.

method removeWidget

removeWidget: (widget: Widget) => void;
  • Remove a widget from the layout.

    Parameter widget

    The widget to remove from the layout.

    #### Notes A widget is automatically removed from the layout when its parent is set to null. This method should only be invoked directly when removing a widget from a layout which has yet to be installed on a parent widget.

    This method does *not* modify the widget's parent.

method removeWidgetAt

removeWidgetAt: (index: number) => void;
  • Remove the widget at a given index from the layout.

    Parameter index

    The index of the widget to remove.

    #### Notes A widget is automatically removed from the layout when its parent is set to null. This method should only be invoked directly when removing a widget from a layout which has yet to be installed on a parent widget.

    This method does *not* modify the widget's parent.

    #### Undefined Behavior An index which is non-integral.

class ScrollBar

class ScrollBar extends Widget {}
  • A widget which implements a canonical scroll bar.

constructor

constructor(options?: ScrollBar.IOptions);
  • Construct a new scroll bar.

    Parameter options

    The options for initializing the scroll bar.

property decrementNode

readonly decrementNode: HTMLDivElement;
  • The scroll bar decrement button node.

    #### Notes Modifying this node directly can lead to undefined behavior.

property incrementNode

readonly incrementNode: HTMLDivElement;
  • The scroll bar increment button node.

    #### Notes Modifying this node directly can lead to undefined behavior.

property maximum

maximum: number;
  • Set the maximum value of the scroll bar.

    #### Notes The max size will be clamped to the range [0, Infinity].

property orientation

orientation: ScrollBar.Orientation;
  • Set the orientation of the scroll bar.

property page

page: number;
  • Set the page size of the scroll bar.

    #### Notes The page size will be clamped to the range [0, Infinity].

property pageRequested

readonly pageRequested: any;
  • A signal emitted when the user clicks the scroll track.

    #### Notes The payload is whether a decrease or increase is requested.

property stepRequested

readonly stepRequested: any;
  • A signal emitted when the user clicks a step button.

    #### Notes The payload is whether a decrease or increase is requested.

property thumbMoved

readonly thumbMoved: any;
  • A signal emitted when the user moves the scroll thumb.

    #### Notes The payload is the current value of the scroll bar.

property thumbNode

readonly thumbNode: HTMLDivElement;
  • The scroll bar thumb node.

    #### Notes Modifying this node directly can lead to undefined behavior.

property trackNode

readonly trackNode: HTMLDivElement;
  • The scroll bar track node.

    #### Notes Modifying this node directly can lead to undefined behavior.

property value

value: number;
  • Set the current value of the scroll bar.

    #### Notes The value will be clamped to the range [0, maximum].

method handleEvent

handleEvent: (event: Event) => void;
  • Handle the DOM events for the scroll bar.

    Parameter event

    The DOM event sent to the scroll bar.

    #### Notes This method implements the DOM EventListener interface and is called in response to events on the scroll bar's DOM node.

    This should not be called directly by user code.

method onAfterDetach

protected onAfterDetach: (msg: any) => void;
  • A method invoked on an 'after-detach' message.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A method invoked on a 'before-attach' message.

method onUpdateRequest

protected onUpdateRequest: (msg: any) => void;
  • A method invoked on an 'update-request' message.

class SingletonLayout

class SingletonLayout extends Layout {}
  • A concrete layout implementation which holds a single widget.

    #### Notes This class is useful for creating simple container widgets which hold a single child. The child should be positioned with CSS.

property widget

widget: Widget;
  • Set the child widget for the layout.

    #### Notes Setting the child widget will cause the old child widget to be automatically disposed. If that is not desired, set the parent of the old child to null before assigning a new child.

method attachWidget

protected attachWidget: (widget: Widget) => void;
  • Attach a widget to the parent's DOM node.

    Parameter index

    The current index of the widget in the layout.

    Parameter widget

    The widget to attach to the parent.

    #### Notes This method is called automatically by the single layout at the appropriate time. It should not be called directly by user code.

    The default implementation adds the widgets's node to the parent's node at the proper location, and sends the appropriate attach messages to the widget if the parent is attached to the DOM.

    Subclasses may reimplement this method to control how the widget's node is added to the parent's node.

method detachWidget

protected detachWidget: (widget: Widget) => void;
  • Detach a widget from the parent's DOM node.

    Parameter widget

    The widget to detach from the parent.

    #### Notes This method is called automatically by the single layout at the appropriate time. It should not be called directly by user code.

    The default implementation removes the widget's node from the parent's node, and sends the appropriate detach messages to the widget if the parent is attached to the DOM.

    Subclasses may reimplement this method to control how the widget's node is removed from the parent's node.

method dispose

dispose: () => void;
  • Dispose of the resources held by the layout.

method init

protected init: () => void;
  • Perform layout initialization which requires the parent widget.

method iter

iter: () => any;
  • Create an iterator over the widgets in the layout.

    Returns

    A new iterator over the widgets in the layout.

method removeWidget

removeWidget: (widget: Widget) => void;
  • Remove a widget from the layout.

    Parameter widget

    The widget to remove from the layout.

    #### Notes A widget is automatically removed from the layout when its parent is set to null. This method should only be invoked directly when removing a widget from a layout which has yet to be installed on a parent widget.

    This method does *not* modify the widget's parent.

class SplitLayout

class SplitLayout extends PanelLayout {}
  • A layout which arranges its widgets into resizable sections.

constructor

constructor(options: SplitLayout.IOptions);
  • Construct a new split layout.

    Parameter options

    The options for initializing the layout.

property alignment

alignment: SplitLayout.Alignment;
  • Set the content alignment for the split layout.

    #### Notes This is the alignment of the widgets in the layout direction.

    The alignment has no effect if the widgets can expand to fill the entire split layout.

property handles

readonly handles: readonly HTMLDivElement[];
  • A read-only array of the split handles in the layout.

property orientation

orientation: SplitLayout.Orientation;
  • Set the layout orientation for the split layout.

property renderer

readonly renderer: SplitLayout.IRenderer;
  • The renderer used by the split layout.

property spacing

spacing: number;
  • Set the inter-element spacing for the split layout.

method attachWidget

protected attachWidget: (index: number, widget: Widget) => void;
  • Attach a widget to the parent's DOM node.

    Parameter index

    The current index of the widget in the layout.

    Parameter widget

    The widget to attach to the parent.

    #### Notes This is a reimplementation of the superclass method.

method detachWidget

protected detachWidget: (index: number, widget: Widget) => void;
  • Detach a widget from the parent's DOM node.

    Parameter index

    The previous index of the widget in the layout.

    Parameter widget

    The widget to detach from the parent.

    #### Notes This is a reimplementation of the superclass method.

method dispose

dispose: () => void;
  • Dispose of the resources held by the layout.

method init

protected init: () => void;
  • Perform layout initialization which requires the parent widget.

method moveHandle

moveHandle: (index: number, position: number) => void;
  • Move the offset position of a split handle.

    Parameter index

    The index of the handle of the interest.

    Parameter position

    The desired offset position of the handle.

    #### Notes The position is relative to the offset parent.

    This will move the handle as close as possible to the desired position. The sibling widgets will be adjusted as necessary.

method moveWidget

protected moveWidget: (
fromIndex: number,
toIndex: number,
widget: Widget
) => void;
  • Move a widget in the parent's DOM node.

    Parameter fromIndex

    The previous index of the widget in the layout.

    Parameter toIndex

    The current index of the widget in the layout.

    Parameter widget

    The widget to move in the parent.

    #### Notes This is a reimplementation of the superclass method.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

method onBeforeShow

protected onBeforeShow: (msg: any) => void;
  • A message handler invoked on a 'before-show' message.

method onChildHidden

protected onChildHidden: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-hidden' message.

method onChildShown

protected onChildShown: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-shown' message.

method onFitRequest

protected onFitRequest: (msg: any) => void;
  • A message handler invoked on a 'fit-request' message.

method onResize

protected onResize: (msg: Widget.ResizeMessage) => void;
  • A message handler invoked on a 'resize' message.

method onUpdateRequest

protected onUpdateRequest: (msg: any) => void;
  • A message handler invoked on an 'update-request' message.

method relativeSizes

relativeSizes: () => number[];
  • Get the relative sizes of the widgets in the layout.

    Returns

    A new array of the relative sizes of the widgets.

    #### Notes The returned sizes reflect the sizes of the widgets normalized relative to their siblings.

    This method **does not** measure the DOM nodes.

method setRelativeSizes

setRelativeSizes: (sizes: number[]) => void;
  • Set the relative sizes for the widgets in the layout.

    Parameter sizes

    The relative sizes for the widgets in the panel.

    #### Notes Extra values are ignored, too few will yield an undefined layout.

    The actual geometry of the DOM nodes is updated asynchronously.

class SplitPanel

class SplitPanel extends Panel {}
  • A panel which arranges its widgets into resizable sections.

    #### Notes This class provides a convenience wrapper around a [[SplitLayout]].

constructor

constructor(options?: SplitPanel.IOptions);
  • Construct a new split panel.

    Parameter options

    The options for initializing the split panel.

property alignment

alignment: SplitLayout.Alignment;
  • Set the content alignment for the split panel.

    #### Notes This is the alignment of the widgets in the layout direction.

    The alignment has no effect if the widgets can expand to fill the entire split panel.

property handles

readonly handles: readonly HTMLDivElement[];
  • A read-only array of the split handles in the panel.

property orientation

orientation: SplitLayout.Orientation;
  • Set the layout orientation for the split panel.

property renderer

readonly renderer: SplitLayout.IRenderer;
  • The renderer used by the split panel.

property spacing

spacing: number;
  • Set the inter-element spacing for the split panel.

method dispose

dispose: () => void;
  • Dispose of the resources held by the panel.

method handleEvent

handleEvent: (event: Event) => void;
  • Handle the DOM events for the split panel.

    Parameter 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.

method onAfterDetach

protected onAfterDetach: (msg: any) => void;
  • A message handler invoked on an 'after-detach' message.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

method onChildAdded

protected onChildAdded: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-added' message.

method onChildRemoved

protected onChildRemoved: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-removed' message.

method relativeSizes

relativeSizes: () => number[];
  • Get the relative sizes of the widgets in the panel.

    Returns

    A new array of the relative sizes of the widgets.

    #### Notes The returned sizes reflect the sizes of the widgets normalized relative to their siblings.

    This method **does not** measure the DOM nodes.

method setRelativeSizes

setRelativeSizes: (sizes: number[]) => void;
  • Set the relative sizes for the widgets in the panel.

    Parameter sizes

    The relative sizes for the widgets in the panel.

    #### Notes Extra values are ignored, too few will yield an undefined layout.

    The actual geometry of the DOM nodes is updated asynchronously.

class StackedLayout

class StackedLayout extends PanelLayout {}
  • A layout where visible widgets are stacked atop one another.

    #### Notes The Z-order of the visible widgets follows their layout order.

method attachWidget

protected attachWidget: (index: number, widget: Widget) => void;
  • Attach a widget to the parent's DOM node.

    Parameter index

    The current index of the widget in the layout.

    Parameter widget

    The widget to attach to the parent.

    #### Notes This is a reimplementation of the superclass method.

method detachWidget

protected detachWidget: (index: number, widget: Widget) => void;
  • Detach a widget from the parent's DOM node.

    Parameter index

    The previous index of the widget in the layout.

    Parameter widget

    The widget to detach from the parent.

    #### Notes This is a reimplementation of the superclass method.

method dispose

dispose: () => void;
  • Dispose of the resources held by the layout.

method moveWidget

protected moveWidget: (
fromIndex: number,
toIndex: number,
widget: Widget
) => void;
  • Move a widget in the parent's DOM node.

    Parameter fromIndex

    The previous index of the widget in the layout.

    Parameter toIndex

    The current index of the widget in the layout.

    Parameter widget

    The widget to move in the parent.

    #### Notes This is a reimplementation of the superclass method.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

method onBeforeShow

protected onBeforeShow: (msg: any) => void;
  • A message handler invoked on a 'before-show' message.

method onChildHidden

protected onChildHidden: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-hidden' message.

method onChildShown

protected onChildShown: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-shown' message.

method onFitRequest

protected onFitRequest: (msg: any) => void;
  • A message handler invoked on a 'fit-request' message.

method onResize

protected onResize: (msg: Widget.ResizeMessage) => void;
  • A message handler invoked on a 'resize' message.

method onUpdateRequest

protected onUpdateRequest: (msg: any) => void;
  • A message handler invoked on an 'update-request' message.

class StackedPanel

class StackedPanel extends Panel {}
  • A panel where visible widgets are stacked atop one another.

    #### Notes This class provides a convenience wrapper around a [[StackedLayout]].

constructor

constructor(options?: StackedPanel.IOptions);
  • Construct a new stacked panel.

    Parameter options

    The options for initializing the panel.

property widgetRemoved

readonly widgetRemoved: any;
  • A signal emitted when a widget is removed from a stacked panel.

method onChildAdded

protected onChildAdded: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-added' message.

method onChildRemoved

protected onChildRemoved: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-removed' message.

class TabBar

class TabBar<T> extends Widget {}
  • A widget which displays titles as a single row or column of tabs.

    #### Notes If CSS transforms are used to rotate nodes for vertically oriented text, then tab dragging will not work correctly. The tabsMovable property should be set to false when rotating nodes from CSS.

constructor

constructor(options?: TabBar.IOptions<T>);
  • Construct a new tab bar.

    Parameter options

    The options for initializing the tab bar.

property allowDeselect

allowDeselect: boolean;
  • Whether a tab can be deselected by the user.

    #### Notes Tabs can be always be deselected programmatically.

property contentNode

readonly contentNode: HTMLUListElement;
  • The tab bar content node.

    #### Notes This is the node which holds the tab nodes.

    Modifying this node directly can lead to undefined behavior.

property currentChanged

readonly currentChanged: any;
  • A signal emitted when the current tab is changed.

    #### Notes This signal is emitted when the currently selected tab is changed either through user or programmatic interaction.

    Notably, this signal is not emitted when the index of the current tab changes due to tabs being inserted, removed, or moved. It is only emitted when the actual current tab node is changed.

property currentIndex

currentIndex: number;
  • Set the index of the currently selected tab.

    #### Notes If the value is out of range, the index will be set to -1.

property currentTitle

currentTitle: Title<T>;
  • Set the currently selected title.

    #### Notes If the title does not exist, the title will be set to null.

property insertBehavior

insertBehavior: TabBar.InsertBehavior;
  • The selection behavior when inserting a tab.

property orientation

orientation: TabBar.Orientation;
  • Set the orientation of the tab bar.

    #### Notes This controls whether the tabs are arranged in a row or column.

property removeBehavior

removeBehavior: TabBar.RemoveBehavior;
  • The selection behavior when removing a tab.

property renderer

readonly renderer: TabBar.IRenderer<T>;
  • The renderer used by the tab bar.

property tabActivateRequested

readonly tabActivateRequested: any;
  • A signal emitted when a tab is clicked by the user.

    #### Notes If the clicked tab is not the current tab, the clicked tab will be made current and the currentChanged signal will be emitted first.

    This signal is emitted even if the clicked tab is the current tab.

property tabCloseRequested

readonly tabCloseRequested: any;
  • A signal emitted when a tab close icon is clicked.

    #### Notes This signal is not emitted unless the tab title is closable.

property tabDetachRequested

readonly tabDetachRequested: any;
  • A signal emitted when a tab is dragged beyond the detach threshold.

    #### Notes This signal is emitted when the user drags a tab with the mouse, and mouse is dragged beyond the detach threshold.

    The consumer of the signal should call releaseMouse and remove the tab in order to complete the detach.

    This signal is only emitted once per drag cycle.

property tabMoved

readonly tabMoved: any;
  • A signal emitted when a tab is moved by the user.

    #### Notes This signal is emitted when a tab is moved by user interaction.

    This signal is not emitted when a tab is moved programmatically.

property tabsMovable

tabsMovable: boolean;
  • Whether the tabs are movable by the user.

    #### Notes Tabs can always be moved programmatically.

property titles

readonly titles: readonly Title<T>[];
  • A read-only array of the titles in the tab bar.

method addTab

addTab: (value: Title<T> | Title.IOptions<T>) => Title<T>;
  • Add a tab to the end of the tab bar.

    Parameter value

    The title which holds the data for the tab, or an options object to convert to a title.

    Returns

    The title object added to the tab bar.

    #### Notes If the title is already added to the tab bar, it will be moved.

method clearTabs

clearTabs: () => void;
  • Remove all tabs from the tab bar.

method dispose

dispose: () => void;
  • Dispose of the resources held by the widget.

method handleEvent

handleEvent: (event: Event) => void;
  • Handle the DOM events for the tab bar.

    Parameter event

    The DOM event sent to the tab bar.

    #### Notes This method implements the DOM EventListener interface and is called in response to events on the tab bar's DOM node.

    This should not be called directly by user code.

method insertTab

insertTab: (index: number, value: Title<T> | Title.IOptions<T>) => Title<T>;
  • Insert a tab into the tab bar at the specified index.

    Parameter index

    The index at which to insert the tab.

    Parameter value

    The title which holds the data for the tab, or an options object to convert to a title.

    Returns

    The title object added to the tab bar.

    #### Notes The index will be clamped to the bounds of the tabs.

    If the title is already added to the tab bar, it will be moved.

method onAfterDetach

protected onAfterDetach: (msg: any) => void;
  • A message handler invoked on an 'after-detach' message.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

method onUpdateRequest

protected onUpdateRequest: (msg: any) => void;
  • A message handler invoked on an 'update-request' message.

method releaseMouse

releaseMouse: () => void;
  • Release the mouse and restore the non-dragged tab positions.

    #### Notes This will cause the tab bar to stop handling mouse events and to restore the tabs to their non-dragged positions.

method removeTab

removeTab: (title: Title<T>) => void;
  • Remove a tab from the tab bar.

    Parameter title

    The title for the tab to remove.

    #### Notes This is a no-op if the title is not in the tab bar.

method removeTabAt

removeTabAt: (index: number) => void;
  • Remove the tab at a given index from the tab bar.

    Parameter index

    The index of the tab to remove.

    #### Notes This is a no-op if the index is out of range.

class TabPanel

class TabPanel extends Widget {}
  • A widget which combines a TabBar and a StackedPanel.

    #### Notes This is a simple panel which handles the common case of a tab bar placed next to a content area. The selected tab controls the widget which is shown in the content area.

    For use cases which require more control than is provided by this panel, the TabBar widget may be used independently.

constructor

constructor(options?: TabPanel.IOptions);
  • Construct a new tab panel.

    Parameter options

    The options for initializing the tab panel.

property currentChanged

readonly currentChanged: any;
  • A signal emitted when the current tab is changed.

    #### Notes This signal is emitted when the currently selected tab is changed either through user or programmatic interaction.

    Notably, this signal is not emitted when the index of the current tab changes due to tabs being inserted, removed, or moved. It is only emitted when the actual current tab node is changed.

property currentIndex

currentIndex: number;
  • Set the index of the currently selected tab.

    #### Notes If the index is out of range, it will be set to -1.

property currentWidget

currentWidget: Widget;
  • Set the currently selected widget.

    #### Notes If the widget is not in the panel, it will be set to null.

property stackedPanel

readonly stackedPanel: StackedPanel;
  • The stacked panel used by the tab panel.

    #### Notes Modifying the panel directly can lead to undefined behavior.

property tabBar

readonly tabBar: TabBar<Widget>;
  • The tab bar used by the tab panel.

    #### Notes Modifying the tab bar directly can lead to undefined behavior.

property tabPlacement

tabPlacement: TabPanel.TabPlacement;
  • Set the tab placement for the tab panel.

    #### Notes This controls the position of the tab bar relative to the content.

property tabsMovable

tabsMovable: boolean;
  • Set the whether the tabs are movable by the user.

    #### Notes Tabs can always be moved programmatically.

property widgets

readonly widgets: readonly Widget[];
  • A read-only array of the widgets in the panel.

method addWidget

addWidget: (widget: Widget) => void;
  • Add a widget to the end of the tab panel.

    Parameter widget

    The widget to add to the tab panel.

    #### Notes If the widget is already contained in the panel, it will be moved.

    The widget's title is used to populate the tab.

method insertWidget

insertWidget: (index: number, widget: Widget) => void;
  • Insert a widget into the tab panel at a specified index.

    Parameter index

    The index at which to insert the widget.

    Parameter widget

    The widget to insert into to the tab panel.

    #### Notes If the widget is already contained in the panel, it will be moved.

    The widget's title is used to populate the tab.

class Title

class Title<T> {}
  • An object which holds data related to an object's title.

    #### Notes A title object is intended to hold the data necessary to display a header for a particular object. A common example is the TabPanel, which uses the widget title to populate the tab for a child widget.

constructor

constructor(options: Title.IOptions<T>);
  • Construct a new title.

    Parameter options

    The options for initializing the title.

property caption

caption: string;
  • Set the caption for the title.

property changed

readonly changed: any;
  • A signal emitted when the state of the title changes.

property className

className: string;
  • Set the extra class name for the title.

    #### Notes Multiple class names can be separated with whitespace.

property closable

closable: boolean;
  • Set the closable state for the title.

    #### Notes This controls the presence of a close icon when applicable.

property dataset

dataset: Title.Dataset;
  • Set the dataset for the title.

    #### Notes This controls the data attributes when applicable.

property icon

icon: string;
  • Deprecated

    Use iconClass instead.

property iconClass

iconClass: string;
  • Set the icon class name for the title.

    #### Notes Multiple class names can be separated with whitespace.

property iconLabel

iconLabel: string;
  • Set the icon label for the title.

    #### Notes Multiple class names can be separated with whitespace.

property label

label: string;
  • Set the label for the title.

property mnemonic

mnemonic: number;
  • Set the mnemonic index for the title.

property owner

readonly owner: {};
  • The object which owns the title.

class Widget

class Widget implements IMessageHandler, IObservableDisposable {}
  • The base class of the Phosphor widget hierarchy.

    #### Notes This class will typically be subclassed in order to create a useful widget. However, it can be used directly to host externally created content.

constructor

constructor(options?: Widget.IOptions);
  • Construct a new widget.

    Parameter options

    The options for initializing the widget.

property dataset

readonly dataset: DOMStringMap;
  • The dataset for the widget's DOM node.

property disposed

readonly disposed: any;
  • A signal emitted when the widget is disposed.

property id

id: string;
  • Set the id of the widget's DOM node.

property isAttached

readonly isAttached: boolean;
  • Test whether the widget's node is attached to the DOM.

property isDisposed

readonly isDisposed: boolean;
  • Test whether the widget has been disposed.

property isHidden

readonly isHidden: boolean;
  • Test whether the widget is explicitly hidden.

property isVisible

readonly isVisible: boolean;
  • Test whether the widget is visible.

    #### Notes A widget is visible when it is attached to the DOM, is not explicitly hidden, and has no explicitly hidden ancestors.

property layout

layout: Layout;
  • Set the layout for the widget.

    #### Notes The layout is single-use only. It cannot be changed after the first assignment.

    The layout is disposed automatically when the widget is disposed.

property node

readonly node: HTMLElement;
  • Get the DOM node owned by the widget.

property parent

parent: Widget;
  • Set the parent of the widget.

    #### Notes Children are typically added to a widget by using a layout, which means user code will not normally set the parent widget directly.

    The widget will be automatically removed from its old parent.

    This is a no-op if there is no effective parent change.

property title

readonly title: Title<Widget>;
  • The title object for the widget.

    #### Notes The title object is used by some container widgets when displaying the widget alongside some title, such as a tab panel or side bar.

    Since not all widgets will use the title, it is created on demand.

    The owner property of the title is set to this widget.

method activate

activate: () => void;
  • Post an 'activate-request' message to the widget.

    #### Notes This is a simple convenience method for posting the message.

method addClass

addClass: (name: string) => void;
  • Add a class name to the widget's DOM node.

    Parameter name

    The class name to add to the node.

    #### Notes If the class name is already added to the node, this is a no-op.

    The class name must not contain whitespace.

method children

children: () => any;
  • Create an iterator over the widget's children.

    Returns

    A new iterator over the children of the widget.

    #### Notes The widget must have a populated layout in order to have children.

    If a layout is not installed, the returned iterator will be empty.

method clearFlag

clearFlag: (flag: Widget.Flag) => void;
  • Clear the given widget flag.

    #### Notes This will not typically be called directly by user code.

method close

close: () => void;
  • Send a 'close-request' message to the widget.

    #### Notes This is a simple convenience method for sending the message.

method contains

contains: (widget: Widget) => boolean;
  • Test whether a widget is a descendant of this widget.

    Parameter widget

    The descendant widget of interest.

    Returns

    true if the widget is a descendant, false otherwise.

method dispose

dispose: () => void;
  • Dispose of the widget and its descendant widgets.

    #### Notes It is unsafe to use the widget after it has been disposed.

    All calls made to this method after the first are a no-op.

method fit

fit: () => void;
  • Post a 'fit-request' message to the widget.

    #### Notes This is a simple convenience method for posting the message.

method hasClass

hasClass: (name: string) => boolean;
  • Test whether the widget's DOM node has the given class name.

    Parameter name

    The class name of interest.

    Returns

    true if the node has the class, false otherwise.

method hide

hide: () => void;
  • Hide the widget and make it hidden to its parent widget.

    #### Notes This causes the [[isHidden]] property to be true.

    If the widget is explicitly hidden, this is a no-op.

method notifyLayout

protected notifyLayout: (msg: any) => void;
  • Invoke the message processing routine of the widget's layout.

    Parameter msg

    The message to dispatch to the layout.

    #### Notes This is a no-op if the widget does not have a layout.

    This will not typically be called directly by user code.

method onActivateRequest

protected onActivateRequest: (msg: any) => void;
  • A message handler invoked on an 'activate-request' message.

    #### Notes The default implementation of this handler is a no-op.

method onAfterAttach

protected onAfterAttach: (msg: any) => void;
  • A message handler invoked on an 'after-attach' message.

    #### Notes The default implementation of this handler is a no-op.

method onAfterDetach

protected onAfterDetach: (msg: any) => void;
  • A message handler invoked on an 'after-detach' message.

    #### Notes The default implementation of this handler is a no-op.

method onAfterHide

protected onAfterHide: (msg: any) => void;
  • A message handler invoked on an 'after-hide' message.

    #### Notes The default implementation of this handler is a no-op.

method onAfterShow

protected onAfterShow: (msg: any) => void;
  • A message handler invoked on an 'after-show' message.

    #### Notes The default implementation of this handler is a no-op.

method onBeforeAttach

protected onBeforeAttach: (msg: any) => void;
  • A message handler invoked on a 'before-attach' message.

    #### Notes The default implementation of this handler is a no-op.

method onBeforeDetach

protected onBeforeDetach: (msg: any) => void;
  • A message handler invoked on a 'before-detach' message.

    #### Notes The default implementation of this handler is a no-op.

method onBeforeHide

protected onBeforeHide: (msg: any) => void;
  • A message handler invoked on a 'before-hide' message.

    #### Notes The default implementation of this handler is a no-op.

method onBeforeShow

protected onBeforeShow: (msg: any) => void;
  • A message handler invoked on a 'before-show' message.

    #### Notes The default implementation of this handler is a no-op.

method onChildAdded

protected onChildAdded: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-added' message.

    #### Notes The default implementation of this handler is a no-op.

method onChildRemoved

protected onChildRemoved: (msg: Widget.ChildMessage) => void;
  • A message handler invoked on a 'child-removed' message.

    #### Notes The default implementation of this handler is a no-op.

method onCloseRequest

protected onCloseRequest: (msg: any) => void;
  • A message handler invoked on a 'close-request' message.

    #### Notes The default implementation unparents or detaches the widget.

method onFitRequest

protected onFitRequest: (msg: any) => void;
  • A message handler invoked on a 'fit-request' message.

    #### Notes The default implementation of this handler is a no-op.

method onResize

protected onResize: (msg: Widget.ResizeMessage) => void;
  • A message handler invoked on a 'resize' message.

    #### Notes The default implementation of this handler is a no-op.

method onUpdateRequest

protected onUpdateRequest: (msg: any) => void;
  • A message handler invoked on an 'update-request' message.

    #### Notes The default implementation of this handler is a no-op.

method processMessage

processMessage: (msg: any) => void;
  • Process a message sent to the widget.

    Parameter msg

    The message sent to the widget.

    #### Notes Subclasses may reimplement this method as needed.

method removeClass

removeClass: (name: string) => void;
  • Remove a class name from the widget's DOM node.

    Parameter name

    The class name to remove from the node.

    #### Notes If the class name is not yet added to the node, this is a no-op.

    The class name must not contain whitespace.

method setFlag

setFlag: (flag: Widget.Flag) => void;
  • Set the given widget flag.

    #### Notes This will not typically be called directly by user code.

method setHidden

setHidden: (hidden: boolean) => void;
  • Show or hide the widget according to a boolean value.

    Parameter hidden

    true to hide the widget, or false to show it.

    #### Notes This is a convenience method for hide() and show().

method show

show: () => void;
  • Show the widget and make it visible to its parent widget.

    #### Notes This causes the [[isHidden]] property to be false.

    If the widget is not explicitly hidden, this is a no-op.

method testFlag

testFlag: (flag: Widget.Flag) => boolean;
  • Test whether the given widget flag is set.

    #### Notes This will not typically be called directly by user code.

method toggleClass

toggleClass: (name: string, force?: boolean) => boolean;
  • Toggle a class name on the widget's DOM node.

    Parameter name

    The class name to toggle on the node.

    Parameter force

    Whether to force add the class (true) or force remove the class (false). If not provided, the presence of the class will be toggled from its current state.

    Returns

    true if the class is now present, false otherwise.

    #### Notes The class name must not contain whitespace.

method update

update: () => void;
  • Post an 'update-request' message to the widget.

    #### Notes This is a simple convenience method for posting the message.

Namespaces

namespace BoxEngine

namespace BoxEngine {}
  • The namespace for the box engine layout functions.

function adjust

adjust: (sizers: ArrayLike<BoxSizer>, index: number, delta: number) => void;
  • Adjust a sizer by a delta and update its neighbors accordingly.

    Parameter sizers

    The sizers which should be adjusted.

    Parameter index

    The index of the sizer to grow.

    Parameter delta

    The amount to adjust the sizer, positive or negative.

    #### Notes This will adjust the indicated sizer by the specified amount, along with the sizes of the appropriate neighbors, subject to the limits specified by each of the sizers.

    This is useful when implementing box layouts where the boundaries between the sizers are interactively adjustable by the user.

function calc

calc: (sizers: ArrayLike<BoxSizer>, space: number) => number;
  • Calculate the optimal layout sizes for a sequence of box sizers.

    This distributes the available layout space among the box sizers according to the following algorithm:

    1. Initialize the sizers's size to its size hint and compute the sums for each of size hint, min size, and max size.

    2. If the total size hint equals the available space, return.

    3. If the available space is less than the total min size, set all sizers to their min size and return.

    4. If the available space is greater than the total max size, set all sizers to their max size and return.

    5. If the layout space is less than the total size hint, distribute the negative delta as follows:

    a. Shrink each sizer with a stretch factor greater than zero by an amount proportional to the negative space and the sum of stretch factors. If the sizer reaches its min size, remove it and its stretch factor from the computation.

    b. If after adjusting all stretch sizers there remains negative space, distribute the space equally among the sizers with a stretch factor of zero. If a sizer reaches its min size, remove it from the computation.

    6. If the layout space is greater than the total size hint, distribute the positive delta as follows:

    a. Expand each sizer with a stretch factor greater than zero by an amount proportional to the postive space and the sum of stretch factors. If the sizer reaches its max size, remove it and its stretch factor from the computation.

    b. If after adjusting all stretch sizers there remains positive space, distribute the space equally among the sizers with a stretch factor of zero. If a sizer reaches its max size, remove it from the computation.

    7. return

    Parameter sizers

    The sizers for a particular layout line.

    Parameter space

    The available layout space for the sizers.

    Returns

    The delta between the provided available space and the actual consumed space. This value will be zero if the sizers can be adjusted to fit, negative if the available space is too small, and positive if the available space is too large.

    #### Notes The [[size]] of each sizer is updated with the computed size.

    This function can be called at any time to recompute the layout for an existing sequence of sizers. The previously computed results will have no effect on the new output. It is therefore not necessary to create new sizer objects on each resize event.

namespace BoxLayout

namespace BoxLayout {}
  • The namespace for the BoxLayout class statics.

function getSizeBasis

getSizeBasis: (widget: Widget) => number;
  • Get the box layout size basis for the given widget.

    Parameter widget

    The widget of interest.

    Returns

    The box layout size basis for the widget.

function getStretch

getStretch: (widget: Widget) => number;
  • Get the box layout stretch factor for the given widget.

    Parameter widget

    The widget of interest.

    Returns

    The box layout stretch factor for the widget.

function setSizeBasis

setSizeBasis: (widget: Widget, value: number) => void;
  • Set the box layout size basis for the given widget.

    Parameter widget

    The widget of interest.

    Parameter value

    The value for the size basis.

function setStretch

setStretch: (widget: Widget, value: number) => void;
  • Set the box layout stretch factor for the given widget.

    Parameter widget

    The widget of interest.

    Parameter value

    The value for the stretch factor.

interface IOptions

interface IOptions {}
  • An options object for initializing a box layout.

property alignment

alignment?: Alignment;
  • The content alignment of the layout.

    The default is 'start'.

property direction

direction?: Direction;
  • The direction of the layout.

    The default is 'top-to-bottom'.

property spacing

spacing?: number;
  • The spacing between items in the layout.

    The default is 4.

type Alignment

type Alignment = 'start' | 'center' | 'end' | 'justify';
  • A type alias for a box layout alignment.

type Direction

type Direction =
| 'left-to-right'
| 'right-to-left'
| 'top-to-bottom'
| 'bottom-to-top';
  • A type alias for a box layout direction.

namespace BoxPanel

namespace BoxPanel {}
  • The namespace for the BoxPanel class statics.

function getSizeBasis

getSizeBasis: (widget: Widget) => number;
  • Get the box panel size basis for the given widget.

    Parameter widget

    The widget of interest.

    Returns

    The box panel size basis for the widget.

function getStretch

getStretch: (widget: Widget) => number;
  • Get the box panel stretch factor for the given widget.

    Parameter widget

    The widget of interest.

    Returns

    The box panel stretch factor for the widget.

function setSizeBasis

setSizeBasis: (widget: Widget, value: number) => void;
  • Set the box panel size basis for the given widget.

    Parameter widget

    The widget of interest.

    Parameter value

    The value for the size basis.

function setStretch

setStretch: (widget: Widget, value: number) => void;
  • Set the box panel stretch factor for the given widget.

    Parameter widget

    The widget of interest.

    Parameter value

    The value for the stretch factor.

interface IOptions

interface IOptions {}
  • An options object for initializing a box panel.

property alignment

alignment?: Alignment;
  • The content alignment of the panel.

    The default is 'start'.

property direction

direction?: Direction;
  • The layout direction of the panel.

    The default is 'top-to-bottom'.

property layout

layout?: BoxLayout;
  • The box layout to use for the box panel.

    If this is provided, the other options are ignored.

    The default is a new BoxLayout.

property spacing

spacing?: number;
  • The spacing between items in the panel.

    The default is 4.

type Alignment

type Alignment = BoxLayout.Alignment;
  • A type alias for a box panel alignment.

type Direction

type Direction = BoxLayout.Direction;
  • A type alias for a box panel direction.

namespace CommandPalette

namespace CommandPalette {}
  • The namespace for the CommandPalette class statics.

variable defaultRenderer

const defaultRenderer: Renderer;
  • The default Renderer instance.

class Renderer

class Renderer implements IRenderer {}
  • The default implementation of IRenderer.

method createIconClass

createIconClass: (data: IItemRenderData) => string;
  • Create the class name for the command item icon.

    Parameter data

    The data to use for the class name.

    Returns

    The full class name for the item icon.

method createItemClass

createItemClass: (data: IItemRenderData) => string;
  • Create the class name for the command palette item.

    Parameter data

    The data to use for the class name.

    Returns

    The full class name for the command palette item.

method createItemDataset

createItemDataset: (data: IItemRenderData) => any;
  • Create the dataset for the command palette item.

    Parameter data

    The data to use for creating the dataset.

    Returns

    The dataset for the command palette item.

method formatEmptyMessage

formatEmptyMessage: (data: IEmptyMessageRenderData) => any;
  • Create the render content for the empty message node.

    Parameter data

    The data to use for the empty message content.

    Returns

    The content to add to the empty message node.

method formatHeader

formatHeader: (data: IHeaderRenderData) => any;
  • Create the render content for the header node.

    Parameter data

    The data to use for the header content.

    Returns

    The content to add to the header node.

method formatItemCaption

formatItemCaption: (data: IItemRenderData) => any;
  • Create the render content for the item caption node.

    Parameter data

    The data to use for the caption content.

    Returns

    The content to add to the caption node.

method formatItemLabel

formatItemLabel: (data: IItemRenderData) => any;
  • Create the render content for the item label node.

    Parameter data

    The data to use for the label content.

    Returns

    The content to add to the label node.

method formatItemShortcut

formatItemShortcut: (data: IItemRenderData) => any;
  • Create the render content for the item shortcut node.

    Parameter data

    The data to use for the shortcut content.

    Returns

    The content to add to the shortcut node.

method renderEmptyMessage

renderEmptyMessage: (data: IEmptyMessageRenderData) => any;
  • Render the empty results message for a command palette.

    Parameter data

    The data to use for rendering the message.

    Returns

    A virtual element representing the message.

method renderHeader

renderHeader: (data: IHeaderRenderData) => any;
  • Render the virtual element for a command palette header.

    Parameter data

    The data to use for rendering the header.

    Returns

    A virtual element representing the header.

method renderItem

renderItem: (data: IItemRenderData) => any;
  • Render the virtual element for a command palette item.

    Parameter data

    The data to use for rendering the item.

    Returns

    A virtual element representing the item.

method renderItemCaption

renderItemCaption: (data: IItemRenderData) => any;
  • Render the caption for a command palette item.

    Parameter data

    The data to use for rendering the caption.

    Returns

    A virtual element representing the caption.

method renderItemContent

renderItemContent: (data: IItemRenderData) => any;
  • Render the content for a command palette item.

    Parameter data

    The data to use for rendering the content.

    Returns

    A virtual element representing the content.

method renderItemIcon

renderItemIcon: (data: IItemRenderData) => any;
  • Render the icon for a command palette item.

    Parameter data

    The data to use for rendering the icon.

    Returns

    A virtual element representing the icon.

method renderItemLabel

renderItemLabel: (data: IItemRenderData) => any;
  • Render the label for a command palette item.

    Parameter data

    The data to use for rendering the label.

    Returns

    A virtual element representing the label.

method renderItemShortcut

renderItemShortcut: (data: IItemRenderData) => any;
  • Render the shortcut for a command palette item.

    Parameter data

    The data to use for rendering the shortcut.

    Returns

    A virtual element representing the shortcut.

interface IEmptyMessageRenderData

interface IEmptyMessageRenderData {}
  • The render data for a command palette empty message.

property query

query: string;
  • The query which failed to match any commands.

interface IHeaderRenderData

interface IHeaderRenderData {}
  • The render data for a command palette header.

property category

readonly category: string;
  • The category of the header.

property indices

readonly indices: ReadonlyArray<number> | null;
  • The indices of the matched characters in the category.

interface IItem

interface IItem {}
  • An object which represents an item in a command palette.

    #### Notes Item objects are created automatically by a command palette.

property args

readonly args: ReadonlyJSONObject;
  • The arguments for the command.

property caption

readonly caption: string;
  • The display caption for the command item.

property category

readonly category: string;
  • The category for the command item.

property className

readonly className: string;
  • The extra class name for the command item.

property command

readonly command: string;
  • The command to execute when the item is triggered.

property dataset

readonly dataset: CommandRegistry.Dataset;
  • The dataset for the command item.

property iconClass

readonly iconClass: string;
  • The icon class for the command item.

property iconLabel

readonly iconLabel: string;
  • The icon label for the command item.

property isEnabled

readonly isEnabled: boolean;
  • Whether the command item is enabled.

property isToggled

readonly isToggled: boolean;
  • Whether the command item is toggled.

property isVisible

readonly isVisible: boolean;
  • Whether the command item is visible.

property keyBinding

readonly keyBinding: CommandRegistry.IKeyBinding | null;
  • The key binding for the command item.

property label

readonly label: string;
  • The display label for the command item.

property rank

readonly rank: number;
  • The rank for the command item.

interface IItemOptions

interface IItemOptions {}
  • An options object for creating a command item.

property args

args?: ReadonlyJSONObject;
  • The arguments for the command.

    The default value is an empty object.

property category

category: string;
  • The category for the item.

property command

command: string;
  • The command to execute when the item is triggered.

property rank

rank?: number;
  • The rank for the command item.

    The rank is used as a tie-breaker when ordering command items for display. Items are sorted in the following order: 1. Text match (lower is better) 2. Category (locale order) 3. Rank (lower is better) 4. Label (locale order)

    The default rank is Infinity.

interface IItemRenderData

interface IItemRenderData {}
  • The render data for a command palette item.

property active

readonly active: boolean;
  • Whether the item is the active item.

property indices

readonly indices: ReadonlyArray<number> | null;
  • The indices of the matched characters in the label.

property item

readonly item: IItem;
  • The command palette item to render.

interface IOptions

interface IOptions {}
  • An options object for creating a command palette.

property commands

commands: CommandRegistry;
  • The command registry for use with the command palette.

property renderer

renderer?: IRenderer;
  • A custom renderer for use with the command palette.

    The default is a shared renderer instance.

interface IRenderer

interface IRenderer {}
  • A renderer for use with a command palette.

method renderEmptyMessage

renderEmptyMessage: (data: IEmptyMessageRenderData) => any;
  • Render the empty results message for a command palette.

    Parameter data

    The data to use for rendering the message.

    Returns

    A virtual element representing the message.

method renderHeader

renderHeader: (data: IHeaderRenderData) => any;
  • Render the virtual element for a command palette header.

    Parameter data

    The data to use for rendering the header.

    Returns

    A virtual element representing the header.

method renderItem

renderItem: (data: IItemRenderData) => any;
  • Render the virtual element for a command palette item.

    Parameter data

    The data to use for rendering the item.

    Returns

    A virtual element representing the item.

    #### Notes The command palette will not render invisible items.

namespace ContextMenu

namespace ContextMenu {}
  • The namespace for the ContextMenu class statics.

interface IItemOptions

interface IItemOptions extends Menu.IItemOptions {}
  • An options object for creating a context menu item.

property rank

rank?: number;
  • The rank for the item.

    The rank is used as a tie-breaker when ordering context menu items for display. Items are sorted in the following order: 1. Depth in the DOM tree (deeper is better) 2. Selector specificity (higher is better) 3. Rank (lower is better) 4. Insertion order

    The default rank is Infinity.

property selector

selector: string;
  • The CSS selector for the context menu item.

    The context menu item will only be displayed in the context menu when the selector matches a node on the propagation path of the contextmenu event. This allows the menu item to be restricted to user-defined contexts.

    The selector must not contain commas.

interface IOptions

interface IOptions {}
  • An options object for initializing a context menu.

property commands

commands: CommandRegistry;
  • The command registry to use with the context menu.

property renderer

renderer?: Menu.IRenderer;
  • A custom renderer for use with the context menu.

namespace DockLayout

namespace DockLayout {}
  • The namespace for the DockLayout class statics.

interface IAddOptions

interface IAddOptions {}
  • An options object for adding a widget to the dock layout.

property mode

mode?: InsertMode;
  • The insertion mode for adding the widget.

    The default is 'tab-after'.

property ref

ref?: Widget | null;
  • The reference widget for the insert location.

    The default is null.

interface ILayoutConfig

interface ILayoutConfig {}
  • A dock layout configuration object.

property main

main: AreaConfig | null;
  • The layout config for the main dock area.

interface IOptions

interface IOptions {}
  • An options object for creating a dock layout.

property renderer

renderer: IRenderer;
  • The renderer to use for the dock layout.

property spacing

spacing?: number;
  • The spacing between items in the layout.

    The default is 4.

interface IRenderer

interface IRenderer {}
  • A renderer for use with a dock layout.

method createHandle

createHandle: () => HTMLDivElement;
  • Create a new handle node for use with a dock layout.

    Returns

    A new handle node for a dock layout.

method createTabBar

createTabBar: () => TabBar<Widget>;
  • Create a new tab bar for use with a dock layout.

    Returns

    A new tab bar for a dock layout.

interface ISplitAreaConfig

interface ISplitAreaConfig {}
  • A layout config object for a split area.

property children

children: AreaConfig[];
  • The children in the split area.

property orientation

orientation: 'horizontal' | 'vertical';
  • The orientation of the split area.

property sizes

sizes: number[];
  • The relative sizes of the children.

property