Added documentation for Auto-Hide feature

githubuser0xFFFF · githubuser0xFFFF · commit 00738704807a · 2022-11-07T14:36:19.000+01:00
diff --git a/demo/MainWindow.cpp b/demo/MainWindow.cpp
@@ -222,6 +222,7 @@ struct MainWindowPrivate
 		ads::CDockWidget* DockWidget = new ads::CDockWidget(QString("Filesystem %1")
 			.arg(FileSystemCount++));
 		DockWidget->setWidget(w);
+		DockWidget->setIcon(svgIcon(":/adsdemo/images/folder_open.svg"));
 		ui.menuView->addAction(DockWidget->toggleViewAction());
 		// We disable focus to test focus highlighting if the dock widget content
 		// does not support focus
@@ -282,6 +283,7 @@ struct MainWindowPrivate
 
 		ads::CDockWidget* DockWidget = new ads::CDockWidget(QString("Label %1").arg(LabelCount++));
 		DockWidget->setWidget(l);
+		DockWidget->setIcon(svgIcon(":/adsdemo/images/font_download.svg"));
 		ui.menuView->addAction(DockWidget->toggleViewAction());
 		return DockWidget;
 	}
@@ -341,6 +343,7 @@ struct MainWindowPrivate
 		auto Result = w->loadFile(FileName);
 		qDebug() << "loadFile result: " << Result;
 		ads::CDockWidget* DockWidget = new ads::CDockWidget(QString("Image Viewer %1").arg(ImageViewerCount++));
+		DockWidget->setIcon(svgIcon(":/adsdemo/images/photo.svg"));
 		DockWidget->setWidget(w,ads:: CDockWidget::ForceNoScrollArea);
 		auto ToolBar = DockWidget->createDefaultToolBar();
 		ToolBar->addActions(w->actions());
