index.d.ts

// Type definitions for GoldenLayout v1.5.x
// Project: https://golden-layout.com/

declare module 'golden-layout' {
    class GoldenLayout implements GoldenLayout.EventEmitter {
        /**
         * The topmost item in the layout item tree. In browser terms: Think of the GoldenLayout instance as window
         * object and of goldenLayout.root as the document.
         */
        root: GoldenLayout.ContentItem;

        /**
         * A reference to the (jQuery) DOM element containing the layout
         */
        container: JQuery;

        /**
         * True once the layout item tree has been created and the initialised event has been fired
         */
        isInitialised: boolean;

        /**
         * A reference to the current, extended top level config.
         *
         * Don't rely on this object for state saving / serialisation. Use layout.toConfig() instead.
         */
        config: GoldenLayout.Config;

        /**
         * The currently selected item or null if no item is selected. Only relevant if settings.selectionEnabled is set
         * to true.
         */
        selectedItem: GoldenLayout.ContentItem;

        /**
         * The current outer width of the layout in pixels.
         */
        width: number;

        /**
         * The current outer height of the layout in pixels.
         */
        height: number;

        /**
         * An array of BrowserWindow instances
         */
        openPopouts: GoldenLayout.BrowserWindow[];

        /**
         * True if the layout has been opened as a popout by another layout.
         */
        isSubWindow: boolean;

        /**
         * A singleton instance of EventEmitter that works across windows
         */
        eventHub: GoldenLayout.EventEmitter;

        /**
         * @param config A GoldenLayout configuration object
         * @param container The DOM element the layout will be initialised in. Default: document.body
         */
        constructor(configuration: GoldenLayout.Config, container?: Element | HTMLElement | JQuery);

        /*
         * @param name 	The name of the component, as referred to by componentName in the component configuration.
         * @param component 	A constructor or factory function. Will be invoked with new and two arguments, a
         *                      containerobject and a component state
         */
        registerComponent(name: String, component: any): void;

        /**
         * Renders the layout into the container. If init() is called before the document is ready it attaches itself as
         * a listener to the document and executes once it becomes ready.
         */
        init(): void;

        /**
         * Returns the current state of the layout and its components as a serialisable object.
         */
        toConfig(): any;

        /**
         * Returns a component that was previously registered with layout.registerComponent().
         * @param name The name of a previously registered component
         */
        getComponent(name: string): any;

        /**
         * Resizes the layout. If no arguments are provided GoldenLayout measures its container and resizes accordingly.
         * @param width The outer width the layout should be resized to. Default: The container elements width
         * @param height The outer height the layout should be resized to. Default: The container elements height
         */
        updateSize(width?: number, height?: number): void;

        /**
         * Destroys the layout. Recursively calls destroy on all components and content items, removes all event
         * listeners and finally removes itself from the DOM.
         */
        destroy(): void;

        /**
         * Creates a new content item or tree of content items from configuration. Usually you wouldn't call this
         * directly, but instead use methods like layout.createDragSource(), item.addChild() or item.replaceChild() that
         * all call this method implicitly.
         * @param itemConfiguration An item configuration (can be an entire tree of items)
         * @param parent A parent item
         */
        createContentItem(itemConfiguration?: GoldenLayout.ItemConfigType, parent?: GoldenLayout.ContentItem): void;

        /**
         * Creates a new popout window with configOrContentItem as contents at the position specified in dimensions
         * @param configOrContentItem   The content item or config that will be created in the new window. If a item is
         *                              provided its config will be read, if config is provided, only the content key
         *                              will be used
         * @param dimensions    A map containing the keys left, top, width and height. Left and top can be negative to
         *                      place the window in another screen.
         * @param parentId  The id of the item within the current layout the child window's content will be appended to
         *                  when popIn is clicked
         * @param indexInParent The index at which the child window's contents will be appended to. Default: null
         */
        createPopout(configOrContentItem: GoldenLayout.ItemConfigType | GoldenLayout.ContentItem,
                     dimensions: {
                         width: number,
                         height: number,
                         left: number,
                         top: number
                     }, parentId?: string,
                     indexInParent?: number): void;

        /**
         * Turns a DOM element into a dragSource, meaning that the user can drag the element directly onto the layout
         * where it turns into a contentItem.
         * @param element The DOM element that will be turned into a dragSource
         * @param itemConfiguration An item configuration (can be an entire tree of items)
         */
        createDragSource(element: HTMLElement | JQuery, itemConfiguration: GoldenLayout.ItemConfigType): void;

        /**
         * If settings.selectionEnabled is set to true, this allows to select items programmatically.
         * @param contentItem A ContentItem instance
         */
        selectItem(contentItem: GoldenLayout.ContentItem): void;

        /**
         * Static method on the GoldenLayout constructor! This method will iterate through a GoldenLayout config object
         * and replace frequent keys and values with single letter substitutes.
         * @param config A GoldenLayout configuration object
         */
        static minifyConfig(config: any): any;

        /**
         * Static method on the GoldenLayout constructor! This method will reverse the minifications of GoldenLayout.minifyConfig.
         * @param minifiedConfig A minified GoldenLayout configuration object
         */
        static unminifyConfig(minifiedConfig: any): any;

        /**
         * Subscribe to an event
         * @param eventName The name of the event to describe to
         * @param callback The function that should be invoked when the event occurs
         * @param context The value of the this pointer in the callback function
         */
        on(eventName: string, callback: Function, context?: any): void;

        /**
         * Notify listeners of an event and pass arguments along
         * @param eventName The name of the event to emit
         */
        emit(eventName: string, arg1?: any, arg2?: any, ...argN: any[]): void;

        /**
         * Alias for emit
         */
        trigger(eventName: string, arg1?: any, arg2?: any, ...argN: any[]): void;

        /**
         * Unsubscribes either all listeners if just an eventName is provided, just a specific callback if invoked with
         * eventName and callback or just a specific callback with a specific context if invoked with all three
         * arguments.
         * @param eventName The name of the event to unsubscribe from
         * @param callback The function that should be invoked when the event occurs
         * @param context The value of the this pointer in the callback function
         */
        unbind(eventName: string, callback?: Function, context?: any): void;

        /**
         * Alias for unbind
         */
        off(eventName: string, callback?: Function, context?: any): void;
    }

    namespace GoldenLayout {

        export type ItemConfigType = ItemConfig | ComponentConfig | ReactComponentConfig;

        export interface Settings {
            /**
             * Turns headers on or off. If false, the layout will be displayed with splitters only.
             * Default: true
             */
            hasHeaders?: boolean;

            /**
             * Constrains the area in which items can be dragged to the layout's container. Will be set to false
             * automatically when layout.createDragSource() is called.
             * Default: true
             */
            constrainDragToContainer?: boolean;

            /**
             * If true, the user can re-arrange the layout by dragging items by their tabs to the desired location.
             * Default: true
             */
            reorderEnabled?: boolean;

            /**
             * If true, the user can select items by clicking on their header. This sets the value of layout.selectedItem to
             * the clicked item, highlights its header and the layout emits a 'selectionChanged' event.
             * Default: false
             */
            selectionEnabled?: boolean;

            /**
             * Decides what will be opened in a new window if the user clicks the popout icon. If true the entire stack will
             * be transferred to the new window, if false only the active component will be opened.
             * Default: false
             */
            popoutWholeStack?: boolean;

            /**
             * Specifies if an error is thrown when a popout is blocked by the browser (e.g. by opening it programmatically).
             * If false, the popout call will fail silently.
             * Default: true
             */
            blockedPopoutsThrowError?: boolean;

            /**
             * Specifies if all popouts should be closed when the page that created them is closed. Popouts don't have a
             * strong dependency on their parent and can exist on their own, but can be quite annoying to close by hand. In
             * addition, any changes made to popouts won't be stored after the parent is closed.
             * Default: true
             */
            closePopoutsOnUnload?: boolean;

            /**
             * Specifies if the popout icon should be displayed in the header-bar.
             * Default: true
             */
            showPopoutIcon?: boolean;

            /**
             * Specifies if the maximise icon should be displayed in the header-bar.
             * Default: true
             */
            showMaximiseIcon?: boolean;

            /**
             * Specifies if the close icon should be displayed in the header-bar.
             * Default: true
             */
            showCloseIcon?: boolean;
        }

        export interface Dimensions {
            /**
             * The width of the borders between the layout items in pixel. Please note: The actual draggable area is wider
             * than the visible one, making it safe to set this to small values without affecting usability.
             * Default: 5
             */
            borderWidth?: number;

            /**
             * The minimum height an item can be resized to (in pixel).
             * Default: 10
             */
            minItemHeight?: number;

            /**
             * The minimum width an item can be resized to (in pixel).
             * Default: 10
             */
            minItemWidth?: number;

            /**
             * The height of the header elements in pixel. This can be changed, but your theme's header css needs to be
             * adjusted accordingly.
             * Default: 20
             */
            headerHeight?: number;

            /**
             * The width of the element that appears when an item is dragged (in pixel).
             * Default: 300
             */
            dragProxyWidth?: number;

