From 6289071bcd1523d4a7fb8c3205513f8c2db26153 Mon Sep 17 00:00:00 2001
From: Steffen Baranowsky <BaraMGB@freenet.de>
Date: Wed, 15 Nov 2017 06:15:01 +0100
Subject: [PATCH] adds doxygen documentation to SubWindow.cpp (#3450)

Doxygen documentation for SubWindow.cpp
---
 include/SubWindow.h   |  9 +++++-
 src/gui/SubWindow.cpp | 74 +++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 79 insertions(+), 4 deletions(-)

diff --git a/include/SubWindow.h b/include/SubWindow.h
index 4bda072a6..24485109e 100644
--- a/include/SubWindow.h
+++ b/include/SubWindow.h
@@ -40,7 +40,14 @@ class QMoveEvent;
 class QResizeEvent;
 class QWidget;
 
-
+/**
+ * @brief The SubWindow class
+ * 
+ *  Because of a bug in the QMdiSubWindow class to save the right position and size
+ *  of a subwindow in a project and because of the inability
+ *  for cusomizing the title bar appearance, lmms implements its own subwindow
+ *  class.
+ */
 class EXPORT SubWindow : public QMdiSubWindow
 {
 	Q_OBJECT
diff --git a/src/gui/SubWindow.cpp b/src/gui/SubWindow.cpp
index 15d8a382e..c2f071034 100644
--- a/src/gui/SubWindow.cpp
+++ b/src/gui/SubWindow.cpp
@@ -2,9 +2,11 @@
  * SubWindow.cpp - Implementation of QMdiSubWindow that correctly tracks
  *   the geometry that windows should be restored to.
  *   Workaround for https://bugreports.qt.io/browse/QTBUG-256
+ *   This implementation adds a custom themed title bar to
+ *   the subwindow.
  *
  * Copyright (c) 2015 Colin Wallace <wallace.colin.a@gmail.com>
- *
+ * Copyright (c) 2016 Steffen Baranowsky <baramgb@freenet.de>
  * This file is part of LMMS - https://lmms.io
  *
  * This program is free software; you can redistribute it and/or
@@ -95,6 +97,12 @@ SubWindow::SubWindow( QWidget *parent, Qt::WindowFlags windowFlags ) :
 
 
 
+/**
+ * @brief SubWindow::paintEvent
+ * 
+ *  This draws our new title bar with custom colors
+ *  and draws a window icon on the left upper corner.
+ */
 void SubWindow::paintEvent( QPaintEvent * )
 {
 	QPainter p( this );
@@ -119,6 +127,12 @@ void SubWindow::paintEvent( QPaintEvent * )
 
 
 
+/**
+ * @brief SubWindow::changeEvent
+ * 
+ * Triggers if the window title changes and calls adjustTitleBar().
+ * @param event
+ */
 void SubWindow::changeEvent( QEvent *event )
 {
 	QMdiSubWindow::changeEvent( event );
@@ -133,6 +147,16 @@ void SubWindow::changeEvent( QEvent *event )
 
 
 
+/**
+ * @brief SubWindow::elideText
+ * 
+ *  Stores the given text into the given label.
+ *  Shorts the text if it's too big for the labels width
+ *  ans adds three dots (...)
+ * 
+ * @param label - holds a pointer to the QLabel
+ * @param text  - the text which will be stored (and if needed breaked down) into the QLabel.
+ */
 void SubWindow::elideText( QLabel *label, QString text )
 {
 	QFontMetrics metrix( label->font() );
@@ -144,6 +168,15 @@ void SubWindow::elideText( QLabel *label, QString text )
 
 
 
+/**
+ * @brief SubWindow::isMaximized
+ * 
+ * This function checks if the subwindow is maximized.
+ * QMdiSubWindow::isMaximized() doesn't work on MacOS.
+ * Therefore we need our own implementation for checking this
+ * @return true if the subwindow is maximized at the moment.
+ *         false if it's not.
+ */
 bool SubWindow::isMaximized()
 {
 #ifdef LMMS_BUILD_APPLE
@@ -161,6 +194,12 @@ bool SubWindow::isMaximized()
 
 
 
+/**
+ * @brief SubWindow::getTrueNormalGeometry
+ * 
+ *  same as QWidet::normalGeometry, but works properly under X11
+ *  see https://bugreports.qt.io/browse/QTBUG-256
+ */
 QRect SubWindow::getTrueNormalGeometry() const
 {
 	return m_trackedNormalGeom;
@@ -216,7 +255,15 @@ void SubWindow::setBorderColor( const QColor &c )
 
 
 
-
+/**
+ * @brief SubWindow::moveEvent
+ * 
+ *  overides the QMdiSubWindow::moveEvent() for saving the position
+ *  of the subwindow into m_trackedNormalGeom. This position
+ *  will be saved with the project because of an Qt bug wich doesn't
+ *  save the right position. look at: https://bugreports.qt.io/browse/QTBUG-256
+ * @param event
+ */
 void SubWindow::moveEvent( QMoveEvent * event )
 {
 	QMdiSubWindow::moveEvent( event );
@@ -231,6 +278,14 @@ void SubWindow::moveEvent( QMoveEvent * event )
 
 
 
+/**
+ * @brief SubWindow::adjustTitleBar
+ * 
+ *  Our title bar needs buttons for maximize/restore and close in the right upper corner.
+ *  We check if the subwindow is maximizable and put the buttons on the right positions.
+ *  At next we calculate the width of the title label and call elideText() for adding
+ *  the window title to m_windowTitle (which is a QLabel)
+ */
 void SubWindow::adjustTitleBar()
 {
 	// button adjustments
@@ -289,7 +344,6 @@ void SubWindow::adjustTitleBar()
 
 
 
-
 void SubWindow::focusChanged( QMdiSubWindow *subWindow )
 {
 	if( m_hasFocus && subWindow != this )
@@ -306,6 +360,20 @@ void SubWindow::focusChanged( QMdiSubWindow *subWindow )
 
 
 
+/**
+ * @brief SubWindow::resizeEvent
+ * 
+ *  On every rezise event we have to adjust our title label.
+ * 
+ *  At next we give the event to QMdiSubWindow::resizeEvent() which handles 
+ *  the event on its behavior.
+ * 
+ *  At last we store the current size into m_trackedNormalGeom. This size
+ *  will be saved with the project because of an Qt bug wich doesn't
+ *  save the right size. look at: https://bugreports.qt.io/browse/QTBUG-256
+ * 
+ * @param event
+ */
 void SubWindow::resizeEvent( QResizeEvent * event )
 {
 	adjustTitleBar();