Dock Manager Specification
- Revision History
- Overview
- User Stories
- Functionality
- Acceptance criteria
- Accessibility
- Internationalization
- Assumptions and Limitations
- Test Scenarios
- References
- Konstantin Dinev | Date:
- Radoslav Mirchev | Date:
- Svilen Dimchevski | Date:
| Version | User | Date | Notes |
|---|---|---|---|
| 0.1 | Stefan Ivanov | Oct 11, 2019 | Initial draft |
| 0.2 | Diyan Dimitrov | Aug 25, 2020 | API spec |
| 0.3 | Diyan Dimitrov | Oct 30, 2020 | Update API spec |
| 0.4 | Dimitar Dimitrov | Nov 24, 2020 | Localization |
| 0.5 | Diyan Dimitrov | Aug 11, 2021 | CSS Parts |
| 0.5 | Ivaylo Barakov | Aug 30, 2023 | Moved spec from igniteui |
| 0.6 | Ivaylo Barakov | Sep 12, 2023 | Update API section |
The Dock Manager provides a framework for complex layouts splitting the view into multiple smaller ones. This can be done recursively in order to create arbitrary layouts that can be manipulated and adjusted at runtime.
As an end user:
- I want to be able to dock a pane to the left, right, top, or bottom to any level of nesting including the global/root one.
- I want to split my full-screen window in left and right pane in order to compare document versions.
- I want to dock a real-time log pane at the bottom of my window.
- I want to dock a pane with commands and operations to the top of my window similar to the MS Office Ribbon.
- I expect a visual indication (joystick) about the available positions to dock panes that is contextual to the pane over which my cursor currently is positioned.
- I want to be able to maximize/minimize a pane.
- I expect to be able to have multiple tabbed views for a certain pane.
- I expect to be able to iterate through the tabs of a pane by pressing the Ctrl+F6/Shift+Ctrl+F6 key (Cmd to replace Ctrl on a Mac). Upon reaching the last tab of a pane pressing Ctrl+F6 would take me to the next pane. Upon reaching the first tab of a pane pressing the Shift+Ctrl+F6 would take me to the previous pane.
- I expect to be able to iterate through the dock manager windows by pressing the Alt+F6/Alt+Ctrl+F6 key.
- I want to be able to reorder the tabs in a pane via drag and drop.
- I want to list all tabs of a pane that are not visible in a dropdown when the total amount of tabs cannot be fit in the width available.
- I want to stash all the panes that I don't need at the moment in a tray.
- I want to pin a docked pane, which would send it (including all the tabs it may have) to the tray for that pane.
- I want to open the tray and unpin a certain pane (with all the tabs it may have) to bring it to its last docked position or float it.
- I want to close a pane (docked or floating), which would remove it from the dock manager layout, including all the tabs it may have.
- I want to open the tray and drag an item to a destination pane and dock it to a certain position.
- I want to open/close the tray area similar to how a navigation drawer may slide in and out.
- I want to be able to resize the tray by dragging its border towards the panes adjacent to it.
- I expect that if I close my application and open it again, it would show the last layout I have created.
- I want to be able to save my layout so that I can apply it later and use it again.
- I expect that if I have a layout and load another one the panes in my current layout will be taken and docked accordingly to the newly loaded one respecting the tree structure depicting the organization of panes.
- I want to move the splitting border between two panes to change their relative sizes.
- I want to move the splitting border between a pane and a split-pane which will cause the window to force the resizing of its children accordingly.
- When moving the splitting border causes a pane to not be able to fit its visible tabs anymore, I expect the active tab to move to the first position so that it is always visible and the tab that comes last to be removed as a tab and appear in a dropdown. On the contrary, if moving the splitting border makes more space in a pane for a tab, the last tab that got moved to the dropdown will be moved back in as a tab.
- I want to take a pane and float it on top of all others.
- I want to take a floating pane and drag it outside the dock manager/browser window.
- I want to list all applicable actions for a pane in a dropdown that is shown from an action icon.
- I want to dock a pane as a tab of another view without splitting the content area.
- I expect a dialog that would list all the panes in the dock manager and let me navigate between them choosing which on to move my focus to in the end.
- I want to double click a pane header in order to maximize it or restore it to its original size once maximized.
- I want to double click a pane header while holding a modifier key CTRL/CMD in order to float it or dock it to its original place once floated.
As a developer:
- I want to define a tree structure that defines the hierarchy of my panes.
- I want to define relative proportions for the area that siblings occupy from a certain pane.
- I want to be able to dock panes programmatically by making changes to the tree.
- I want to be able to persist the organization of panes and load it next time that the dock manager is opened.
- I want to be able to exclude certain panes from the organization upon persisting it.
- I want to be able to define a special content pane (document content), which would be the main one and cannot be unpinned/minimized/sent to the tray. Its tabs are positioned at the top of the window unlike panes that have tabs at the bottom.
- I want to be able to freeze/unfreeze tabs in the document pane via pin/unpin action icon which would keep them in view under any circumstances - if necessary multiple rows of frozen tabs will be shown with the ones not frozen filling up the available space.
- I expect that it is easy to distinguish the document area from the docked panes i.e. document area has tabs at the top, while for a pane they are always rendered at the bottom.
- I want to be able to unpin and pin panes programatically.
- I want to be able to determine whether an action (unpin, close etc.)on a given pane affects all its child panes recursively (default) or affects just the parent and makes its former children into present siblings.
- I want to be able to set a certain pane as floatable which will make it appear above all others programmatically.
- I want to be able to close a certain pane programmatically persisting its state upon closing e.g. pinned/unpinned.
- I want to load a set of documents each in its own tab for a certain pane.
- I expect that each tab sizes according to the document name it has to display.
- I expect to have a tray, which can be opened or closed and it comes out of the box.
- I expect to have a suggestive layout visualization (joystick), which shows all possible docking action and it comes out of the box.
- I want to be able to define allowable docking positions for a give pane, by default it can be docked in all directions.
- I want to be able to freeze the arrangement of panes so that the user cannot resize or rearrange them but may only flip through the tabs in a certain pane and browse the document that it displays.
- I want to be able to set a minimum width and height values for every pane of the dock manager.
- I expect to be provided with a template for the tab name that by default displays only text allowing icons or images to be added to it.
- I expect to be provided with a template for the pane name that by default displays only text allowing icons or images to be added to it.
- I want to be able to change the language of all strings shown in context menus, tooltips, etc. and/or provide custom strings for each of them
Design Hands-Off:
The Dock Manager component supports localizing the strings shown in the context menus, tooltips and aria attributes. By default the Dock Manager detects the language of the page by searching for a lang attribute on any of its parents. If the lang attribute is not set or is set to a value which the Dock Manager does not support, the default language used is English(en). The Dock Manager exposes resourceStrings property which allows the user to modify the strings. If the resourceStrings property is set by the user, the Dock Manager will use it no matter what lang attribute is set.
The Dock Manager provides built-in localized strings for the following languages: English(en), Japanese(jp), Korean(ko) and Spanish(es). In order to provide resource strings for another language use the addResourceStrings(language, resourceStrings) method where language is the custom string that has to be set to the lang attribute and resourceStrings is an implementation of IgcDockManagerResourceStrings containing all custom resource strings.
| Name | Description | Type |
|---|---|---|
| activePane | Gets/sets the active pane of the Dock Manager. | IgcContentPane |
| allowMaximize | Specifies whether the end user is allowed to maximize panes. Defaults to true. | boolean |
| draggedPane | Gets/sets the currently dragged pane. |
IgcContentPane | IgcSplitPane | IgcTabGroupPane
|
| dropPosition | Gets/sets the current drop position when performing custom drag/drop. | IgcDockManagerPoint |
| layout | Gets/sets the layout configuration of the Dock Manager. | IgcDockManagerLayout |
| maximizedPane | Gets/sets the maximized pane. |
IgcContentPane | IgcSplitPane | IgcTabGroupPane
|
| resourceStrings | Gets/sets the resource strings. | IgcDockManagerResourceStrings |
| allowFloatingPanesResize | Determines whether the end user is allowed to resize floating panes. Defaults to true. | boolean |
| containedInBoundaries | Determines whether the floating panes are kept inside the Dock Manager boundaries. Defaults to false. | boolean |
| showHeaderIconOnHover | Determines which tab header icons should show when hovering over the tab with the mouse. Defaults to undefined. |
closeOnly | moreOptionsOnly | all
|
| showPaneHeaders | Determines whether pane headers are only shown on hover or always visible. Defaults to 'always'. |
onHoverOnly | always
|
| disableKeyboardNavigation | Disables the built-in keyboard shortcuts for pane navigation. Defaults to false. | boolean |
| allowInnerDock | Determines whether the end user is allowed to inner dock panes. Defaults to true. | boolean |
| proximityDock | Determines whether the end user can dock the dragged pane by dragging it close to the target pane edges. If enabled, docking indicators are not visible. Defaults to false. | boolean |
| Name | Description | Return type | Parameters |
|---|---|---|---|
| dropPane | Performs drop of the draggedPane into the specified dropPosition. Returns true if the pane has been docked otherwise returns false. |
Promise<boolean> |
|
| removePane | Removes a pane from the layout. | Promise<void> |
pane: IgcDockManagerPane
|
| focusPane | Focuses a pane from the layout. | Promise<void> |
contentId: string
|
| Name | Description | Cancelable | Type |
|---|---|---|---|
| splitterResizeStart | Raised when a splitter resizing starts | false | CustomEvent |
| splitterResizeEnd | Raised when a splitter resizing ends | false | CustomEvent |
| layoutChange | Raised when the layout updates | true | CustomEvent |
| paneHeaderConnected | Raised when a pane header element is connected | false | CustomEvent<IgcPaneHeaderConnectionEventArgs> |
| paneHeaderDisconnected | Raised when a pane header element is disconnected | false | CustomEvent<IgcPaneHeaderConnectionEventArgs> |
| tabHeaderConnected | Raised when a tab header element is connected | false | CustomEvent<IgcTabHeaderConnectionEventArgs> |
| tabHeaderDisconnected | Raised when a tab header element is disconnected | false | CustomEvent<IgcTabHeaderConnectionEventArgs> |
| paneClose | Raised when panes are about to close | true | CustomEvent<IgcPaneCloseEventArgs> |
| paneScroll | Raised when pane is scrolled. | true | CustomEvent<IgcPaneScrollEventArgs> |
| paneDragStart | Raised when a pane drag starts | true | CustomEvent<IgcPaneDragStartEventArgs> |
| paneDragOver | Raised when a pane is dragged over | true | CustomEvent<IgcPaneDragOverEventArgs> |
| paneDragEnd | Raised when a pane drag ends | false | CustomEvent<IgcPaneDragEndEventArgs> |
| panePinnedToggle | Raised when panes are about to get pinned/unpinned | true | CustomEvent<IgcPanePinnedEventArgs> |
| floatingPaneResizeEnd | Raised when a floating pane resize operation ends. | false | CustomEvent<IgcFloatingPaneResizeEventArgs> |
| floatingPaneResizeStart | Raised when a floating pane resizing operation starts. | true | CustomEvent<IgcFloatingPaneResizeEventArgs> |
| floatingPaneResizeMove | Raised when a floating pane resizing operation is in progress. | true | CustomEvent<IgcFloatingPaneResizeMoveEventArgs> |
| activePaneChanged | Raised when a pane is selected/activated | true | CustomEvent<IgcActivePaneEventArgs> |
| Name | Description |
|---|---|
| content-pane | The content pane component. |
| split-pane | The split pane component |
| floating-window | Indicates a floating pane |
| pane-header | The content pane header component |
| pane-header-content | The content area of the content pane header |
| pane-header-actions | The actions area of the content pane header |
| pane-header-close-button | The close button of a pane header |
| pane-header-maximize-button | The maximize button of a pane header |
| pane-header-minimize-button | The minimize button of a pane header |
| pane-header-pin-button | The pin button of a pane header |
| pane-header-unpin-button | The unpin button of a pane header |
| splitter | The resizing splitter component |
| splitter-base | The base element of the splitter component |
| splitter-ghost | The ghost element of the splitter component |
| splitter-handle | Indicates the custom splitter handle. |
| tab-panel | The tab panel component |
| tab-strip-area | The tab strip area containing the tab headers. |
| tab-strip-actions | The tab strip area containing the tab actions. |
| tabs-container | The container area of the tabs |
| tabs-content | The content area of the tabs |
| tabs-minimize-button | The minimize button of the tabs |
| tabs-maximize-button | The minimize button of the tabs |
| tabs-more-button | The more button of the tabs |
| context-menu | The context menu component |
| context-menu-item | An item in the context menu component |
| context-menu-content | The content section of the context menu component |
| context-menu-close-button | The close button in the context menu component |
| context-menu-unpin-button | The unpin button in the context menu component |
| docking-preview | The docking preview area |
| docking-indicator | The non-root docking indicator |
| root-docking-indicator | The root docking indicator |
| pane-navigator | The pane navigator component |
| pane-navigator-header | The header area of the pane navigator |
| pane-navigator-body | The body area of the pane navigator |
| pane-navigator-items-group | An items group in the pane navigator component |
| pane-navigator-items-group-title | The title element of an items group in the pane navigator |
| pane-navigator-item | An item in the pane navigator |
| tab-header | The tab header component |
| header-title | The header title area of a tab header. |
| tab-header-close-button | The close button of a tab header |
| tab-header-more-options-button | The more options button of a tab header |
| unpinned-pane-header | The unpinned pane header component |
| unpinned-tab-area | Indicates the unpinned tab area. |
| unpinned-tab-area--left | Indicates the unpinned tab area on the left. |
| unpinned-tab-area--right | Indicates the unpinned tab area on the right. |
| unpinned-tab-area--bottom | Indicates the unpinned tab area on the bottom. |
| unpinned-tab-area--horizontal | Indicates a horizontal unpinned tab area with top or bottom location. |
| unpinned-tab-area--hidden | Indicates an unpinned tab area without any panes. |
| single-floating | Applies to a single floating content-pane. |
| active | Indicates an active state. Applies to pane-header, pane-header-content, pane-header-actions, tab-header, unpinned-pane-header, tab-header-close-button, tab-header-more-options-button . |
| disabled | Indicates a disabled state. Applies to context-menu, pane-navigator, content-pane, pane-header, pane-header-content, pane-header-actions, unpinned-pane-header, tab-header, tab-panel, pane-navigator-item. |
| floating | Indicates a floating pane placement. Applies to pane-header, pane-header-content, pane-header-actions, tab-header-more-options. |
| window | Indicates a floating window placement. Applies to pane-header, pane-header-content, pane-header-actions. |
| selected | Indicates a selected state. Applies to tab-header, tab-header-close-button, pane-navigator-item, tab-panel
|
| document | Indicates a document host. Applies to tabs-content. |
| start | Indicates a position at start. Applies to unpinned-pane-header. |
| end | Indicates a position at end. Applies to unpinned-pane-header. |
| top | Indicates a top tabs position. Applies to tab-header, tab-strip-area, tab-strip-actions. |
| bottom | Indicates a bottom tabs position. Applies to tab-header, tab-strip-area, tab-strip-actions. |
| horizontal | Indicates a horizontal position. Applies to unpinned-pane-header, splitter-handle. |
| vertical | Indicates a vertical position. Applies to unpinned-pane-header, splitter-handle. |
| hovered | Indicates a hovered state. Applies to tab-header-close-button
|
| hover-preview-close | Indicates the close button shown on hover. Applies to tab-header. |
| hover-preview-options | Indicates the more options button shown on hover. Applies to tab-header. |
| Name | Description |
|---|---|
| pinButton | The pin button slot. |
| unpinButton | The unpin button slot. |
| maximizeButton | The maximize button slot. |
| minimizeButton | The minimize button slot. |
| moreOptionsButton | The more options button slot. |
| closeButton | The close button in pane and tab headers |
| moreTabsButton | The more tabs button slot in tabs component. |
| tabHeaderCloseButton | The close button slot of a tab header. |
| paneHeaderCloseButton | The close button slot of a pane header. |
| splitterHandle | The splitter handle slot. |
| Name | Description | Required | Type |
|---|---|---|---|
| rootPane | The root split pane of the layout. | true | IgcSplitPane |
| floatingPanes | The floating panes of the layout. | false | IgcSplitPane[] |
| Name | Description | Required | Type |
|---|---|---|---|
| id | The id of the pane. If not set the Dock Manager generates it automatically. | false | string |
| type | The type of the pane. | true | IgcDockManagerPaneType.contentPane |
| contentId | The slot attribute's value of the content element. | true | string |
| header | The text header of the content pane. | false | string |
| headerId | The slot attribute's value of the header element. If headerId is set, the header will be disregarded. | false | string |
| tabHeaderId | The slot attribute's value of the tab header element. If not set, the header property value is used. |
false | string |
| unpinnedHeaderId | The slot attribute's value of the unpinned header element. If not set, the header property value is used. |
false | string |
| floatingHeaderId | The slot attribute's value of the floating header element. If not set, the headerId property value is used. |
false | string |
| documentOnly | Marks that a content pane can be docked only inside a document host. Defaults to false . | false | boolean |
| size | The relative size of the pane. Defaults to 100. | false | number |
| isPinned | Describes whether a content pane is pinned or not. Defaults to true. | false | boolean |
| isMaximized | Determines whether a content pane is maximized or not. Defaults to false. | false | boolean |
| unpinnedSize | The absolute size of the pane in an unpinned state. Defaults to 200. | false | number |
| unpinnedLocation | If not set the Dock Manager automatically calculates it based on the location of the pane relatively to the document host. If more than one document host is presented, the closest one in the pane hierarchy will be used for the calculation. If there is no document host, the default location is left. | false | IgcUnpinnedLocation |
| allowClose | Specifies whether the end user is allowed to close the pane. Defaults to true. | false | boolean |
| allowPinning | Specifies whether the end user is allowed to pin/unpin the pane. Defaults to true. | false | boolean |
| allowDocking | Specifies whether the end user is allowed to dock the pane. Defaults to true. | false | boolean |
| allowFloating | Specifies whether the end user is allowed to make the pane floating. Defaults to true. | false | boolean |
| allowMaximize | Determines whether the end user is allowed to maximize the pane. Defaults to true. | false | boolean |
| acceptsInnerDock | Determines whether the end user can inner dock another pane in this one. Defaults to true. | false | boolean |
| hidden | Determines whether a pane is hidden in the UI. Defaults to false. | false | boolean |
| disabled | Determines whether a pane is disabled. Defaults to false. | false | boolean |
| Name | Description | Required | Type |
|---|---|---|---|
| id | The id of the pane. If not set the Dock Manager generates it automatically. | false | string |
| type | The type of the pane. | true | IgcDockManagerPaneType.splitPane |
| orientation | The slot attribute's value of the content element. | true | IgcSplitPaneOrientation |
| panes | The child panes of the split pane. | true | IgcDockManagerPane[] |
| size | The relative size of the pane. Defaults to 100. | false | number |
| floatingLocation | The absolute location point of the pane. Applies only for floating panes. | false | IgcDockManagerPoint |
| floatingWidth | The absolute width of the pane. Applies only for floating panes. Defaults to 100. | false | number |
| floatingHeight | The absolute height of the pane. Applies only for floating panes. Defaults to 100. | false | number |
| floatingResizable | Determines whether floating pane resizing is allowed. Applies only for floating panes. | false | boolean |
| allowEmpty | Determines whether the pane should present in the UI when empty. | false | boolean |
| isMaximized | Determines whether a split pane is maximized or not. Defaults to false. | false | boolean |
| Name | Description | Required | Type |
|---|---|---|---|
| id | The id of the pane. If not set the Dock Manager generates it automatically. | false | string |
| type | The type of the pane. | true | IgcDockManagerPaneType.tabGroupPane |
| panes | The child content panes of the tab group. | true | IgcDockManagerPane[] |
| size | The relative size of the pane. Defaults to 100. | false | number |
| selectedIndex | The index of the selected tab. | false | number |
| allowEmpty | Determines whether the pane should present in the UI when empty. | false | boolean |
| isMaximized | Determines whether a split pane is maximized or not. Defaults to false. | false | boolean |
| Name | Description | Required | Type |
|---|---|---|---|
| id | The id of the pane. If not set the Dock Manager generates it automatically. | false | string |
| type | The type of the pane. | true | IgcDockManagerPaneType.documentHost |
| rootPane | The root split pane of the document host. | true | IgcSplitPane |
| size | The relative size of the pane. Defaults to 100. | false | number |
| Name | Description | Required | Type |
|---|---|---|---|
| position | Gets the position of the docking indicator. | false | IgcDockingIndicatorPosition |
| isRoot | Gets a value indicating whether the docking indicator is a root one. | true | boolean |
| direction | Gets a value indicating the direction of the docking indicator. | true | string |
| Name | Description | Type |
|---|---|---|
| dragService | Gets/sets the drag service. | IgcDragService |
| Name | Required | Type |
|---|---|---|
| close | false | string |
| pin | false | string |
| unpin | false | string |
| maximize | false | string |
| minimize | false | string |
| panes | false | string |
| documents | false | string |
| moreTabs | false | string |
| moreOptions | false | string |
| Name | Description | Return type | Parameters |
|---|---|---|---|
| addResourceStrings | Adds custom resource strings. | language: string, resourceStrings: IgcDockManagerResourceStrings
|
A
| Key | Result |
|---|---|
| Shift + Arrow up | With multiple tabs in a tab group splits the view and docks the focused tab above |
| Cmd/Ctrl + Shift + Arrow up | Dock to global top |
| Shift + Arrow down | With multiple tabs in a tab group splits the view and docks the focused tab below |
| Cmd/Ctrl + Shift + Arrow down | Dock to global bottom |
| Shift + Arrow right | With multiple tabs in a tab group splits the view and docks the focused tab right |
| Cmd/Ctrl + Shift + Arrow right | Dock to global right |
| Shift + Arrow left | With multiple tabs in a tab group splits the view and docks the focused tab left |
| Cmd/Ctrl + Shift + Arrow left | Dock to global left |
| Alt + F3. | Closes document/tab |
| Cmd/Ctrl + F6 | Focus next tab in document host |
| Cmd/Ctrl + Arrow right | Focus next tab in document host |
| Cmd/Ctrl + Shift + F6 | Focus previous tab in document host |
| Cmd/Ctrl + Arrow left | Focus previous tab in document host |
| Alt + F6 | Focus next content pane |
| Alt + Shift + F6 | Focus previous content pane |
| Cmd/Ctrl + F7 | Show the navigator and iterate panes and documents starting from the first document forward |
| Cmd/Ctrl + F8 | Show the navigator and iterate panes and documents starting from the first document forward |
| Alt + F7 | Show the navigator and iterate panes and documents starting from the first pane forward |
| Alt + F8 | Show the navigator and iterate panes and documents starting from the first pane forward |
| Cmd/Ctrl + Shift + F7 | Show the navigator and iterate panes and documents starting from the last document backwards |
| Cmd/Ctrl + Shift + F8 | Show the navigator and iterate panes and documents starting from the last document backwards |
| Alt + Shift + F7 | Show the navigator and iterate panes and documents starting from the last pane backwards |
| Alt + Shift + F8 | Show the navigator and iterate panes and documents starting from the last pane backwards |
A
A
A
- S
- S
- S
- A
- S
- S