            /**
             * The height of the element that appears when an item is dragged (in pixel).
             * Default: 200
             */
            dragProxyHeight?: number;
        }

        export interface Labels {
            /**
             * The tooltip text that appears when hovering over the close icon.
             * Default: 'close'
             */
            close?: string;

            /**
             * The tooltip text that appears when hovering over the maximise icon.
             * Default: 'maximise'
             */
            maximise?: string;

            /**
             * The tooltip text that appears when hovering over the minimise icon.
             * Default: 'minimise'
             */
            minimise?: string;

            /**
             * The tooltip text that appears when hovering over the popout icon.
             * Default: 'open in new window'
             */
            popout?: string;
        }

        export interface ItemConfig {
            /**
             * The type of the item. Possible values are 'row', 'column', 'stack', 'component' and 'react-component'.
             */
            type: string;

            /**
             * An array of configurations for items that will be created as children of this item.
             */
            content?: ItemConfigType[];

            /**
             * The width of this item, relative to the other children of its parent in percent
             */
            width?: number;

            /**
             * The height of this item, relative to the other children of its parent in percent
             */
            height?: number;

            /**
             * A String or an Array of Strings. Used to retrieve the item using item.getItemsById()
             */
            id?: string | string[];

            /**
             * Determines if the item is closable. If false, the x on the items tab will be hidden and container.close()
             * will return false
             * Default: true
             */
            isClosable?: boolean;

            /**
             * The title of the item as displayed on its tab and on popout windows
             * Default: componentName or ''
             */
            title?: string;
        }

        export interface ComponentConfig extends ItemConfig {
            /**
             * The name of the component as specified in layout.registerComponent. Mandatory if type is 'component'.
             */
            componentName: string;

            /**
             * A serialisable object. Will be passed to the component constructor function and will be the value returned by
             * container.getState().
             */
            componentState?: any;
        }

        export interface ReactComponentConfig extends ItemConfig {
            /**
             * The name of the component as specified in layout.registerComponent. Mandatory if type is 'react-component'
             */
            component: string;

            /**
             * Properties that will be passed to the component and accessible using this.props.
             */
            props?: any;
        }

        export interface Config {
            settings?: Settings;
            dimensions?: Dimensions;
            labels?: Labels;
            content?: ItemConfigType[];
        }

        export interface ContentItem extends EventEmitter {
            /**
             * This items configuration in its current state
             */
            config: ItemConfigType;

            /**
             * The type of the item. Can be row, column, stack, component or root
             */
            type: string;

            /**
             * An array of items that are children of this item
             */
            contentItems: ContentItem[];

            /**
             * The item that is this item's parent (or null if the item is root)
             */
            parent: ContentItem;

            /**
             * A String or array of identifiers if provided in the configuration
             */
            id: string;

            /**
             * True if the item had been initialised
             */
            isInitialised: boolean;

            /**
             * True if the item is maximised
             */
            isMaximised: boolean;

            /**
             * True if the item is the layout's root item
             */
            isRoot: boolean;

            /**
             * True if the item is a row
             */
            isRow: boolean;

            /**
             * True if the item is a column
             */
            isColumn: boolean;

            /**
             * True if the item is a stack
             */
            isStack: boolean;

            /**
             * True if the item is a component
             */
            isComponent: boolean;

            /**
             * A reference to the layoutManager that controls this item
             */
            layoutManager: any;

            /**
             * The item's outer element
             */
            element: Container;

            /**
             * The item's inner element. Can be the same as the outer element.
             */
            childElementContainer: Container;

            /**
             * Adds an item as a child to this item. If the item is already a part of a layout it will be removed
             * from its original position before adding it to this item.
             * @param itemOrItemConfig A content item (or tree of content items) or an ItemConfiguration to create the item from
             * @param index last index  An optional index that determines at which position the new item should be added. Default: last index.
             */
            addChild(itemOrItemConfig: ContentItem | ItemConfigType, index?: number): void;

            /**
             * Destroys the item and all it's children
             * @param contentItem The contentItem that should be removed
             * @param keepChild If true the item won't be destroyed. (Use cautiosly, if the item isn't destroyed it's up to you to destroy it later). Default: false.
             */
            removeChild(contentItem: Config, keepChild?: boolean): void;

            /**
             * The contentItem that should be removed
             * @param oldChild    ContentItem The contentItem that should be removed
             * @param newChild A content item (or tree of content items) or an ItemConfiguration to create the item from
             */
            replaceChild(oldChild: ContentItem, newChild: ContentItem | ItemConfigType): void;

