From 2d86378d155a6ac873b5403d5e6ae2de6c048a09 Mon Sep 17 00:00:00 2001 From: stephenjelfs Date: Mon, 2 May 2016 13:27:51 +0200 Subject: [PATCH 1/5] Added more typing information for Container. --- index.d.ts | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 76 insertions(+), 2 deletions(-) diff --git a/index.d.ts b/index.d.ts index 848843c85..efe0494c5 100644 --- a/index.d.ts +++ b/index.d.ts @@ -363,7 +363,7 @@ declare namespace GoldenLayout { content: ItemConfigType[]; } - export interface ContentItem { + export interface ContentItem extends EventEmitter { /** * This items configuration in its current state */ @@ -432,7 +432,7 @@ declare namespace GoldenLayout { /** * The item's outer element */ - element: any; + element: Container; /** * The item's inner element. Can be the same as the outer element. @@ -463,6 +463,80 @@ declare namespace GoldenLayout { * 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: any; // TODO: Type? + + /** + * 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; + + /** + * 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 { From 1c75648b5654e59e22ea2103a39c78adcea70122 Mon Sep 17 00:00:00 2001 From: stephenjelfs Date: Sun, 8 May 2016 13:21:55 +0200 Subject: [PATCH 2/5] Added remaining definitions for ContentItem --- index.d.ts | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 2 +- 2 files changed, 115 insertions(+), 1 deletion(-) diff --git a/index.d.ts b/index.d.ts index efe0494c5..9a57dc882 100644 --- a/index.d.ts +++ b/index.d.ts @@ -439,18 +439,132 @@ declare namespace GoldenLayout { */ 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(): void; + + /** + * 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 { diff --git a/package.json b/package.json index 9621ac508..eeabc0f3f 100644 --- a/package.json +++ b/package.json @@ -71,7 +71,7 @@ "goldenlayout-light-theme.css" ] }, - { + { "basePath": "/", "files": [ "typings.json" From e7379b08bc3646c3283706b96b8028c6e3df48a2 Mon Sep 17 00:00:00 2001 From: stephenjelfs Date: Sun, 8 May 2016 14:26:41 +0200 Subject: [PATCH 3/5] Added remaining BrowserWindow, Tab, and Header typings. --- index.d.ts | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 133 insertions(+), 2 deletions(-) diff --git a/index.d.ts b/index.d.ts index 9a57dc882..359082651 100644 --- a/index.d.ts +++ b/index.d.ts @@ -495,7 +495,7 @@ declare namespace GoldenLayout { /** * Removes the item from its current position in the layout and opens it in a window */ - popout(): void; + popout(): BrowserWindow; /** * Maximises the item or minimises it if it's already maximised @@ -587,7 +587,7 @@ declare namespace GoldenLayout { * A reference to the tab that controls this container. Will initially be null * (and populated once a tab event has been fired). */ - tab: any; // TODO: Type? + tab: Tab; /** * The current title of the container @@ -655,6 +655,137 @@ declare namespace GoldenLayout { 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 { From 9b47828fb2d5b42650e075cf4ef75fb6da5c3e94 Mon Sep 17 00:00:00 2001 From: stephenjelfs Date: Sun, 8 May 2016 14:29:25 +0200 Subject: [PATCH 4/5] Use same order as documentation (for easier maintainence) --- index.d.ts | 107 ++++++++++++++++++++++++++--------------------------- 1 file changed, 53 insertions(+), 54 deletions(-) diff --git a/index.d.ts b/index.d.ts index 359082651..41437cf15 100644 --- a/index.d.ts +++ b/index.d.ts @@ -2,6 +2,59 @@ // Project: https://golden-layout.com/ declare class GoldenLayout { + /** + * 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 @@ -85,60 +138,6 @@ declare class GoldenLayout { */ selectItem(contentItem: GoldenLayout.ContentItem): void; - /** - * 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; - /** * 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. From 26aeeafd6855595239f3a600e394505124438c79 Mon Sep 17 00:00:00 2001 From: stephenjelfs Date: Sun, 8 May 2016 14:32:00 +0200 Subject: [PATCH 5/5] Fixed ts-linting --- index.d.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.d.ts b/index.d.ts index 41437cf15..13cde591e 100644 --- a/index.d.ts +++ b/index.d.ts @@ -781,9 +781,9 @@ declare namespace GoldenLayout { 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 - */ + * 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; }