.. _gui_style:

Style
-----

.. structure:: Style

    This object represents the style of a widget. Styles can be either changed directly
    on a :struct:`Widget`, or changed on the GUI:SKIN so as to affect all subsequently
    created widgets of a particular type inside that GUI.

    ===================================== =============================== =============
    Suffix                                Type                            Description
    ===================================== =============================== =============
    :attr:`HSTRETCH`                      :struct:`Boolean`               Should the widget stretch horizontally? (default depends on widget subclass)
    :attr:`VSTRETCH`                      :struct:`Boolean`               Should the widget stretch vertically?
    :attr:`WIDTH`                         :struct:`scalar` (pixels)       Fixed width (or 0 if flexible).
    :attr:`HEIGHT`                        :struct:`scalar` (pixels)       Fixed height (or 0 if flexible).
    :attr:`MARGIN`                        :struct:`StyleRectOffset`       Spacing between this and other widgets.
    :attr:`PADDING`                       :struct:`StyleRectOffset`       Spacing between the outside of the widget and its contents (text, etc.).
    :attr:`BORDER`                        :struct:`StyleRectOffset`       Size of the edges in the 9-slice image for BG images in NORMAL, HOVER, etc.
    :attr:`OVERFLOW`                      :struct:`StyleRectOffset`       Extra space added to the area of the background image. Allows the background to go beyond the widget's rectangle.
    :attr:`ALIGN`                         :struct:`string`                One of "CENTER", "LEFT", or "RIGHT". See note below.
    :attr:`FONT`                          :struct:`string`                The name of the font of the text on the content or "" if the default.
    :attr:`FONTSIZE`                      :struct:`scalar`                The size of the text on the content.
    :attr:`RICHTEXT`                      :struct:`Boolean`               Set to False to disable rich-text (<i>...</i>, etc.)
    :attr:`NORMAL`                        :struct:`StyleState`            Properties for the widget normally.
    :attr:`ON`                            :struct:`StyleState`            Properties for when the widget is under the mouse and "on".
    :attr:`NORMAL_ON`                     :struct:`StyleState`            Alias for ON.
    :attr:`HOVER`                         :struct:`StyleState`            Properties for when the widget is under the mouse.
    :attr:`HOVER_ON`                      :struct:`StyleState`            Properties for when the widget is under the mouse and "on".
    :attr:`ACTIVE`                        :struct:`StyleState`            Properties for when the widget is active (eg. button being held down).
    :attr:`ACTIVE_ON`                     :struct:`StyleState`            Properties for when the widget is active and "on".
    :attr:`FOCUSED`                       :struct:`StyleState`            Properties for when the widget has keyboard focus.
    :attr:`FOCUSED_ON`                    :struct:`StyleState`            Properties for when the widget has keyboard focus and is "on".
    :attr:`BG`                            :struct:`string`                The same as NORMAL:BG. Name of a "9-slice" image file.
    :attr:`TEXTCOLOR`                     :ref:`Color <colors>`           The same as NORMAL:TEXTCOLOR. The color of the text on the label.
    ===================================== =============================== =============

    .. attribute:: HSTRETCH

        :type: :struct:`Boolean`
        :access: Get/Set

        Should the widget stretch horizontally? (default depends on widget subclass)

    .. attribute:: VSTRETCH

        :type: :struct:`Boolean`
        :access: Get/Set

        Should the widget stretch vertically?

    .. attribute:: WIDTH

        :type: :struct:`scalar`
        :access: Get/Set

        (pixels)       Fixed width (or 0 if flexible).

    .. attribute:: HEIGHT

        :type: :struct:`scalar`
        :access: Get/Set

        (pixels)       Fixed height (or 0 if flexible).

    .. attribute:: MARGIN

        :type: :struct:`StyleRectOffset`
        :access: Get/Set

        Spacing between this and other widgets.

    .. attribute:: PADDING

        :type: :struct:`StyleRectOffset`
        :access: Get/Set

        Spacing between the outside of the widget and its contents (text, etc.).

    .. attribute:: BORDER

        :type: :struct:`StyleRectOffset`
        :access: Get/Set

        Size of the edges in the 9-slice image for BG images in NORMAL, HOVER, etc.

    .. attribute:: OVERFLOW

        :type: :struct:`StyleRectOffset`
        :access: Get/Set

        Extra space added to the area of the background image. Allows the background to go beyond the widget's rectangle.

    .. attribute:: ALIGN

        :type: :struct:`string`
        :access: Get/Set

        One of "CENTER", "LEFT", or "RIGHT".

    .. note::

        The ALIGN attribute will not do anything useful unless either HSTRETCH is set to true or a fixed WIDTH is set,
        since otherwise it will be exactly the right size to fit the content of the widget with no alignment within that space being necessary.

        It is currently only relevant for the widgets that have scalar content (Label and subclasses).


    .. attribute:: FONT

        :type: :struct:`string`
        :access: Get/Set

        The name of the font of the text on the content or "" if the default.

    .. attribute:: FONTSIZE

        :type: :struct:`scalar`
        :access: Get/Set

        The size of the text on the content.

    .. attribute:: RICHTEXT

        :type: :struct:`Boolean`
        :access: Get/Set

        Set to False to disable rich-text (<i>...</i>, etc.)

    .. attribute:: NORMAL

        :type: :struct:`StyleState`
        :access: Get/Set

        Properties for the widget normally.

    .. attribute:: ON

        :type: :struct:`StyleState`
        :access: Get/Set

        Properties for when the widget is under the mouse and "on".

    .. attribute:: NORMAL_ON

        :type: :struct:`StyleState`
        :access: Get/Set

        Alias for ON.

    .. attribute:: HOVER

        :type: :struct:`StyleState`
        :access: Get/Set

        Properties for when the widget is under the mouse.

    .. attribute:: HOVER_ON

        :type: :struct:`StyleState`
        :access: Get/Set

        Properties for when the widget is under the mouse and "on".

    .. attribute:: ACTIVE

        :type: :struct:`StyleState`
        :access: Get/Set

        Properties for when the widget is active (eg. button being held down).

    .. attribute:: ACTIVE_ON

        :type: :struct:`StyleState`
        :access: Get/Set

        Properties for when the widget is active and "on".

    .. attribute:: FOCUSED

        :type: :struct:`StyleState`
        :access: Get/Set

        Properties for when the widget has keyboard focus.

    .. attribute:: FOCUSED_ON

        :type: :struct:`StyleState`
        :access: Get/Set

        Properties for when the widget has keyboard focus and is "on".

    .. attribute:: BG

        :type: :struct:`string`
        :access: Get/Set

        The same as NORMAL:BG. Name of a "9-slice" image file.

    .. attribute:: TEXTCOLOR
    
        :type: :strucT:`color`
        
        The same as NORMAL:TEXTCOLOR. The color of the text on the label.