            /**
             * Updates the items size. To actually assign a new size from within a component, use container.setSize( width, height )
             */
            setSize(): void;

            /**
             * Sets the item's title to the provided value. Triggers titleChanged and stateChanged events
             * @param title the new title
             */
            setTitle(title: string): void;

            /**
             * A powerful, yet admittedly confusing method to recursively call methods on items in a tree. Usually you wouldn't need
             * to use it directly, but it's used internally to setSizes, destroy parts of the item tree etc.
             * @param functionName The name of the method to invoke
             * @param functionArguments An array of arguments to pass to every function
             * @param bottomUp If true, the method is invoked on the lowest parts of the tree first and then bubbles upwards. Default: false
             * @param skipSelf If true, the method will only be invoked on the item's children, but not on the item itself. Default: false
             */
            callDownwards(functionName: string, functionArguments?: any[], bottomUp?: boolean, skipSelf?: boolean): void;

            /**
             * Emits an event that bubbles up the item tree until it reaches the root element (and after a delay the layout manager). Useful e.g. for indicating state changes.
             */
            emitBubblingEvent(name: string): void;

            /**
             * Convenience method for item.parent.removeChild( item )
             */
            remove(): void;

            /**
             * Removes the item from its current position in the layout and opens it in a window
             */
            popout(): BrowserWindow;

            /**
             * Maximises the item or minimises it if it's already maximised
             */
            toggleMaximise(): void;

            /**
             * Selects the item. Only relevant if settings.selectionEnabled is set to true
             */
            select(): void;

            /**
             * Unselects the item. Only relevant if settings.selectionEnabled is set to true
             */
            deselect(): void;

            /**
             * Returns true if the item has the specified id or false if not
             * @param id An id to check for
             */
            hasId(id: string): boolean;

            /**
             * Only Stacks have this method! It's the programmatical equivalent of clicking a tab.
             * @param contentItem The new active content item
             */
            setActiveContentItem(contentItem: ContentItem): void;

            /**
             * Only Stacks have this method! Returns the currently selected contentItem.
             */
            getActiveContentItem(): ContentItem;

            /**
             * Adds an id to an item or does nothing if the id is already present
             * @param id The id to be added
             */
            addId(id: string): void;

            /**
             * Removes an id from an item or throws an error if the id couldn't be found
             * @param id The id to be removed
             */
            removeId(id: string): void;

            /**
             * Calls filterFunction recursively for every item in the tree. If the function returns true the item is added to the resulting array
             * @param filterFunction A function that determines whether an item matches certain criteria
             */
            getItemsByFilter(filterFunction: (contentItem: ContentItem) => boolean): ContentItem[];

            /**
             * Returns all items with the specified id.
             * @param id An id specified in the itemConfig
             */
            getItemsById(id: string | string[]): ContentItem[];

            /**
             * Returns all items with the specified type
             * @param type 'row', 'column', 'stack', 'component' or 'root'
             */
            getItemsByType(type: string): ContentItem[];

            /**
             * Returns all instances of the component with the specified componentName
             * @param componentName a componentName as specified in the itemConfig
             */
            getComponentsByName(componentName: string): any;

        }

        export interface Container extends EventEmitter {
            /**
             * The current width of the container in pixel
             */
            width: number;

            /**
             * The current height of the container in pixel
             */
            height: number;

            /**
             * A reference to the component-item that controls this container
             */
            parent: ContentItem;

            /**
             * A reference to the tab that controls this container. Will initially be null
             * (and populated once a tab event has been fired).
             */
            tab: Tab;

            /**
             * The current title of the container
             */
            title: string;

            /*
             * A reference to the GoldenLayout instance this container belongs to
             */
            layoutManager: GoldenLayout;

            /**
             * True if the item is currently hidden
             */
            isHidden: boolean;

            /**
             * Overwrites the components state with the provided value. To only change parts of the componentState see
             * extendState below. This is the main mechanism for saving the state of a component. This state will be the
             * value of componentState when layout.toConfig() is called and will be passed back to the component's
             * constructor function. It will also be used when the component is opened in a new window.
             * @param state A serialisable object
             */
            setState(state: any): void;

            /**
             * This is similar to setState, but merges the provided state into the current one, rather than overwriting it.
             * @param state A serialisable object
             */
            extendState(state: any): void;

            /**
             * Returns the current state.
             */
            getState(): any;

            /**
             * Returns the container's inner element as a jQuery element
             */
            getElement(): JQuery;

            /**
             * hides the container or returns false if hiding it is not possible
             */
            hide(): boolean;

