qskinny/doc/classes/QskAspect.dox

/*!
    \class QskAspect QskAspect.h
    \ingroup Themeing

    \brief Lookup key for a QskSkinHintTable

    QskAspect is used by the \ref qskskinning "themeing system" to determine a
    a certain aspect of a QskSkinnable. While an aspect is simply a 64-bit
    unsigned integer, it is composed of smaller enum bitfields which can be ORed
    together to describe a more specific part of the user interface.

    For example, the border colors of a QskPushButton while pressed is
    defined by combining the State (QskAbstractButton::Pressed) with the
    Subcontrol (QskPushButton::Panel), the Primitive (QskAspect::Border),
    and the Type (QskAspect::Color) as so:

        auto aspect = QskPushButton::Panel | QskAbstractButton::Pressed | QskAspect::Color | QskAspect::Border

    \sa QskSkinnable::effectiveSkinHint(), QskSkinHintTable
*/

/*!
    \enum QskAspect::Type

    \brief Represents the type of the Aspect. 

    The type categorizes the aspect to be a metric, color or "something else".

    Often primitives are related to a specific category. F.e QskAspect::Alignment will
    probably always be a QskAspect::Flag, while QskAspect::Border will usually
    be combined with QskAspect::Color and QskAspect::Metric.

    Smooth transitions can be set up depending on these categories. F.e when
    changing from daylight to darkness color schemem only values of QskAspect::Color
    aspects need to be considered. But when changing the Look&Feel of the 
    application all type of aspects need to be considered.

    \var QskAspect::Type QskAspect::Flag

    Flags are all sort of attributes that are no metrics or colors - f.e
    an alignment.

    \var QskAspect::Type QskAspect::Metric

    Metrics are related to geometries in most cases corresponding to pixel distances.
    Examples are margin/padding(s).

    \var QskAspect::Type QskAspect::Color

    Colors are all sort of color values, like fill gradients, border colors.
 */

/*!
    \enum QskAspect::Primitive

    \brief Represents a specific element or attribute 

    This enum defines an initial list of primitive elements. A primitive is a common
    element, such as a border, font role etc.

    The number of primitives can be extended by additional application
    specific elements by using reservePrimitives()

    \sa setPrimitive(), clearPrimitive(), primitive(),
        reservePrimitives(), primitiveCount()

    \var QskAspect::Primitive QskAspect::NoPrimitive
        No specific primitive

    \var QskAspect::Primitive QskAspect::Alignment
        Usually used in combination with QskAspect::Flag

    \sa QskSkinnable::alignmentHint(), QskSkinHintTableEditor::alignment()

    \var QskAspect::Primitive QskAspect::Style
        Usually used in combination with QskAspect::Flag

    \var QskAspect::Primitive QskAspect::GraphicRole

        A graphic role is an id that can be used to retrieve a specific
        color filter for a graphic.

    \sa QskSkinnable::graphicRoleHint(), QskSkinHintTableEditor::graphicRole(),
        QskSkin::graphicFilter(), QskSkinnable::effectiveGraphicFilter()

    \var QskAspect::Primitive QskAspect::FontRole

        A font role is an id that can be used to retrieve a specific
        font from the font table.

    \sa QskSkinnable::fontRoleHint(), QskSkinHintTableEditor::fontRole()
        QskSkin::font(), QskSkinnable::effectiveFont()

    \var QskAspect::Primitive QskAspect::TextColor
        A color for regular text

    \sa QskTextColors(), QskAspect::StyleColor, QskAspect::LinkColor

    \var QskAspect::Primitive QskAspect::StyleColor
        This color is used as the outline color for outlined text,
        and as the shadow color for raised or sunken text.

    \sa QskAspect::TextColor, QskAspect::LinkColor

    \var QskAspect::Primitive QskAspect::LinkColor
        The color of links in texts.

    \sa QskAspect::TextColor, QskAspect::StyleColor

    \var QskAspect::Primitive QskAspect::StrutSize
        A sensible metric - usually a QSizeF. 

        This size is usually used for layout calculations. It might be
        interpreted as a minimum, maximum or fixed size.

    \sa QskSkinnable::strutSizeHint(), QskSkinHintTableEditor::strutSize()

    \var QskAspect::Primitive QskAspect::Size
        A placeholder for defining a metric.

    \var QskAspect::Primitive QskAspect::Position

        A metric that is often used for animating controls ( slide in/out )
        or handles.

    \var QskAspect::Primitive QskAspect::Margin

        Margins like being described in the CSS Box Model.

    \sa QskSkinnable::marginHint(), QskSkinHintTableEditor::margin()

    \var QskAspect::Primitive QskAspect::Padding

        Margins like being described in the CSS Box Model.

    \sa QskSkinnable::paddingHint(), QskSkinHintTableEditor::padding()

    \var QskAspect::Primitive QskAspect::Spacing

        A metric, that is used by layout code for the distance between
        elements.

    \sa QskSkinnable::spacingHint(), QskSkinHintTableEditor::spacing()

    \var QskAspect::Primitive QskAspect::Shadow

        A primitive to define colors and metrics for shadows.

    \sa QskShadowMetrics()

        A primitive to define the shape of an element.

    \var QskAspect::Primitive QskAspect::Shape

    \sa QskBoxShapeMetrics, QskSkinnable::boxShapeHint(), QskSkinHintTableEditor::boxShape()

    \var QskAspect::Primitive QskAspect::Border

        A primitive to define colors and metrics for borders.

    \sa QskSkinnable::boxBorderMetricsHint(), QskSkinnable::boxBorderColorsHint()
        QskSkinHintTableEditor::boxBorderMetrics(), QskSkinHintTableEditor::boxBorderColors()
*/

/*! 
    \enum QskAspect::Variation

    \brief Some sort of variation

    The variation bits can be used to have different definitions for
    a skinnable depending on its position, orientation or emphasis. F.e a tab bar
    looks slightly different depending on its position. 

    \note flags indicating an orientation can't be used together
          with the flags for the position

    \sa QskSkinnable::effectiveVariation()

    \var QskAspect::Variation QskAspect::NoVariation
        No specific variation bits

    \var QskAspect::Variation QskAspect::Vertical
        Indicates a vertical orientation
        
    \var QskAspect::Variation QskAspect::Horizontal
        Indicates a horizontal orientation

    \var QskAspect::Variation QskAspect::Top
        Indicates a top position

    \var QskAspect::Variation QskAspect::Left
        Indicates a left position

    \var QskAspect::Variation QskAspect::Right
        Indicates a right position

    \var QskAspect::Variation QskAspect::Bottom
        Indicates a bottom position
*/

/*! 
    \enum QskAspect::Subcontrol

    \brief For use within the rendering or lay-outing of a specific QskSkinnable.

    While the Default value applies to any control (and can be used as a fallback),
    specifying a Subcontrol limits the aspect's scope to that sub-component
    (or \em subcontrol) of the control. For example, the Subcontrol type
    QskPushButton::Panel refers to the background panel of a push button.

    Beside the default values below subcontrols are defined and registered
    using the QSK_SUBCONTROL and QSK_SUBCONTROLS macros.

    \var QskAspect::Subcontrol QskAspect::Control
        No specific subcontrol - used as fallback when resolving skin hints

    \var QskAspect::Subcontrol QskAspect::LastSubcontrol
        Highest number that fits into the reserved bits for the subcontrol
*/

/*! 
    \enum QskAspect::State

    Applies to a given aspect when the control is in a given state.
    QskSkinnable subclasses (typically QskControl subclasses) can define UI
    states, as denoted by any OR combination of State flags. For example, a
    checked QskPushButton has the QskPushButton::Checked state flag set when
    it is checked.

    The skin hint resolving algorithms is removing the state bits one by one
    until it finds a match, what gives lower bits a higher priority. This
    is a rather obscure and error prone approach and needs to be replaced
    by something more user friendly. But until this has been done the state
    bits are divided into 3 sections:

        - [ QskAspect::FirstSystemState, QskAspect::FirstUserState [
            High priority state bits
        - [ QskAspect::FirstUserState, QskAspect::LastUserState ]
            State bits reserved for application code
        - ] QskAspect::LastUserState, QskAspect::LastSystemState ]
            Low priority state bits

    \var QskAspect::State QskAspect::NoState
        No specific state

    \var QskAspect::FirstSystemState QskAspect::FirstSystemState
        First bit of the high priority bits section

    \var QskAspect::FirstUserState QskAspect::FirstUserState
        First bit of the bits being reserved for application code

    \var QskAspect::LastUserState QskAspect::LastUserState
        Last bit of the bits being reserved for application code

    \var QskAspect::LastSystemState QskAspect::LastSystemState
        Highest state bit

    \var QskAspect::AllStates
        A bit mask for setting all state bits
*/

/*!
    \def QSK_SUBCONTROL
*/

/*!
    \def QSK_SUBCONTROLS
*/

/*!
    \fn QskAspect::QskAspect()

    Constructs an aspect with no bits being set.
*/

/*!
    \fn QskAspect::QskAspect( Subcontrol )

    Constructs an aspect with the subcontrol bits being initialized
    \param subControl Initial subcontrol
*/

/*!
    \fn QskAspect::QskAspect( Type )

    Constructs an aspect with the type bits being initialized
    \param type Initial type
*/

/*!
    \fn QskAspect::QskAspect( Variation )

    Constructs an aspect with the variation bits being initialized
    \param variation Initial variation
*/

/*!
    \fn QskAspect::QskAspect( const QskAspect& )

    Copy constructor
*/

/*!
    \fn QskAspect::QskAspect( QskAspect&& )

    Move constructor
*/

/*!
    \fn QskAspect::operator=( const QskAspect& )

    Assignment operator
*/

/*!
    \fn QskAspect::operator==( const QskAspect& )

    "Equal to" operator
    \sa operator!=(), operator<()
*/

