Commit ab3997e3 authored by David Jarvie's avatar David Jarvie
Browse files

Add API documentation

parent 629228f8
Pipeline #125737 passed with stage
in 1 minute and 46 seconds
/*
* stackedwidgets.cpp - classes implementing stacked widgets
* Program: kalarm
* SPDX-FileCopyrightText: 2008-2021 David Jarvie <djarvie@kde.org>
* SPDX-FileCopyrightText: 2008-2022 David Jarvie <djarvie@kde.org>
*
* SPDX-License-Identifier: GPL-2.0-or-later
*/
......@@ -44,17 +44,17 @@ StackedScrollWidget::StackedScrollWidget(StackedScrollGroup* group, QWidget* par
setSizePolicy(QSizePolicy::MinimumExpanding, QSizePolicy::MinimumExpanding);
}
StackedScrollGroup::StackedScrollGroup(QDialog* dlg, QObject* tabParent)
: StackedGroupT<QScrollArea>(tabParent)
StackedScrollGroup::StackedScrollGroup(QDialog* dlg, QWidget* container)
: StackedGroupT<QScrollArea>(container)
, mDialog(dlg)
{
}
/******************************************************************************
* Return the minimum size for the tab, adjusted if necessary to a height that
* fits the screen.
* In order to make the QStackedWidget containing the tabs take the correct
* size, the value returned is actually the minimum size of the largest tab.
* Return the minimum size for the tabs, constrained if necessary to a height
* that fits the screen.
* In order to make the widget containing the tabs take the correct size, the
* value returned is actually the minimum size of the largest tab.
* Otherwise, only the currently visible tab would be taken into account with
* the result that the dialog would initially be displayed too small.
*/
......
/*
* stackedwidgets.h - classes implementing stacked widgets
* Program: kalarm
* SPDX-FileCopyrightText: 2008-2021 David Jarvie <djarvie@kde.org>
* SPDX-FileCopyrightText: 2008-2022 David Jarvie <djarvie@kde.org>
*
* SPDX-License-Identifier: GPL-2.0-or-later
*/
......@@ -36,6 +36,11 @@ template <class T> class StackedGroupT;
* A widget contained in a stack, whose minimum size hint is that of the largest
* widget in the stack. This class works together with StackedGroup.
*
* Do not use this class for widgets contained in a QStackedWidget or
* StackedWidget.
*
* @tparam T The base class for this widget. Must be derived from QWidget.
* @author David Jarvie <djarvie@kde.org>
*/
template <class T>
......@@ -43,8 +48,8 @@ class StackedGroupWidgetT : public T
{
public:
/** Constructor.
* @param group The stack group to insert this widget into.
* @param parent The parent object of this widget.
* @param group The stack group to insert this widget into.
*/
explicit StackedGroupWidgetT(StackedGroupT<T>* group, QWidget* parent = nullptr)
: T(parent),
......@@ -62,7 +67,8 @@ private:
/**
* A group of stacked widgets whose minimum size hints are all equal to the
* largest widget's minimum size hint.
* largest widget's minimum size hint. Use this alongside the widgets' container,
* e.g. QTabWidget.
*
* It is inherited from QObject solely to ensure automatic deletion when its
* parent widget is deleted.
......@@ -73,7 +79,13 @@ template <class T>
class StackedGroupT : public QObject
{
public:
explicit StackedGroupT(QObject* parent = nullptr) : QObject(parent) {}
/** Constructor.
* @param container The parent widget. This should be set to the container
* for the stacked widgets, which will ensure that this
* object is deleted when the container is deleted.
*/
explicit StackedGroupT(QWidget* container) : QObject(container) {}
void addWidget(StackedGroupWidgetT<T>* w) { mWidgets += w; }
void removeWidget(StackedGroupWidgetT<T>* w) { mWidgets.removeAll(w); }
virtual QSize minimumSizeHint() const;
......@@ -91,17 +103,20 @@ QSize StackedGroupT<T>::minimumSizeHint() const
return sz;
}
/** A non-scrollable stacked widget. */
/** A non-scrollable stacked QWidget. */
using StackedGroupWidget = StackedGroupWidgetT<QWidget>;
/** A group of non-scrollable stacked widgets. */
/** A group of non-scrollable stacked widgets which are each derived from QWidget. */
using StackedGroup = StackedGroupT<QWidget>;
class StackedScrollGroup;
/**
* A stacked widget which becomes scrollable when necessary to fit the height
* of the screen.
* A stacked QScrollArea widget, which becomes scrollable when necessary to
* fit the height of the screen.
*
* Do not use this class for widgets contained in a QStackedWidget or
* StackedWidget.
*
* @author David Jarvie <djarvie@kde.org>
*/
......@@ -113,20 +128,48 @@ public:
};
/**
* A group of stacked widgets which individually become scrollable when necessary
* to fit the height of the screen.
* A group of stacked StackedScrollWidget widgets, which individually become
* scrollable when necessary to fit the height of the screen.
*
* @author David Jarvie <djarvie@kde.org>
*/
class StackedScrollGroup : public StackedGroupT<QScrollArea>
{
public:
StackedScrollGroup(QDialog*, QObject* tabParent);
QSize minimumSizeHint() const override;
int heightReduction() const { return mHeightReduction; }
QSize adjustSize(bool force = false);
void setSized() { mSized = true; }
bool sized() const { return mSized; }
/** Constructor.
* @param dialog The dialog which contains the widgets.
* @param container The parent widget. This should be set to the container
* for the stacked widgets, which will ensure that this
* object is deleted when the container is deleted.
*/
StackedScrollGroup(QDialog* dialog, QWidget* container);
/** Return the minimum size for the tabs, constrained if necessary to a height
* that fits the dialog into the screen. The dialog height must have been
* previously evaluated by calling adjustSize().
*/
QSize minimumSizeHint() const override;
/** Return the reduction in dialog height which adjustSize() performed in
* order to fit the dialog to the desktop.
*/
int heightReduction() const { return mHeightReduction; }
/** Set the minimum height for the dialog, so as to accommodate the tabs,
* but constrained to fit the desktop. If necessary, the tab contents are
* made scrollable.
* @param force If false, this method will only evaluate and set the
* minimum dialog height the first time it is called. Set
* true to force re-evaluation.
* @return The minimum size for the dialog, or null if the size was not evaluated.
*/
QSize adjustSize(bool force = false);
/** Prevent adjustSize(false) from evaluating or setting the dialog height. */
void setSized() { mSized = true; }
/** Return whether the dialog size has already been set, e.g. by adjustSize(). */
bool sized() const { return mSized; }
private:
QSize maxMinimumSizeHint() const;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment