Improved documentation, made a lot of member functions protected to make it clearer which functions the user is allowed to use, the CDockWidget constructor now sets the objectName() to the given title, so there is no need to call setObjectName() explicitely if the title is static and unique

Author: Uwe Kindler

demo/MainWindow.cpp

@@ -83,7 +83,6 @@ static ads::CDockWidget* createLongTextLabelDockWidget(QMenu* ViewMenu)
 
 	ads::CDockWidget* DockWidget = new ads::CDockWidget(QString("Label %1").arg(LabelCount++));
 	DockWidget->setWidget(l);
-	DockWidget->setObjectName(DockWidget->windowTitle());
 	ViewMenu->addAction(DockWidget->toggleViewAction());
 	return DockWidget;
 }
@@ -96,7 +95,6 @@ static ads::CDockWidget* createCalendarDockWidget(QMenu* ViewMenu)
 	QCalendarWidget* w = new QCalendarWidget();
 	ads::CDockWidget* DockWidget = new ads::CDockWidget(QString("Calendar %1").arg(CalendarCount++));
 	DockWidget->setWidget(w);
-	DockWidget->setObjectName(DockWidget->windowTitle());
 	DockWidget->setToggleViewActionMode(ads::CDockWidget::ActionModeShow);
 	ViewMenu->addAction(DockWidget->toggleViewAction());
 	return DockWidget;
@@ -114,7 +112,6 @@ static ads::CDockWidget* createFileSystemTreeDockWidget(QMenu* ViewMenu)
 	w->setModel(m);
 	ads::CDockWidget* DockWidget = new ads::CDockWidget(QString("Filesystem %1").arg(FileSystemCount++));
 	DockWidget->setWidget(w);
-	DockWidget->setObjectName(DockWidget->windowTitle());
 	ViewMenu->addAction(DockWidget->toggleViewAction());
     return DockWidget;
 }
@@ -178,6 +175,7 @@ void MainWindowPrivate::createContent()
 	DockManager->addDockWidget(ads::LeftDockWidgetArea, DockWidget);
 	DockManager->addDockWidget(ads::LeftDockWidgetArea, createLongTextLabelDockWidget(ViewMenu));
 	DockManager->addDockWidget(ads::BottomDockWidgetArea, createFileSystemTreeDockWidget(ViewMenu));
+
 	auto FileSystemWidget = createFileSystemTreeDockWidget(ViewMenu);
 	FileSystemWidget->setFeature(ads::CDockWidget::DockWidgetMovable, false);
 	auto TopDockArea = DockManager->addDockWidget(ads::TopDockWidgetArea, FileSystemWidget);

src/DockAreaWidget.h

@@ -41,6 +41,7 @@ namespace ads
 struct DockAreaWidgetPrivate;
 class CDockManager;
 class CDockContainerWidget;
+struct DockContainerWidgetPrivate;
 class CDockWidget;
 
 
@@ -55,12 +56,48 @@ class ADS_EXPORT CDockAreaWidget : public QFrame
 private:
 	DockAreaWidgetPrivate* d; ///< private data (pimpl)
 	friend struct DockAreaWidgetPrivate;
+	friend class CDockContainerWidget;
+	friend class DockContainerWidgetPrivate;
+	friend class CDockWidgetTab;
 
 private slots:
 	void onDockWidgetTitleClicked();
 	void onTabsMenuActionTriggered(QAction* Action);
 	void onCloseButtonClicked();
 