diff --git a/demo/demo.pro b/demo/demo.pro
@@ -15,6 +15,7 @@ lessThan(QT_MAJOR_VERSION, 6) {
 CONFIG += c++14
 CONFIG += debug_and_release
 DEFINES += QT_DEPRECATED_WARNINGS
+RC_FILE += app.rc
 
 adsBuildStatic {
     DEFINES += ADS_STATIC
diff --git a/demo/demo.qrc b/demo/demo.qrc
@@ -33,5 +33,7 @@
         <file>images/photo.svg</file>
         <file>images/crop_original.svg</file>
         <file>images/panorama.svg</file>
+        <file>images/ads_icon2.svg</file>
+        <file>images/font_download.svg</file>
     </qresource>
 </RCC>
diff --git a/demo/images/ads_icon2.svg b/demo/images/ads_icon2.svg
@@ -1,13 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1024" height="1024" version="1.1" viewBox="0 0 1024 1024" xmlns="http://www.w3.org/2000/svg">
  <desc>electric_iron icon - Licensed under Iconfu Standard License v1.0 (https://www.iconfu.com/iconfu_standard_license) - Incors GmbH</desc>
- <g>
-  <text x="1251.1022" y="1305.4956" fill="#000000" font-family="sans-serif" font-size="40px" style="line-height:1.25" xml:space="preserve"><tspan x="1251.1022" y="1305.4956"/></text>
-  <g>
-   <path d="m405.33 234.66v256h469.33v-256z" fill="#009ddd" style="mix-blend-mode:normal"/>
-   <path d="m661.33 533.33v256h213.33v-256z" fill="#ff9833" style="mix-blend-mode:normal"/>
-   <path d="m405.33 533.33v256h213.33v-256z" fill="#accb01" style="mix-blend-mode:normal"/>
-   <path d="m149.33 234.66v554.67h213.33v-554.67z" fill="#0083c3" style="mix-blend-mode:normal"/>
-  </g>
+ <g transform="matrix(1.4118 0 0 1.4118 -210.82 -210.82)" stroke-width=".50173">
+  <text x="1251.1022" y="1305.4956" fill="#000000" font-family="sans-serif" font-size="40px" style="line-height:1.25" xml:space="preserve"><tspan x="1251.1022" y="1305.4956" stroke-width=".70833"/></text>
+  <path d="m405.33 234.66v256h469.33v-256z" fill="#009ddd" style="mix-blend-mode:normal"/>
+  <path d="m661.33 533.33v256h213.33v-256z" fill="#ff9833" style="mix-blend-mode:normal"/>
+  <path d="m405.33 533.33v256h213.33v-256z" fill="#accb01" style="mix-blend-mode:normal"/>
+  <path d="m149.33 234.66v554.67h213.33v-554.67z" fill="#0083c3" style="mix-blend-mode:normal"/>
  </g>
 </svg>
diff --git a/demo/images/font_download.svg b/demo/images/font_download.svg
@@ -0,0 +1,6 @@
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0,0,1024,1024">
+	<desc>font_download icon - Licensed under Apache License v2.0 (http://www.apache.org/licenses/LICENSE-2.0) - Created with Iconfu.com - Derivative work of Material icons (Copyright Google Inc.)</desc>
+	<g fill="#03b8e5" fill-rule="nonzero" style="mix-blend-mode: normal">
+		<path d="M938.67,170.67v682.66c0,46.93 -38.41,85.34 -85.34,85.34h-682.66c-46.93,0 -85.34,-38.41 -85.34,-85.34v-682.66c0,-46.93 38.41,-85.34 85.34,-85.34h682.66c46.93,0 85.34,38.41 85.34,85.34zM769.71,789.33l-218.03,-554.66h-79.36l-218.03,554.66h89.18l47.78,-128h240.64l48.64,128zM512,340.48l88.32,235.52h-176.64z"/>
+	</g>
+</svg>
diff --git a/demo/main.cpp b/demo/main.cpp
@@ -45,6 +45,7 @@ int main(int argc, char *argv[])
 	QApplication a(argc, argv);
 	a.setApplicationName("Advanced Docking System Demo");
 	a.setQuitOnLastWindowClosed(true);
+	a.setWindowIcon(QIcon(":/adsdemo/images/ads_icon2.svg"));
 
 	qInstallMessageHandler(myMessageOutput);
 	qDebug() << "Message handler test";
diff --git a/doc/AutoHide_PinTo.png b/doc/AutoHide_PinTo.png
diff --git a/doc/cfg_flag_AutoHideSideBarsIconOnly_false.png b/doc/cfg_flag_AutoHideSideBarsIconOnly_false.png
diff --git a/doc/cfg_flag_AutoHideSideBarsIconOnly_true.png b/doc/cfg_flag_AutoHideSideBarsIconOnly_true.png
diff --git a/doc/cfg_flag_DockAreaHasAutoHideButton.png b/doc/cfg_flag_DockAreaHasAutoHideButton.png
diff --git a/doc/user-guide.md b/doc/user-guide.md
@@ -28,6 +28,14 @@
   - [`FloatingContainerForceNativeTitleBar` (Linux only)](#floatingcontainerforcenativetitlebar-linux-only)
   - [`FloatingContainerForceQWidgetTitleBar` (Linux only)](#floatingcontainerforceqwidgettitlebar-linux-only)
   - [`MiddleMouseButtonClosesTab`](#middlemousebuttonclosestab)
+- [Auto-Hide Configuration Flags](#auto-hide-configuration-flags)
+  - [Setting Auto-Hide Flags](#setting-auto-hide-flags)
+  - [`AutoHideFeatureEnabled`](#autohidefeatureenabled)
+  - [`DockAreaHasAutoHideButton`](#dockareahasautohidebutton)
+  - [`AutoHideButtonTogglesArea`](#autohidebuttontogglesarea)
+  - [`AutoHideButtonCheckable`](#autohidebuttoncheckable)
+  - [`AutoHideSideBarsIconOnly`](#autohidesidebarsicononly)
+  - [`AutoHideShowOnMouseOver`](#autohideshowonmouseover)
 - [DockWidget Feature Flags](#dockwidget-feature-flags)
   - [`DockWidgetClosable`](#dockwidgetclosable)
   - [`DockWidgetMovable`](#dockwidgetmovable)
@@ -41,7 +49,10 @@
 - [Central Widget](#central-widget)
 - [Empty Dock Area](#empty-dock-area)
 - [Custom Close Handling](#custom-close-handling)
-- ['Auto Hide Dock Widgets'](#auto-hide-dock-widgets)
+- [Auto Hide Dock Widgets](#auto-hide-dock-widgets)
+  - [Pinning Auto-Hide Widgets to a certain border](#pinning-auto-hide-widgets-to-a-certain-border)
+  - [Show / Hide Auto-Hide Widgets via Mouse Over](#show--hide-auto-hide-widgets-via-mouse-over)
+  - [Adding Auto Hide Widgets](#adding-auto-hide-widgets)
 - [Styling](#styling)
   - [Disabling the Internal Style Sheet](#disabling-the-internal-style-sheet)
 
@@ -487,6 +498,85 @@ possible in various web browsers.
 
 ![MiddleMouseButtonClosesTab true](cfg_flag_MiddleMouseButtonClosesTab.gif)
 
+## Auto-Hide Configuration Flags
+
+The Advanced Docking System has a number of global configuration options to
+configure the Auto-Hide functionality. The "Auto Hide" feature allows to display
+more information using less screen space by hiding or showing windows pinned to
+one of the four dock container borders.
+
+### Setting Auto-Hide Flags
+
+You should set the Auto-Hide flags before creating the dock manager
+instance. That means, you should set the Auto-Hide flags after setting the
+configuration flags.
+
+```c++
+CDockManager::setConfigFlag(CDockManager::FocusHighlighting, true);
+CDockManager::setAutoHideConfigFlags(CDockManager::DefaultAutoHideConfig);
+CDockManager::setAutoHideConfigFlag(CDockManager::AutoHideShowOnMouseOver, true);
+...
+d->DockManager = new CDockManager(this);
+```
+
+If you set the Auto-Hide flags, you can set individual flags using the
+function `CDockManager::setAutoHideConfigFlag` or you can set all flags using
+the function `CDockManager::setAutoHideConfigFlags`. Instead of settings all
+flags individually, it is better to pick a predefined set of configuration
+flags and then modify individual flags. The following predefined
+configurations are available
+
+- `DefaultAutoHideConfig` - default auto hide config
+
+Pick one of those predefined configurations and then modify the following
+configurations flags to adjust the docking system to your needs.
+
+### `AutoHideFeatureEnabled`
+
+Enables / disables the Auto-Hide functionality. Only if this flag is enabled,
+the other Auto-Hide flags will be evaluated.
+
+### `DockAreaHasAutoHideButton`
+
+If this flag is set (default), then each dock area has a pin button in the title 
+bar to toggle Auto-Hide state.
+
+![DockAreaHasAutoHideButton true](cfg_flag_DockAreaHasAutoHideButton.png)
+
+### `AutoHideButtonTogglesArea`
+
+If set, the the pin button in the dock area title bar toggles the complete area.
+If not set (default), then the pin button toggles the current active tab / dock
+widget and pressing the **Ctrl** key while clicking the pin button toggles the
+complete ara.
+
+### `AutoHideButtonCheckable`
+
+Normally the pin button in the dock area title bar is not checkable. If this
+flag is set, then the button is checkable. That means, if button is checked,
+the dock widget is pinned.
+
+### `AutoHideSideBarsIconOnly`
+
+Normally the Auto-Hide tabs show the icon and title of the dock widget:
+
+![AutoHideSideBarsIconOnly false](cfg_flag_AutoHideSideBarsIconOnly_false.png)
+
+You can set this flag, if you would like to have only icons in the Auto-Hide
+tabs instead of icon and dock widget title. If this is set, the Auto-Hide tab
+needs less space. The tooltip of each tab still shows the dock widget title.
+
+![AutoHideSideBarsIconOnly true](cfg_flag_AutoHideSideBarsIconOnly_true.png)
+
+### `AutoHideShowOnMouseOver`
+
+Normally Auto-Hide widgets are shown by clicking the Auto-Hide tab and
+hidden by clicking the Auto-Hide tab again or by clicking into any other
+dock widget in the same container. If this flag is set, the Auto-Hide widget
+is shown, if the user hovers over the Auto-Hide tab or if the users moves the
+mouse outside of the Auto-Hide widget. Showing and hiding my mouse click still
+works if this feature is enabled.
+
 ## DockWidget Feature Flags
 
 ### `DockWidgetClosable`
@@ -613,51 +703,48 @@ When an entire area is closed, the default behavior is to hide the dock widgets
 
 ## Auto Hide Dock Widgets
 
-Enabling this feature adds a pin icon to each dock area that will pin the dock widgets in the area to the left, right or bottom edge of the window as a side tab. The dock widget is then normally hidden, but showing the view by clicking the tab would overlay the dock widget on top of all the other widgets.
+The Advanced Docking System supports "Auto-Hide" functionality for **all** dock containers. The "Auto Hide" feature allows to display more information using less screen space by hiding or showing windows pinned to one of the four dock container borders.
 
-![Auto hide demo](autohide-feature-demo.png)
+Enabling this feature adds a button with a pin icon to each dock area.
 
-The area dock widgets are added to are based on the distance to the left, right and bottom edge.
+![DockAreaHasAutoHideButton true](cfg_flag_DockAreaHasAutoHideButton.png)
 
-Note: Overlay, Pin, and Auto Hide here all refer to the same functionality.
+By clicking this button, the current dock widget (or the complete area - depending on the
+configuration flags) will be pinned to a certain border. The border is choosen
+depending on the location of the dock area. If you click the pin button while
+holding down the **Ctrl** key, the whole dock area will be pinned to a certain
+border.
 
-### Setting Configuration Flags
+### Pinning Auto-Hide Widgets to a certain border
 
-Setting and enabling the overlay feature is similar to setting config flags, but do be aware that it uses a different eOverlayFlag enum and not the eConfigFlag enum. This is only relevant if you call `CDockManager::setConfigFlags` for the `ConfigFlags`, as it would mean you have to call `CDockManager::setConfigFlags` a second time for the `AutoHideFlags`.
+If you would like to pin a dock widget or a dock area to a certain border,
+then you can right-click into the dock widget tab or into the dock area title bar
+to show the context menu. Then you can select the location via the **Pin to** menu:
 
-```c++
-CDockManager::setConfigFlags(CDockManager::DefaultAutoHideConfig);
-CDockManager::setConfigFlag(CDockManager::LeftSideBarPrioritizeIconOnly, true);
-...
-d->DockManager = new CDockManager(this);
-```
+![Pin to](AutoHide_PinTo.png)
+
+### Show / Hide Auto-Hide Widgets via Mouse Over
+
+Normally Auto-Hide widgets are shown by clicking the Auto-Hide tab and hidden by
+clicking the Auto-Hide tab again or by clicking into any other dock widget in
+the same container. If the Auto-Hide config flag `AutoHideShowOnMouseOver` is set,
+the Auto-Hide widget is shown, if the user hovers over the Auto-Hide tab and is
+collapsed if the mouse cursor leaves the Auto-Hide widget. Showing and hiding
+my mouse click still works if this feature is enabled.
 
 ### Adding Auto Hide Widgets
 
-Adding an auto hide widget is similar to adding a dock widget, simply call `dockManager->addAutoHideDockWidget`. 
+Adding an auto hide widget is similar to adding a dock widget, simply call
+`dockManager->addAutoHideDockWidget()`.
 
 ```c++
+CDockManager::setAutoHideConfigFlags(CDockManager::DefaultAutoHideConfig);
 d->DockManager = new CDockManager(this);
 CDockWidget* TableDockWidget = new CDockWidget("Table 1");
-TableDockWidget->setDefaultOverlayDockProportion(0.5); // Default size in proportion to the window size when adding the overlay widget
-DockManager->addOverlayDockWidget(CDockWidgetSideTab::SideTabBarArea::LeftTop, TableDockWidget, CDockWidget::Last);
+DockManager->addAutoHideDockWidget(SideBarLeft, TableDockWidget);
 ```
 
-See `autohide` example to learn how it works.
-
-### Configuration Flags For Auto Hide Widgets
-
-- `DockContainerHasTopSideBar`,`DockContainerHasLeftSideBar`, `DockContainerHasRightSideBar`, `DockContainerHasBottomSideBar` -> Enabling each of these enables the side bar at each location. Disabling any of them would mean that the widget cannot be added at that location, so it would be added at the next available location. E.g. If you only enable `DockContainerHasRightSideBar` and `DockContainerHasBottomSideBar` then it will be added to the bottom side bar or right side bar respectively. If none of these are enabled, the auto hide button will not be added, as at least one of them must be enabled to work.
-- `DockAreaHasAutoHideButton` -> Adds the auto hide button to the title bar of the dock area
-- `TopSideBarPrioritizeIconOnly`, `LeftSideBarPrioritizeIconOnly`, `RightSideBarPrioritizeIconOnly`, `BottomSideBarPrioritizeIconOnly` -> If this is set, the side bar this is enabled with will prioritize showing an icon only, as opposed to an icon and text. This is set per side bar, so if you only enable `LeftSideBarPrioritizeIconOnly`, the right and bottom side bars will still show the icon and the text. This is only relevant if an icon is set, otherwise it will only show text as usual.
-- `AutoHideDockAreaHasTitle` -> Adds the title of the dock window where the title bar would be. 
-- `DefaultAutoHideConfig` -> Enables `DockContainerHasTopSideBar`, `DockContainerHasLeftSideBar`, `DockContainerHasRightSideBar`, `DockContainerHasBottomSideBar`, `DockAreaHasAutoHideButton`, `AutoHideDockAreaHasTitle`
-
-### Limitations
-
-- Currently the `LeftBottom` and `RightBottom` areas can only be added programatically, and not through the pin icon. These are used if you'd like to add a new dock widget separated from the normal dock areas.
-
-- Adding a `DockWidget` (e.g. via `addDockWidget`) to an `DockArea` in an Auto Hide Widget that already has a dockwidget is undefined behavior. An overlayed dock area does not have tabs and does not support more than one `DockWidget` in it's area. If you want to add a `DockWidget` to a `DockArea` that *could* be in an auto hidden widget, check first if it's auto hidden via `CDockArea::isAutoHide` and handle it accordingly (typically by adding the overlay dock widget as a side tab instead of to the area).  
+See `autohide` example or the demo application to learn how it works.
 
 ## Styling
 
diff --git a/src/DockManager.h b/src/DockManager.h
@@ -340,18 +340,18 @@ class ADS_EXPORT CDockManager : public CDockContainerWidget
 		CDockContainerWidget* DockContainerWidget);
 
 	/**
-	 * Adds a dock widget overlayed into the dock manager container based on the side tab bar area.
-	 * An overlay widget is used for auto hide functionality
+	 * Adds an Auto-Hide widget to the dock manager container pinned to
+	 * the given side bar location.
 	 * \return Returns the CAutoHideDockContainer that contains the new DockWidget
 	 */
-	CAutoHideDockContainer* addAutoHideDockWidget(SideBarLocation area, CDockWidget* Dockwidget);
+	CAutoHideDockContainer* addAutoHideDockWidget(SideBarLocation Location, CDockWidget* Dockwidget);
 
 	/**
-	 * Adds dock widget overlayed into the given container based on the CDockWidgetSideTab::SideTabBarArea.
-	 * An overlay widget is used for auto hide functionality
+	 * Adds an Auto-Hide widget to the given DockContainerWidget pinned to
+	 * the given side bar location in this container.
 	 * \return Returns the CAutoHideDockContainer that contains the new DockWidget
 	 */
-	CAutoHideDockContainer* addAutoHideDockWidgetToContainer(SideBarLocation area,
+	CAutoHideDockContainer* addAutoHideDockWidgetToContainer(SideBarLocation Location,
 		CDockWidget* Dockwidget, CDockContainerWidget* DockContainerWidget);
 
 	/**
