some minor steps towards doxygen docs

This commit is contained in:
Uwe Rathmann 2021-01-25 11:06:01 +01:00
parent 41549a4392
commit a19c4c7878
9 changed files with 661 additions and 471 deletions

View File

@ -895,7 +895,7 @@ EXCLUDE_SYMLINKS = NO
# Note that the wildcards are matched against the file with absolute path, so to # Note that the wildcards are matched against the file with absolute path, so to
# exclude all test directories for example use the pattern */test/* # exclude all test directories for example use the pattern */test/*
EXCLUDE_PATTERNS = EXCLUDE_PATTERNS = *Private.*
# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
# (namespaces, classes, functions, etc.) that should be excluded from the # (namespaces, classes, functions, etc.) that should be excluded from the

View File

@ -1,112 +1,92 @@
/*! /*!
\brief Defines a series of enum values for describing particular aspects of controls \class QskAspect QskAspect.h
\ingroup theming
\sa QskSkinHint \brief Lookup key for a QskSkinHintTable
\sa QskControl::skinHint
\sa QskSkin::skinHint
*/
namespace QskAspect
{
/*!
\var Aspect
Used by the \ref qskskinning "skin engine" to determine how a given aspect Used by the \ref qskskinning "skin engine" to determine how a given aspect
of a control is drawn. While Aspect is simply a 64-bit unsigned integer, it of a control is drawn. While Aspect is simply a 64-bit unsigned integer, it
is composed of smaller enum bitfields which can be ORed together to is composed of smaller enum bitfields which can be ORed together to
describe a more specific part of the user interface. describe a more specific part of the user interface.
For example, the top border color of a QskPushButton while pressed is For example, the border colors of a QskPushButton while pressed is
defined by combining the State (QskAbstractButton::Pressed) with the defined by combining the State (QskAbstractButton::Pressed) with the
Subcontrol (QskPushButton::Panel), the Primitive (Border), Subcontrol (QskPushButton::Panel), the Primitive (Border),
the edge/corner (Top), and the Type (Color) as so: and the Type (Color) as so:
auto aspect = QskAbstractButton::Pressed | QskPushButton::Panel | QskAspect::Border | QskAspect::Top | QskAspect::Color auto aspect = QskPushButton::Panel | QskAbstractButton::Pressed | QskAspect::Color | QskAspect::Border
This `aspect` can then be passed to, e.g., QskSkin::setSkinHint as the first \sa QskSkinnable::effectiveSkinHint(), QskSkin::skinHint()
argument. */
The 64 bits in Aspect are partitioned as follows (Note: flags are /*!
interpreted as single bits, while IDs are interpreted as aggregate integer \enum QskAspect::Type
values):
0xFFFF000000000000 | 0x0000FFFF00000000 | 0x00000000FFF00000 | 0x00000000000F0000 | 0x000000000000F000 | 0x0000000000000800 | 0x0000000000000700 | 0x00000000000000FF
-------------------| --------------------------- | -------------------------------- | ------------------------------ | -------------------------------------------- | ---------------------------- | ------------------------- | --------------------------
Unused | QskAspect::State (16 flags) | QskAspect::Subcontrol (4096 IDs) | QskAspect::Primitive (255 IDs) | QskAspect::Corner, QskAspect::Edge (4 flags) | QskAspect::Modifier (1 flag) | QskAspect::Type (128 IDs) | QskAspect::Index (256 IDs)
\note The above structure may change in the future as features are added \brief Represents the type of the Aspect.
and/or sections are be expanded to accommodate wider information types.
*/
/*! Represents a specific "subresource" ID, usually a FontRole or ColorRole. The type categorizes the aspect to be a metric, color or "something else".
In most cases, the default (`0`) is appropriate. */
enum Index : std::uint8_t
{
FirstIndex = 0x00,
LastIndex = 0xFF,
};
/*! Represents the data type of the Aspect. The default is Flag, but Often primitives are related to a specific category. F.e QskAspect::Alignment will
more commonly this will be a Color or Metric. Colors are 32-bit ARGB probably always be a QskAspect::Flag, while QskAspect::Border will usually
values (see QRgb), and Metrics are `float` values typically be combined with QskAspect::Color and QskAspect::Metric.
corresponding to pixel distances. */
enum Type : std::uint16_t
{
Flag = 0x0000, // default, enum / int
Metric = 0x0100, // float
Color = 0x0200, // QRgb (uint)
};
/*! Adds extra information to Type. Currently, the only modifier is Animator, Smooth transitions can be set up depending on these categories. F.e when
which specifies that skinhint corresponds to the animation data for this changing from daylight to darkness color schemem only values of QskAspect::Color
Aspect. */ aspects need to be considered. But when changing the Look&Feel of the
enum Modifier : std::uint16_t application all type of aspects need to be considered.
{
Animator = 0x0800 ///< Denotes that the skin hint affects the animation timing/easing.
};
/*! Used with certain Primitives (such as Border) to specify an edge. Zero or \var QskAspect::Type QskAspect::Flag
more Edges can be combined to denote which edge(s) the Aspect is concerned.
The default value of `0` implies AllEdges. */
enum Edge : std::uint32_t
{
Left = 0x00001000,
Top = 0x00002000,
Right = 0x00004000,
Bottom = 0x00008000,
AllEdges = Top | Left | Right | Bottom
};
/*! Used with certain Primitives (such as Radius) to specify a corner. Zero or Flags are all sort of attributes that are no metrics or colors - f.e
more Corners can be combined to denote which corner(s) the Aspect is concerned. an alignment. A reasonable subset of possible flags is offered as
The default value of `0` implies AllCorners. */ QskAspect::FlagPrimitive
enum Corner : std::uint32_t
{
TopLeft = 0x00001000,
TopRight = 0x00002000,
BottomRight = 0x00004000,
BottomLeft = 0x00008000,
LeftCorners = TopLeft | BottomLeft,
RightCorners = TopRight | BottomRight,
TopCorners = TopLeft | TopRight,
BottomCorners = BottomLeft | BottomRight,
AllCorners = TopLeft | TopRight | BottomLeft | BottomRight
};
/*! The fundamental building blocks of box-like UI components, based on the \var QskAspect::Type QskAspect::Metric
<a>CSS box model</a>. See QskSkinRenderer::updateBox for more information. */
enum Primitive : std::uint32_t
{
Background = 0x00000000, ///< The default primitive, the background color(s)
Margin = 0x00010000, ///< The margin, according to the CSS box model Metrics are related to geometries in most cases corresponding to pixel distances.
Padding = 0x00020000, ///< The padding, according to the CSS box model Examples are the margin/padding. A reasonable subset of possible metrics
RadiusX = 0x00030000, ///< The horizontal corner radius, according to the CSS box model is offered as QskAspect::MetricPrimitive.
RadiusY = 0x00040000, ///< The vertical corner radius, according to the CSS box model
Border = 0x00050000, ///< The border thickness/color, according to the CSS box model
Shadow = 0x00060000, ///< The shadow thickness/color, according to the CSS box model
Radius = RadiusX | RadiusY, // 0x70000 ///< Convenience enum for specifying both horizontal and vertical radii
Fundamental = 0x00080000 // Disables edge/corner routing \var QskAspect::Type QskAspect::Color
};
Colors are all sort of color values, like fill gradients, border colors.
*/
/*!
\enum QskAspect::FlagPrimitive
\var QskAspect::FlagPrimitive QskAspect::NoFlagPrimitive
\var QskAspect::FlagPrimitive QskAspect::Alignment
\var QskAspect::FlagPrimitive QskAspect::Direction
\var QskAspect::FlagPrimitive QskAspect::Style
\var QskAspect::FlagPrimitive QskAspect::Decoration
\var QskAspect::FlagPrimitive QskAspect::GraphicRole
\var QskAspect::FlagPrimitive QskAspect::FontRole
*/
/*!
\enum QskAspect::MetricPrimitive
\var QskAspect::MetricPrimitive QskAspect::NoMetricPrimitive
\var QskAspect::MetricPrimitive QskAspect::StrutSize
\var QskAspect::MetricPrimitive QskAspect::Size
\var QskAspect::MetricPrimitive QskAspect::Position
\var QskAspect::MetricPrimitive QskAspect::Margin
\var QskAspect::MetricPrimitive QskAspect::Padding
\var QskAspect::MetricPrimitive QskAspect::Shadow
\var QskAspect::MetricPrimitive QskAspect::Spacing
\var QskAspect::MetricPrimitive QskAspect::Shape
\var QskAspect::MetricPrimitive QskAspect::Border
*/
/*!
\enum QskAspect::ColorPrimitive
\var QskAspect::ColorPrimitive QskAspect::NoColorPrimitive
\var QskAspect::ColorPrimitive QskAspect::TextColor
\var QskAspect::ColorPrimitive QskAspect::StyleColor
\var QskAspect::ColorPrimitive QskAspect::LinkColor
*/
/*! For use within the rendering of a specific QskSkinnable. While the Default /*! For use within the rendering of a specific QskSkinnable. While the Default
value applies to any control (and can be used as a fallback), specifying a value applies to any control (and can be used as a fallback), specifying a
@ -134,58 +114,3 @@ enum State : std::uint64_t
Automatic = 0x0000000000000000, ///< No specified state (the default) Automatic = 0x0000000000000000, ///< No specified state (the default)
NoState = 0x0000FFFF00000000 ///< Empty state, explicitly specified. Useful in some types of animators. NoState = 0x0000FFFF00000000 ///< Empty state, explicitly specified. Useful in some types of animators.
}; };
/*! These Aspects are for convenience, providing commonly combined values
to limit the verbosity of combining Aspects in application code. */
enum : Aspect
{
MarginTop = Margin | Top, ///< The top margin
MarginLeft = Margin | Left, ///< The left margin
MarginRight = Margin | Right, ///< The right margin
MarginBottom = Margin | Bottom, ///< The bottom margin
PaddingTop = Padding | Top, ///< The top padding
PaddingLeft = Padding | Left, ///< The left padding
PaddingRight = Padding | Right, ///< The right padding
PaddingBottom = Padding | Bottom, ///< The bottom padding
BorderTop = Border | Top, ///< The top border
BorderLeft = Border | Left, ///< The left border
BorderRight = Border | Right, ///< The right border
BorderBottom = Border | Bottom, ///< The bottom border
ShadowTop = Shadow | Top, ///< The top shadow
ShadowLeft = Shadow | Left, ///< The left shadow
ShadowRight = Shadow | Right, ///< The right shadow
ShadowBottom = Shadow | Bottom, ///< The bottom shadow
RadiusXTopLeft = RadiusX | TopLeft, ///< The top-left horizontal radius
RadiusXTopRight = RadiusX | TopRight, ///< The top-right horizontal radius
RadiusXBottomLeft = RadiusX | BottomLeft, ///< The bottom-left horizontal radius
RadiusXBottomRight = RadiusX | BottomRight, ///< The bottom-right horizontal radius
RadiusYTopLeft = RadiusY | TopLeft, ///< The top-left vertical radius
RadiusYTopRight = RadiusY | TopRight, ///< The top-right vertical radius
RadiusYBottomLeft = RadiusY | BottomLeft, ///< The bottom-left vertical radius
RadiusYBottomRight = RadiusY | BottomRight, ///< The bottom-right vertical radius
// Standard metrics
Size = 0x0000000000000000 | Fundamental | Metric, ///< A "size" placeholder, like width or height
Position = 0x0000000000010000 | Fundamental | Metric, ///< A "position" placeholder, like the position of a QskSlider
MinimumWidth = 0x0000000000020000 | Fundamental | Metric, ///< A minimum width hint
MinimumHeight = 0x0000000000030000 | Fundamental | Metric, ///< A minimum height hint
MaximumWidth = 0x0000000000040000 | Fundamental | Metric, ///< A maximum width hint
MaximumHeight = 0x0000000000050000 | Fundamental | Metric, ///< A maximum height hint
Spacing = 0x0000000000060000 | Fundamental | Metric, ///< A spacing hint, such as between rows in a QskListBox
// Standard flags
Alignment = 0x0000000000000000 | Fundamental | Flag, ///< A flag typically used for storing text alignments (Qt::Alignment)
Style = 0x0000000000010000 | Fundamental | Flag, ///< A flag for storing text style (Qsk::Style)
Decoration = 0x0000000000020000 | Fundamental | Flag, ///< A flag for storing decoration information
ColorRole = 0x0000000000060000 | Fundamental | Flag, ///< A flag for specifying a QRgb value at a given QskAspect::Index
FontRole = 0x0000000000070000 | Fundamental | Flag, ///< A flag for specifying a QFont value at a given QskAspect::Index
// Standard colors
TextColor = 0x0000000000000000 | Fundamental | Color, ///< A placeholder for text color
StyleColor = 0x0000000000010000 | Fundamental | Color, ///< A placeholder for text style color
LinkColor = 0x0000000000020000 | Fundamental | Color, ///< A placeholder for text link color
AllAspects = 0xFFFFFFFFFFFFFFFF ///< All possible bits in Aspect (useful for e.g. QskSkinnable::markDirty).
};
}

View File

@ -1,5 +1,11 @@
/*! /*!
\class QskQuickItem QskQuickItem.h \class QskQuickItem QskQuickItem.h
\ingroup framework
QskQuickItem completes the C++ API of QQuickItem and implements some
flags to offer better control over the operations happening in the
update cycle.
*/ */
/*! /*!
@ -10,56 +16,339 @@
QskQuickItem implements a couple of modifications, that QskQuickItem implements a couple of modifications, that
can be en/disabled individually. can be en/disabled individually.
The default setting enables all attributes. \var QskQuickItem::Flag QskQuickItem::DeferredUpdate
\var DeferredUpdate Creating of sceme graph nodes is blocked when being invisible.
Creating of paint nodes is blocked for all invisible nodes
( QQuickItem::isVisible() ). ( QQuickItem::isVisible() ).
\note Some more advanced algorithms have not yet been implemented, \note Some more advanced algorithms have not yet been implemented,
such as viewport frustrum culling (i.e. hiding items outside of the such as viewport frustrum culling (i.e. hiding items outside of the
window geometry). window geometry).
\var DeferredPolish \var QskQuickItem::Flag QskQuickItem::DeferredPolish
Calculation of layouts ( updateLayout() ) is blocked for all invisible Polishing an item ( QQuickItem::polish() ) is blocked when being invisible.
nodes ( QQuickItem::isVisible() ). F.e for all items being derived from QskControl the layout calculations
happen during polishing.
\var DeferredLayout \var QskQuickItem::Flag QskQuickItem::DeferredLayout
Updates of the implicit size is blocked until effectiveConstraint() or sizeHint() Recalculations of the implicitSize are blocked until being explicitely requested by
is explicitly called. When being enabled the implicit size is not recalculated before QQuickItem::implicitSize().
being requested - usually by a QskLayout.
\var CleanupOnVisibility When being enabled the item indicates layout relevant changes by
sending a QEvent::LayoutRequest ( similar to QWidget ) to its parent item
without recalculating the actual size hints ( f.e the implicitSize ).
When having layout code that relies on binding the implicit width/height
the QskQuickItem::DeferredLayout flag needs to be disabled.
\note All layout classes offered by the Qt/Quick modules of the Qt Company
( f.e anchors ) do require immediate updates of the implicit size.
\sa QskQuickItem::resetImplicitSize()
\var QskQuickItem::Flag QskQuickItem::CleanupOnVisibility
Delete scene graph nodes, when the item becomes hidden ( QQuickItem::isVisible() ). Delete scene graph nodes, when the item becomes hidden ( QQuickItem::isVisible() ).
Enabling this mode will reduce the memory footprint, but comes at the cost Enabling this mode will reduce the memory footprint, but comes at the cost
of having to recreate nodes later. of having to recreate nodes later.
\var PreferRasterForTextures \var QskQuickItem::Flag QskQuickItem::PreferRasterForTextures
When creating textures from QskGraphic, prefer the raster paint When creating textures from QskGraphic, prefer the raster paint
engine over the OpenGL paint engine. engine over the OpenGL paint engine.
\var DebugForceBackground \var DebugForceBackground
Always fill the background of thecontrol with a random color. Always fill the background of the item with a random color.
\note This flag is useful when analyzing layouts. \note This flag is useful when analyzing layouts.
\sa controlFlags(), setControlFlags(), resetControlFlags() \sa controlFlags(), setControlFlags(), resetControlFlags()
testControlFlag(), setControlFlag(), resetControlFlag() testControlFlag(), setControlFlag(), resetControlFlag()
*/ */
/*! /*!
\fn void QskQuickItem::setControlFlag( Flag, bool on = true ); \fn QskQuickItem::QskQuickItem
bla
*/
*!
\fn QskQuickItem::~QskQuickItem
\bla
*/ */
/*! /*!
\fn void QskQuickItem::resetControlFlag( Flag ); \fn QskQuickItem::className
bla
*/ */
/*! /*!
\fn bool QskQuickItem::testControlFlag( Flag ) const; \fn QskQuickItem::isVisibleTo
bla
*/ */
/*!
\fn QskQuickItem::isVisibleToParent
bla
*/
/*!
\fn QskQuickItem::hasChildItems
bla
*/
/*!
\fn QskQuickItem::setGeometry( qreal, qreal, qreal, qreal )
bla
*/
/*!
\fn QskQuickItem::setGeometry( const QRectF& )
bla
*/
/*!
\fn QskQuickItem::geometry() const
bla
*/
/*!
\fn QskQuickItem::geometryChange
bla
*/
/*!
\fn QskQuickItem::rect
bla
*/
/*!
\fn QskQuickItem::implicitSize
bla
*/
/*!
\fn QskQuickItem::setPolishOnResize
bla
*/
/*!
\fn QskQuickItem::polishOnResize() const
bla
*/
/*!
\fn QskQuickItem::setTransparentForPositioner
bla
*/
/*!
\fn QskQuickItem::isTransparentForPositioner
bla
*/
/*!
\fn QskQuickItem::setTabFence
bla
*/
/*!
\fn QskQuickItem::isTabFence
bla
*/
/*!
\fn QskQuickItem::setLayoutMirroring
bla
*/
/*!
\fn QskQuickItem::resetLayoutMirroring
bla
*/
/*!
\fn QskQuickItem::layoutMirroring
bla
*/
/*!
\fn QskQuickItem::setControlFlags
bla
*/
/*!
\fn QskQuickItem::resetControlFlags
bla
*/
/*!
\fn QskQuickItem::controlFlags
bla
*/
/*!
\fn QskQuickItem::setControlFlag
bla
*/
/*!
\fn QskQuickItem::resetControlFlag
bla
*/
/*!
\fn QskQuickItem::testControlFlag
bla
*/
/*!
\fn QskQuickItem::controlFlagsChanged
bla
*/
/*!
\fn QskQuickItem::classBegin
bla
*/
/*!
\fn QskQuickItem::componentComplete
bla
*/
/*!
\fn QskQuickItem::releaseResources
bla
*/
/*!
\fn QskQuickItem::isPolishScheduled
bla
*/
/*!
\fn QskQuickItem::isUpdateNodeScheduled
bla
*/
/*!
\fn QskQuickItem::isInitiallyPainted
bla
*/
/*!
\fn QskQuickItem::maybeUnresized
bla
*/
/*!
\fn QskQuickItem::itemFlagsChanged
bla
*/
/*!
\fn QskQuickItem::setGeometry
bla
*/
/*!
\fn QskQuickItem::show
bla
*/
/*!
\fn QskQuickItem::hide
bla
*/
/*!
\fn QskQuickItem::setVisible
bla
*/
/*!
\fn QskQuickItem::resetImplicitSize
bla
*/
/*!
\fn QskQuickItem::event
bla
*/
/*!
\fn QskQuickItem::changeEvent
bla
*/
/*!
\fn QskQuickItem::geometryChangeEvent
bla
*/
/*!
\fn QskQuickItem::windowChangeEvent
bla
*/
/*!
\fn QskQuickItem::itemChange
bla
*/
/*!
void \fn QskQuickItem::aboutToShow
bla
*/

View File

@ -39,7 +39,6 @@
\class QskGestureRecognizer \class QskGestureRecognizer
\class QskPanGestureRecognizer \class QskPanGestureRecognizer
\class QskQuick \class QskQuick
\class QskQuickItem
\class QskSetup \class QskSetup
\class QskShortcutMap \class QskShortcutMap
\class QskWindow \class QskWindow
@ -55,7 +54,6 @@
\defgroup Themeing Themeing \defgroup Themeing Themeing
\{ \{
\class QskAspect
\class QskBoxBorderColors \class QskBoxBorderColors
\class QskBoxBorderMetrics \class QskBoxBorderMetrics
\class QskBoxShapeMetrics \class QskBoxShapeMetrics
@ -99,29 +97,7 @@
\class QskTextLabel \class QskTextLabel
\} \}
\defgroup Skinlets Skinlets \defgroup container Container
\{
\class QskBoxSkinlet
\class QskFocusIndicatorSkinlet
\class QskGraphicLabelSkinlet
\class QskListViewSkinlet
\class QskPageIndicatorSkinlet
\class QskPopupSkinlet
\class QskProgressBarSkinlet
\class QskPushButtonSkinlet
\class QskScrollViewSkinlet
\class QskSeparatorSkinlet
\class QskSliderSkinlet
\class QskStatusIndicatorSkinlet
\class QskSubWindowAreaSkinlet
\class QskSubWindowSkinlet
\class QskTabButtonSkinlet
\class QskTabViewSkinlet
\class QskTextInputSkinlet
\class QskTextLabelSkinlet
\}
\defgroup Container Container
\{ \{
\class QskScrollArea \class QskScrollArea
\class QskSubWindowArea \class QskSubWindowArea