+protected:
+	/**
+	 * Inserts a dock widget into dock area.
+	 * All dockwidgets in the dock area tabified in a stacked layout with tabs.
+	 * The index indicates the index of the new dockwidget in the tabbar and
+	 * in the stacked layout. If the Activate parameter is true, the new
+	 * DockWidget will be the active one in the stacked layout
+	 */
+	void insertDockWidget(int index, CDockWidget* DockWidget, bool Activate = true);
+
+	/**
+	 * Add a new dock widget to dock area.
+	 * All dockwidgets in the dock area tabified in a stacked layout with tabs
+	 */
+	void addDockWidget(CDockWidget* DockWidget);
+
+	/**
+	 * Removes the given dock widget from the dock area
+	 */
+	void removeDockWidget(CDockWidget* DockWidget);
+
+	/**
+	 * Returns the index of contents of the title widget that is located at
+	 * mouse position pos
+	 */
+	int indexOfContentByTitlePos(const QPoint& pos, QWidget* exclude = nullptr) const;
+
+	/**
+	 * Reorder the index position of DockWidget at fromIndx to toIndex.
+	 */
+	void reorderDockWidget(int fromIndex, int toIndex);
+
+
 public:
 	/**
 	 * Default Constructor
@@ -83,26 +120,6 @@ private slots:
 	 */
 	CDockContainerWidget* dockContainer() const;
 
-	/**
-	 * Inserts a dock widget into dock area.
-	 * All dockwidgets in the dock area tabified in a stacked layout with tabs.
-	 * The index indicates the index of the new dockwidget in the tabbar and
-	 * in the stacked layout. If the Activate parameter is true, the new
-	 * DockWidget will be the active one in the stacked layout
-	 */
-	void insertDockWidget(int index, CDockWidget* DockWidget, bool Activate = true);
-
-	/**
-	 * Add a new dock widget to dock area.
-	 * All dockwidgets in the dock area tabified in a stacked layout with tabs
-	 */
-	void addDockWidget(CDockWidget* DockWidget);
-
-	/**
-	 * Removes the given dock widget from the dock area
-	 */
-	void removeDockWidget(CDockWidget* DockWidget);
-
 	/**
 	 * Returns the rectangle of the title area
 	 */
@@ -118,12 +135,6 @@ private slots:
 	 */
 	int tabIndex(CDockWidget* DockWidget);
 
-	/**
-	 * Returns the index of contents of the title widget that is located at
-	 * mouse position pos
-	 */
-	int indexOfContentByTitlePos(const QPoint& pos, QWidget* exclude = nullptr) const;
-
 	/**
 	 * Returns a list of all dock widgets in this dock area.
 	 * This list contains open and closed dock widgets.
@@ -145,11 +156,6 @@ private slots:
 	 */
 	CDockWidget* dockWidget(int Index) const;
 
-	/**
-	 * Reorder the index position of DockWidget at fromIndx to toIndex.
-	 */
-	void reorderDockWidget(int fromIndex, int toIndex);
-
 	/**
 	 * Returns the index of the current active dock widget
 	 */
@@ -161,7 +167,7 @@ private slots:
 	CDockWidget* currentDockWidget() const;
 
 	/**
-	 * Shows the tab with tghe given dock widget
+	 * Shows the tab with the given dock widget
 	 */
 	void setCurrentDockWidget(CDockWidget* DockWidget);
 

src/DockContainerWidget.h

@@ -44,7 +44,9 @@ struct DockContainerWidgetPrivate;
 class CDockAreaWidget;
 class CDockWidget;
 class CDockManager;
+struct DockManagerPrivate;
 class CFloatingDockContainer;
+struct FloatingDockContainerPrivate;
 
 /**
  * Container that manages a number of dock areas with single dock widgets
@@ -56,6 +58,11 @@ class ADS_EXPORT CDockContainerWidget : public QFrame
 private:
 	DockContainerWidgetPrivate* d; ///< private data (pimpl)
 	friend struct DockContainerWidgetPrivate;
+	friend class CDockManager;
+	friend struct DockManagerPrivate;
+	friend class CDockAreaWidget;
+	friend class CFloatingDockContainer;
+	friend struct FloatingDockContainerPrivate;
 
 protected:
 	/**
@@ -68,6 +75,34 @@ class ADS_EXPORT CDockContainerWidget : public QFrame
 	 */
 	QSplitter* rootSplitter() const;
 