            /**
             * shows the container or returns false if showing it is not possible
             */
            show(): boolean;

            /**
             * Sets the container to the specified size or returns false if that's not possible
             * @param width the new width in pixel
             * @param height the new height in pixel
             */
            setSize(width: number, height: number): boolean;

            /**
             * Sets the item's title to the provided value. Triggers titleChanged and stateChanged events
             * @param title the new title
             */
            setTitle(title: string): void;

            /**
             * Closes the container or returns false if that is not possible
             */
            close(): boolean;
        }

        export interface BrowserWindow {

            /**
             * True if the window has been opened and its GoldenLayout instance initialised.
             */
            isInitialised: boolean;

            /**
             * Creates a window configuration object from the Popout.
             */
            toConfig(): {
                dimensions: {
                    width: number,
                    height: number,
                    left: number,
                    top: number
                },
                content: Config,
                parentId: string,
                indexInParent: number
            };

            /**
             * Returns the GoldenLayout instance from the child window
             */
            getGlInstance(): GoldenLayout;

            /**
             * Returns the native Window object
             */
            getWindow(): Window;

            /**
             * Closes the popout
             */
            close(): void;

            /**
             * Returns the popout to its original position as specified in parentId and indexInParent
             */
            popIn(): void;
        }

        export interface Header {
            /**
             * A reference to the LayoutManager instance
             */
            layoutManager: GoldenLayout;

            /**
             * A reference to the Stack this Header belongs to
             */
            parent: ContentItem;

            /**
             * An array of the Tabs within this header
             */
            tabs: Tab[];

            /**
             * The currently selected activeContentItem
             */
            activeContentItem: ContentItem;

            /**
             * The outer (jQuery) DOM element of this Header
             */
            element: JQuery;

            /**
             * The (jQuery) DOM element containing the tabs
             */
            tabsContainer: JQuery;

            /**
             * The (jQuery) DOM element containing the close, maximise and popout button
             */
            controlsContainer: JQuery;

            /**
             * Hides the currently selected contentItem, shows the specified one and highlights its tab.
             * @param contentItem The content item that will be selected
             */
            setActiveContentItem(contentItem: ContentItem): void;

            /**
             * Creates a new tab and associates it with a content item
             * @param contentItem The content item the tab will be associated with
             * @param index A zero based index, specifying the position of the new tab
             */
            createTab(contentItem: ContentItem, index?: number): void;

            /**
             * Finds a tab by its contentItem and removes it
             * @param contentItem The content item the tab is associated with
             */
            removeTab(contentItem: ContentItem): void;
        }

        export interface Tab {

            /**
             * True if this tab is the selected tab
             */
            isActive: boolean;

            /**
             * A reference to the header this tab is a child of
             */
            header: Header;

            /**
             * A reference to the content item this tab relates to
             */
            contentItem: ContentItem;

            /**
             * The tabs outer (jQuery) DOM element
             */
            element: JQuery;

            /**
             * The (jQuery) DOM element containing the title
             */
            titleElement: JQuery;

            /**
             * The (jQuery) DOM element that closes the tab
             */
            closeElement: JQuery;

            /**
             * Sets the tab's title. Does not affect the contentItem's title!
             * @param title The new title
             */
            setTitle(title: string): void;

            /**
             * Sets this tab's active state. To programmatically switch tabs, use header.setActiveContentItem( item ) instead.
             * @param isActive Whether the tab is active
             */
            setActive(isActive: boolean): void;
        }

        export interface EventEmitter {
            /**
             * Subscribe to an event
             * @param eventName The name of the event to describe to
             * @param callback The function that should be invoked when the event occurs
             * @param context The value of the this pointer in the callback function
             */
            on(eventName: string, callback: Function, context?: any): void;

            /**
             * Notify listeners of an event and pass arguments along
             * @param eventName The name of the event to emit
             */
            emit(eventName: string, arg1?: any, arg2?: any, ...argN: any[]): void;

            /**
             * Alias for emit
             */
            trigger(eventName: string, arg1?: any, arg2?: any, ...argN: any[]): void;

            /**
             * Unsubscribes either all listeners if just an eventName is provided, just a specific callback if invoked with
             * eventName and callback or just a specific callback with a specific context if invoked with all three
             * arguments.
             * @param eventName The name of the event to unsubscribe from
             * @param callback The function that should be invoked when the event occurs
             * @param context The value of the this pointer in the callback function
             */
            unbind(eventName: string, callback?: Function, context?: any): void;

            /**
             * Alias for unbind
             */
            off(eventName: string, callback?: Function, context?: any): void;
        }
    }

    export = GoldenLayout;
}