Improved source code documentation, removed empty main.qrc to silence qmake warning

Author: githubuser0xFFFF

demo/demo.pro

@@ -21,7 +21,6 @@ HEADERS += \
 FORMS += \
 	mainwindow.ui
 
-RESOURCES += main.qrc
 
 LIBS += -L$${ADS_OUT_ROOT}/lib
 

demo/main.qrc

@@ -44,6 +44,10 @@ class CFloatingDockContainer;
  * Custom tabbar implementation for tab area that is shown on top of a
  * dock area widget.
  * The tabbar displays the tab widgets of the contained dock widgets.
+ * We cannot use QTabBar here because it does a lot of fancy animations
+ * that will crash the application if a tab is removed while the animation
+ * has not finished. And we need to remove a tab, if the user drags a
+ * a dock widget out of a group of tabbed widgets
  */
 class CDockAreaTabBar : public QScrollArea
 {
@@ -61,6 +65,7 @@ private slots:
 
 protected:
 	virtual void wheelEvent(QWheelEvent* Event) override;
+
 	/**
 	 * Stores mouse position to detect dragging
 	 */
@@ -96,6 +101,7 @@ private slots:
 
 public:
 	using Super = QScrollArea;
+
 	/**
 	 * Default Constructor
 	 */

src/DockAreaTabBar.h

@@ -99,8 +99,9 @@ struct DockAreaTitleBarPrivate
 	}
 
     /**
-     * Helper class to set title bar button icons depending on operating system
-     * and to avoid duplicated code
+     * Helper function to set title bar button icons depending on operating
+     * system and to avoid duplicated code. On windows the standard icons
+     * are blurry since Qt 5.11 so we need to do some additional steps
      */
     void setTitleBarButtonIcon(tTileBarButton* Button, QStyle::StandardPixmap StandarPixmap)
     {
@@ -136,14 +137,14 @@ void DockAreaTitleBarPrivate::createButtons()
 	TabsMenuButton->setPopupMode(QToolButton::InstantPopup);
     setTitleBarButtonIcon(TabsMenuButton, QStyle::SP_TitleBarUnshadeButton);
 	QMenu* TabsMenu = new QMenu(TabsMenuButton);
-	#ifndef QT_NO_TOOLTIP
+#ifndef QT_NO_TOOLTIP
 	TabsMenu->setToolTipsVisible(true);
-	#endif
+#endif
 	_this->connect(TabsMenu, SIGNAL(aboutToShow()), SLOT(onTabsMenuAboutToShow()));
 	TabsMenuButton->setMenu(TabsMenu);
-	#ifndef QT_NO_TOOLTIP
+#ifndef QT_NO_TOOLTIP
 	TabsMenuButton->setToolTip(QObject::tr("List all tabs"));
-	#endif
+#endif
 	TabsMenuButton->setSizePolicy(QSizePolicy::Fixed, QSizePolicy::Expanding);
 	TopLayout->addWidget(TabsMenuButton, 0);
 	_this->connect(TabsMenuButton->menu(), SIGNAL(triggered(QAction*)),
@@ -154,9 +155,9 @@ void DockAreaTitleBarPrivate::createButtons()
 	UndockButton = new tTileBarButton();
 	UndockButton->setObjectName("undockButton");
 	UndockButton->setAutoRaise(true);
-	#ifndef QT_NO_TOOLTIP
+#ifndef QT_NO_TOOLTIP
 	UndockButton->setToolTip(QObject::tr("Detach Group"));
-	#endif
+#endif
     setTitleBarButtonIcon(UndockButton, QStyle::SP_TitleBarNormalButton);
     UndockButton->setSizePolicy(QSizePolicy::Fixed, QSizePolicy::Expanding);
 	TopLayout->addWidget(UndockButton, 0);
@@ -168,7 +169,7 @@ void DockAreaTitleBarPrivate::createButtons()
 	CloseButton->setObjectName("closeButton");
 	CloseButton->setAutoRaise(true);
     setTitleBarButtonIcon(CloseButton, QStyle::SP_TitleBarCloseButton);
-	#ifndef QT_NO_TOOLTIP
+#ifndef QT_NO_TOOLTIP
 	if (testConfigFlag(CDockManager::DockAreaCloseButtonClosesTab))
 	{
 		CloseButton->setToolTip(QObject::tr("Close Active Tab"));
@@ -177,7 +178,7 @@ void DockAreaTitleBarPrivate::createButtons()
 	{
 		CloseButton->setToolTip(QObject::tr("Close Group"));
 	}
-	#endif
+#endif
 	CloseButton->setSizePolicy(QSizePolicy::Fixed, QSizePolicy::Expanding);
 	CloseButton->setIconSize(QSize(16, 16));
 	TopLayout->addWidget(CloseButton, 0);

src/DockAreaTitleBar.cpp

@@ -43,7 +43,9 @@ class CDockAreaWidget;
 struct DockAreaTitleBarPrivate;
 
 /**
- * Title bar of a dock area
+ * Title bar of a dock area.
+ * The title bar contains a tabbar with all tabs for a dock widget group and
+ * with a tabs menu button, a undock button and a close button.
  */
 class CDockAreaTitleBar : public QFrame
 {
@@ -61,6 +63,10 @@ private slots:
 	void showContextMenu(const QPoint& pos);
 
 public slots:
+	/**
+	 * Call this slot to tell the title bar that it should update the tabs menu
+	 * the next time it is shown.
+	 */
 	void markTabsMenuOutdated();
 
 
@@ -87,7 +93,8 @@ public slots:
 	QAbstractButton* button(TitleBarButton which) const;
 
 	/**
-	 * This function is here for debug reasons
+	 * Marks the tabs menu outdated before it calls its base class
+	 * implementation
 	 */
 	virtual void setVisible(bool Visible) override;
 

src/DockAreaTitleBar.h

@@ -63,8 +63,11 @@ static const char* const INDEX_PROPERTY = "index";
 static const char* const ACTION_PROPERTY = "action";
 
 /**
- * New dock area layout mimics stack layout but only inserts the current
- * widget into the internal QLayout object
+ * Internal dock area layout mimics stack layout but only inserts the current
+ * widget into the internal QLayout object.
+ * \warning Only the current widget has a parent. All other widgets
+ * do not have a parent. That means, a widget that is in this layout may
+ * return nullptr for its parent() function if it is not the current widget.
  */
 class CDockAreaLayout
 {
@@ -118,7 +121,7 @@ class CDockAreaLayout
 	}
 
 	/**
-	 * Removes the given widget from the lyout
+	 * Removes the given widget from the layout
 	 */
 	void removeWidget(QWidget* Widget)
 	{

src/DockAreaWidget.cpp

@@ -185,12 +185,12 @@ protected slots:
 	QList<CDockWidget*> dockWidgets() const;
 
 	/**
-	 * Returns the number of dock widgets in this area
+	 * Returns the number of open dock widgets in this area
 	 */
 	int openDockWidgetsCount() const;
 
 	/**
-	 * Returns a list of dock widgets that are not closed
+	 * Returns a list of dock widgets that are not closed.
 	 */
 	QList<CDockWidget*> openedDockWidgets() const;
 
@@ -236,8 +236,10 @@ protected slots:
 	 * This functions returns the dock widget features of all dock widget in
 	 * this area.
 	 * A bitwise and is used to combine the flags of all dock widgets. That
-	 * means, if only dock widget does not support a certain flag, the whole
-	 * dock are does not support the flag.
+	 * means, if only one single dock widget does not support a certain flag,
+	 * the whole dock are does not support the flag. I.e. if one single
+	 * dock widget in this area is not closabe, the whole dock are is not
+	 * closable.
 	 */
 	CDockWidget::DockWidgetFeatures features() const;
 

src/DockAreaWidget.h

@@ -50,7 +50,10 @@ struct FloatingDockContainerPrivate;
 
 /**
  * Container that manages a number of dock areas with single dock widgets
- * or tabyfied dock widgets in each area
+ * or tabyfied dock widgets in each area.
+ * Each window that support docking has a DockContainerWidget. That means
+ * the main application window and all floating windows are ore contain
+ * an DockContainerWidget.
  */
 class ADS_EXPORT CDockContainerWidget : public QFrame
 {

src/DockContainerWidget.h

@@ -131,7 +131,7 @@ class ADS_EXPORT CDockManager : public CDockContainerWidget
 	 * If the given parent is a QMainWindow, the dock manager sets itself as the
 	 * central widget.
 	 * Before you create any dock widgets, you should properly setup the
-	 * configuration flags via setConfigFlags()
+	 * configuration flags via setConfigFlags().
 	 */
 	CDockManager(QWidget* parent = 0);
 

src/DockManager.h

@@ -245,9 +245,6 @@ class CDockOverlayCross : public QWidget
 protected:
 	virtual void showEvent(QShowEvent* e) override;
 	void setAreaWidgets(const QHash<DockWidgetArea, QWidget*>& widgets);
-
-private:
-
 }; // CDockOverlayCross
 
 } // namespace ads