+	/**
+	 * Drop floating widget into the container
+	 */
+	void dropFloatingWidget(CFloatingDockContainer* FloatingWidget, const QPoint& TargetPos);
+
+	/**
+	 * Adds the given dock area to this container widget
+	 */
+	void addDockArea(CDockAreaWidget* DockAreaWidget, DockWidgetArea area = CenterDockWidgetArea);
+
+	/**
+	 * Removes the given dock area from this container
+	 */
+	void removeDockArea(CDockAreaWidget* area);
+
+	/**
+	 * Saves the state into the given stream
+	 */
+	void saveState(QXmlStreamWriter& Stream) const;
+
+	/**
+	 * Restores the state from given stream.
+	 * If Testing is true, the function only parses the data from the given
+	 * stream but does not restore anything. You can use this check for
+	 * faulty files before you start restoring the state
+	 */
+	bool restoreState(QXmlStreamReader& Stream, bool Testing);
+
 public:
 	/**
 	 * Default Constructor
@@ -79,11 +114,6 @@ class ADS_EXPORT CDockContainerWidget : public QFrame
 	 */
 	virtual ~CDockContainerWidget();
 
-	/**
-	 * Drop floating widget into the container
-	 */
-	void dropFloatingWidget(CFloatingDockContainer* FloatingWidget, const QPoint& TargetPos);
-
 	/**
 	 * Adds dockwidget into the given area.
 	 * If DockAreaWidget is not null, then the area parameter indicates the area
@@ -94,16 +124,6 @@ class ADS_EXPORT CDockContainerWidget : public QFrame
 	CDockAreaWidget* addDockWidget(DockWidgetArea area, CDockWidget* Dockwidget,
 		CDockAreaWidget* DockAreaWidget = nullptr);
 
-	/**
-	 * Adds the given dock area to this container widget
-	 */
-	void addDockArea(CDockAreaWidget* DockAreaWidget, DockWidgetArea area = CenterDockWidgetArea);
-
-	/**
-	 * Removes the given dock area from this container
-	 */
-	void removeDockArea(CDockAreaWidget* area);
-
 	/**
 	 * Returns the current zOrderIndex
 	 */
@@ -148,19 +168,6 @@ class ADS_EXPORT CDockContainerWidget : public QFrame
 	 */
 	bool isFloating() const;
 
-	/**
-	 * Saves the state into the given stream
-	 */
-	void saveState(QXmlStreamWriter& Stream) const;
-
-	/**
-	 * Restores the state from given stream.
-	 * If Testing is true, the function only parses the data from the given
-	 * stream but does not restore anything. You can use this check for
-	 * faulty files before you start restoring the state
-	 */
-	bool restoreState(QXmlStreamReader& Stream, bool Testing);
-
 	/**
 	 * Dumps the layout for debugging purposes
 	 */

src/DockManager.h