/*!
    \fn QskAspect::operator!=( const QskAspect& )

    "Not equal to" operator
    \sa operator==(), operator<()
*/

/*!
    \fn QskAspect::operator<( const QskAspect& )

    "Less than" operator
*/

/*!
    \fn QskAspect::operator|( Subcontrol ) const

    Sets the subcontrol bits
*/

/*!
    \fn QskAspect::operator|( Type ) const

    Sets the type bits
*/

/*!
    \fn QskAspect::operator|( Primitive ) const

    Sets the primitive bits
*/

/*!
    \fn QskAspect::operator|( Variation ) const

    Sets the variation bits
*/

/*!
    \fn QskAspect::operator|( State ) const

    ORs state to the state bits
    \param state Additional state bit
*/

/*!
    \fn QskAspect::operator|( States ) const

    ORs states to the state bits
    \param states Additional state bits
*/
/*!
    \fn QskAspect::stateless

    \return A copy of the aspect without the state bits
*/

/*!
    \fn QskAspect::trunk

    \return A copy of the aspect without the runtime bits ( state, variation ) bits
*/

/*!
    \fn QskAspect::value

    \returns All bits interpreted as quint64
*/

/*!
    \fn QskAspect::isAnimator

    \return true, when the animator bit is set
*/

/*!
    \fn QskAspect::setAnimator

    Set/Clear the animator bit depending on on
*/

/*!
    \fn QskAspect::subControl

    \return Subcontrol bits
    \sa setSubControl()
*/

/*!
    \fn QskAspect::setSubControl

    Sets the subcontrol bits
    \sa subControl()
*/

/*!
    \fn QskAspect::type

    \return Type bits
    \sa setType()
*/

/*!
    \fn QskAspect::setType

    Sets the type bits
    \sa type()
*/

/*!
    \fn QskAspect::isMetric
    \return true, if type() equals to QskAspect::Metric
*/

/*!
    \fn QskAspect::isColor
    \return true, if type() equals to QskAspect::Color
*/

/*!
    \fn QskAspect::isFlag
    \return true, if type() equals to QskAspect::Flag
*/

/*!
    \fn QskAspect::variation

    \return Variation bits
    \sa setVariation()
*/

/*!
    \fn QskAspect::setVariation

    Sets the variation bits
    \sa variation()
*/

/*!
    \fn QskAspect::states

    \return State bits
    \sa setState()
*/

/*!
    \fn QskAspect::topState

    \return Topmost state bit
    \sa state()
*/

/*!
    \fn QskAspect::setStates

    Sets the state bits
    \sa addState(), clearState(), hasState(), state()
*/

/*!
    \fn QskAspect::addStates

    ORs state to the state bits
    \sa setState(), clearState(), hasState(), state()
*/

/*!
    \fn QskAspect::hasStates
    \return true, if any of the state bits is set
*/

/*!
    \fn QskAspect::clearState

    Clear the state bit for state
    \sa setState(), addState(), hasState(), state()
*/

/*!
    \fn QskAspect::clearStates

    Clears all state bits
    \sa clearState() setState(), addState(), hasState(), state()
*/

/*!
    \fn QskAspect::flagPrimitive
    \return primitive bits, when the aspect is a QskAspect::Flag 
*/

/*!
    \fn QskAspect::colorPrimitive
    \return primitive bits, when the aspect is a QskAspect::Color 
*/

/*!
    \fn QskAspect::metricPrimitive
    \return metric bits, when the aspect is a QskAspect::Metric 
*/

/*!
    \fn QskAspect::setPrimitive

    Sets the primitive bits
    \sa primitive(), clearPrimitive()
*/

/*!
    \fn QskAspect::primitive

    \return Primitive bits
    \sa setPrimitive(), clearPrimitive()
*/

/*!
    \fn QskAspect::clearPrimitive()

    Clears all primitive bits
    \sa setPrimitive(), primitive()
*/

/*!
    \fn QskAspect::toPrintable

    \return A printable string for debug purposes
    \note The string is internally stored in a buffer that gets reused
          every 10 calls. If the string is not only for an immediate
          debug statement it needs to be copied out.
*/

/*!
    \fn QskAspect::registerState

    Registers a printable string for a state.

    This method is called from the QSK_STATE and QSK_SYSTEM_STATE
    macros and is usually never called manually in application code
*/

/*!
    \fn QskAspect::nextSubcontrol

    \return Unique ( application wide ) identifier

    This method is called from the QSK_SUBCONTROL macro and is usually
    never called manually in application code
*/

/*!
    \fn QskAspect::subControlName

    \return Printable string for a specific subControl
*/

/*!
    \fn QskAspect::subControlNames
    \return Printable strings of all subControls for a class represented by metaObject
*/

/*!
    \fn QskAspect::subControls
    \return All subControls for a class represented by metaObject
*/

/*!
    \fn QskAspect::primitiveCount
*/

/*!
    \fn QskAspect::reservePrimitives
*/