@@ -40,8 +40,13 @@ namespace ads
 {
 struct DockManagerPrivate;
 class CFloatingDockContainer;
+struct FloatingDockContainerPrivate;
 class CDockContainerWidget;
 class CDockOverlay;
+class CDockAreaTabBar;
+class CDockWidgetTab;
+struct DockWidgetTabPrivate;
+struct DockAreaWidgetPrivate;
 
 /**
  * The central dock manager that maintains the complete docking system
@@ -52,23 +57,15 @@ class ADS_EXPORT CDockManager : public CDockContainerWidget
 private:
 	DockManagerPrivate* d; ///< private data (pimpl)
 	friend struct DockManagerPrivate;
+	friend class CFloatingDockContainer;
+	friend struct FloatingDockContainerPrivate;
+	friend class CDockContainerWidget;
+	friend class CDockAreaTabBar;
+	friend class CDockWidgetTab;
+	friend struct DockAreaWidgetPrivate;
+	friend struct DockWidgetTabPrivate;
 
 protected:
-
-
-public:
-	/**
-	 * Default Constructor.
-	 * If the given parent is a QMainWindow, the dock manager sets itself as the
-	 * central widget
-	 */
-	CDockManager(QWidget* parent = 0);
-
-	/**
-	 * Virtual Destructor
-	 */
-	virtual ~CDockManager();
-
 	/**
 	 * Registers the given floating widget in the internal list of
 	 * floating widgets
@@ -102,11 +99,30 @@ class ADS_EXPORT CDockManager : public CDockContainerWidget
 	 */
 	CDockOverlay* dockAreaOverlay() const;
 
+public:
+	/**
+	 * Default Constructor.
+	 * If the given parent is a QMainWindow, the dock manager sets itself as the
+	 * central widget
+	 */
+	CDockManager(QWidget* parent = 0);
+
+	/**
+	 * Virtual Destructor
+	 */
+	virtual ~CDockManager();
+
 	/**
 	 * Adds dockwidget into the given area.
 	 * If DockAreaWidget is not null, then the area parameter indicates the area
 	 * into the DockAreaWidget. If DockAreaWidget is null, the Dockwidget will
-	 * be dropped into the container.
+	 * be dropped into the container. If you would like to add a dock widget
+	 * tabified, then you need to add it to an existing dock area object
+	 * into the CenterDockWidgetArea. The following code shows this:
+	 * \code
+	 * DockManager->addDockWidget(ads::CenterDockWidgetArea, NewDockWidget,
+	 * 	   ExisitingDockArea);
+	 * \endcode
 	 * \return Returns the dock area widget that contains the new DockWidget
 	 */
 	CDockAreaWidget* addDockWidget(DockWidgetArea area, CDockWidget* Dockwidget,

src/DockWidget.cpp

@@ -211,6 +211,7 @@ CDockWidget::CDockWidget(const QString &title, QWidget *parent) :
 	d->Layout->setSpacing(0);
 	setLayout(d->Layout);
 	setWindowTitle(title);
+	setObjectName(title);
 
 	d->TitleWidget = new CDockWidgetTab(this);
 	d->ToggleViewAction = new QAction(title);

src/DockWidget.h

@@ -132,7 +132,16 @@ class ADS_EXPORT CDockWidget : public QFrame
 	};
 
 	/**
-	 * Default Constructor
+	 * This constructor creates a dock widget with the given title.
+	 * The title is the text that is shown in the window title when the dock
+	 * widget is floating and it is the title that is shown in the titlebar
+	 * or the tab of this dock widget if it is tabified.
+	 * The object name of the dock widget is also set to the title. The
+	 * object name is required by the dock manager to properly save and restore
+	 * the state of the dock widget. That means, the title needs to be unique.
+	 * If your title is not unique or if you would like to change the title
+	 * during runtime, you need to set a unique object name explicitely
+	 * by calling setObjectName() after construction.
 	 */
 	CDockWidget(const QString &title, QWidget* parent = 0);
 
@@ -216,11 +225,6 @@ class ADS_EXPORT CDockWidget : public QFrame
 	 */
 	void setToggleViewActionMode(eToggleViewActionMode Mode);
 
-	/**
-	 * Emits titleChanged signal if title change event occurs
-	 */
-	virtual bool event(QEvent *e) override;
-
 	/**
 	 * Sets the dock widget icon that is shown in tabs and in toggle view
 	 * actions
@@ -232,6 +236,13 @@ class ADS_EXPORT CDockWidget : public QFrame
 	 */
 	QIcon icon() const;
 
+
+public: // reimplements QFrame -----------------------------------------------
+	/**
+	 * Emits titleChanged signal if title change event occurs
+	 */
+	virtual bool event(QEvent *e) override;
+
 public slots:
 	/**
 	 * This property controls whether the dock widget is open or closed.

src/DockWidgetTab.cpp

@@ -138,6 +138,7 @@ void DockWidgetTabPrivate::createLayout()
 	l->addWidget(IconLabel, Qt::AlignVCenter);
 
 	TitleLabel = new QLabel();
+	TitleLabel->setObjectName("dockWidgetTabLabel");
 	l->addWidget(TitleLabel, 1);
 
 	IconLabel->setVisible(false);