GTK+ 3 Reference Manual: GtkThemingEngine

## GtkThemingEngine GtkThemingEngine — Theming renderers |

## Synopsis

    #include <gtk/gtk.h>

    struct              GtkThemingEngineClass;
    struct              GtkThemingEngine;
    void                gtk_theming_engine_get              (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             ...);
    GtkTextDirection    gtk_theming_engine_get_direction    (GtkThemingEngine *engine);
    GtkJunctionSides    gtk_theming_engine_get_junction_sides
                                                            (GtkThemingEngine *engine);
    const GtkWidgetPath * gtk_theming_engine_get_path       (GtkThemingEngine *engine);
    void                gtk_theming_engine_get_property     (GtkThemingEngine *engine,
                                                             const gchar *property,
                                                             GtkStateFlags state,
                                                             GValue *value);
    GdkScreen *         gtk_theming_engine_get_screen       (GtkThemingEngine *engine);
    GtkStateFlags       gtk_theming_engine_get_state        (GtkThemingEngine *engine);
    void                gtk_theming_engine_get_style        (GtkThemingEngine *engine,
                                                             ...);
    void                gtk_theming_engine_get_style_property
                                                            (GtkThemingEngine *engine,
                                                             const gchar *property_name,
                                                             GValue *value);
    void                gtk_theming_engine_get_style_valist (GtkThemingEngine *engine,
                                                             va_list args);
    void                gtk_theming_engine_get_valist       (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             va_list args);
    void                gtk_theming_engine_get_color        (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GdkRGBA *color);
    void                gtk_theming_engine_get_background_color
                                                            (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GdkRGBA *color);
    void                gtk_theming_engine_get_border_color (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GdkRGBA *color);
    void                gtk_theming_engine_get_border       (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GtkBorder *border);
    void                gtk_theming_engine_get_padding      (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GtkBorder *padding);
    void                gtk_theming_engine_get_margin       (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GtkBorder *margin);
    const PangoFontDescription * gtk_theming_engine_get_font
                                                            (GtkThemingEngine *engine,
                                                             GtkStateFlags state);
    gboolean            gtk_theming_engine_has_class        (GtkThemingEngine *engine,
                                                             const gchar *style_class);
    gboolean            gtk_theming_engine_has_region       (GtkThemingEngine *engine,
                                                             const gchar *style_region,
                                                             GtkRegionFlags *flags);
    gboolean            gtk_theming_engine_lookup_color     (GtkThemingEngine *engine,
                                                             const gchar *color_name,
                                                             GdkRGBA *color);
    gboolean            gtk_theming_engine_state_is_running (GtkThemingEngine *engine,
                                                             GtkStateType state,
                                                             gdouble *progress);
    GtkThemingEngine *  gtk_theming_engine_load             (const gchar *name);
    void                gtk_theming_engine_register_property
                                                            (const gchar *name_space,
                                                             GtkStylePropertyParser parse_func,
                                                             GParamSpec *pspec);

## Object Hierarchy

      GObject
       +----GtkThemingEngine

## Properties

      "name"                     gchar*                : Read / Write / Construct Only

## Description

GtkThemingEngine is the object used for rendering themed content in GTK+ widgets. Even though GTK+ has a default implementation, it can be overridden in CSS files by enforcing a GtkThemingEngine object to be loaded as a module.

In order to implement a theming engine, a GtkThemingEngine subclass must be created, alongside the CSS file that will reference it, the theming engine would be created as an .so library, and installed in $(gtk-modules-dir)/theming-engines/.

GtkThemingEngines have limited access to the object they are rendering, the GtkThemingEngine API has read-only accessors to the style information contained in the rendered object's GtkStyleContext.

## Details

### struct GtkThemingEngineClass

    struct GtkThemingEngineClass {
      GObjectClass parent_class;

      void (* render_line) (GtkThemingEngine *engine,
                            cairo_t          *cr,
                            gdouble           x0,
                            gdouble           y0,
                            gdouble           x1,
                            gdouble           y1);
      void (* render_background) (GtkThemingEngine *engine,
                                  cairo_t          *cr,
                                  gdouble           x,
                                  gdouble           y,
                                  gdouble           width,
                                  gdouble           height);
      void (* render_frame) (GtkThemingEngine *engine,
                             cairo_t          *cr,
                             gdouble           x,
                             gdouble           y,
                             gdouble           width,
                             gdouble           height);
      void (* render_frame_gap) (GtkThemingEngine *engine,
                                 cairo_t          *cr,
                                 gdouble           x,
                                 gdouble           y,
                                 gdouble           width,
                                 gdouble           height,
                                 GtkPositionType   gap_side,
                                 gdouble           xy0_gap,
                                 gdouble           xy1_gap);
      void (* render_extension) (GtkThemingEngine *engine,
                                 cairo_t          *cr,
                                 gdouble           x,
                                 gdouble           y,
                                 gdouble           width,
                                 gdouble           height,
                                 GtkPositionType   gap_side);
      void (* render_check) (GtkThemingEngine *engine,
                             cairo_t          *cr,
                             gdouble           x,
                             gdouble           y,
                             gdouble           width,
                             gdouble           height);
      void (* render_option) (GtkThemingEngine *engine,
                              cairo_t          *cr,
                              gdouble           x,
                              gdouble           y,
                              gdouble           width,
                              gdouble           height);
      void (* render_arrow) (GtkThemingEngine *engine,
                             cairo_t          *cr,
                             gdouble           angle,
                             gdouble           x,
                             gdouble           y,
                             gdouble           size);
      void (* render_expander) (GtkThemingEngine *engine,
                                cairo_t          *cr,
                                gdouble           x,
                                gdouble           y,
                                gdouble           width,
                                gdouble           height);
      void (* render_focus) (GtkThemingEngine *engine,
                             cairo_t          *cr,
                             gdouble           x,
                             gdouble           y,
                             gdouble           width,
                             gdouble           height);
      void (* render_layout) (GtkThemingEngine *engine,
                              cairo_t          *cr,
                              gdouble           x,
                              gdouble           y,
                              PangoLayout      *layout);
      void (* render_slider) (GtkThemingEngine *engine,
                              cairo_t          *cr,
                              gdouble           x,
                              gdouble           y,
                              gdouble           width,
                              gdouble           height,
                              GtkOrientation    orientation);
      void (* render_handle)    (GtkThemingEngine *engine,
                                 cairo_t          *cr,
                                 gdouble           x,
                                 gdouble           y,
                                 gdouble           width,
                                 gdouble           height);
      void (* render_activity) (GtkThemingEngine *engine,
                                cairo_t          *cr,
                                gdouble           x,
                                gdouble           y,
                                gdouble           width,
                                gdouble           height);

      GdkPixbuf * (* render_icon_pixbuf) (GtkThemingEngine    *engine,
                                          const GtkIconSource *source,
                                          GtkIconSize          size);
      void (* render_icon) (GtkThemingEngine *engine,
                            cairo_t          *cr,
    			GdkPixbuf        *pixbuf,
                            gdouble           x,
                            gdouble           y);
      void (* render_icon_surface) (GtkThemingEngine *engine,
    				cairo_t          *cr,
    				cairo_surface_t  *surface,
    				gdouble           x,
    				gdouble           y);
    };

Base class for theming engines.

GObjectClass `parent_class`; | The parent class.
`render_line` () | Renders a line between two points.
`render_background` () | Renders the background area of a widget region.
`render_frame` () | Renders the frame around a widget area.
`render_frame_gap` () | Renders the frame around a widget area with a gap in it.
`render_extension` () | Renders a extension to a box, usually a notebook tab.
`render_check` () | Renders a checkmark, as in GtkCheckButton.
`render_option` () | Renders an option, as in GtkRadioButton.
`render_arrow` () | Renders an arrow pointing to a certain direction.
`render_expander` () | Renders an element what will expose/expand part of the UI, as in GtkExpander.
`render_focus` () | Renders the focus indicator.
`render_layout` () | Renders a PangoLayout
`render_slider` () | Renders a slider control, as in GtkScale.
`render_handle` () | Renders a handle to drag UI elements, as in GtkPaned.
`render_activity` () | Renders an area displaying activity, such as in GtkSpinner, or GtkProgressBar.
`render_icon_pixbuf` () | Renders an icon as a GdkPixbuf.
`render_icon` () | Renders an icon given as a GdkPixbuf.
`render_icon_surface` () | Renders an icon given as a cairo_surface_t.

### struct GtkThemingEngine

    struct GtkThemingEngine;

### gtk_theming_engine_get ()

    void                gtk_theming_engine_get              (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             ...);

Retrieves several style property values that apply to the currently rendered element.

`engine` : | a GtkThemingEngine
`state` : | state to retrieve values for
`...` : | property name /return value pairs, followed by `NULL`

Since 3.0

### gtk_theming_engine_get_direction ()

    GtkTextDirection    gtk_theming_engine_get_direction    (GtkThemingEngine *engine);

### Warning

`gtk_theming_engine_get_direction` has been deprecated since version 3.8 and should not be used in newly-written code. Use `gtk_theming_engine_get_state()` and check for GTK_STATE_FLAG_DIR_LTR and GTK_STATE_FLAG_DIR_RTL instead.

Returns the widget direction used for rendering.

`engine` : | a GtkThemingEngine
Returns : | the widget direction

Since 3.0

### gtk_theming_engine_get_junction_sides ()

    GtkJunctionSides    gtk_theming_engine_get_junction_sides
                                                            (GtkThemingEngine *engine);

Returns the widget direction used for rendering.

`engine` : | a GtkThemingEngine
Returns : | the widget direction

Since 3.0

### gtk_theming_engine_get_path ()

    const GtkWidgetPath * gtk_theming_engine_get_path       (GtkThemingEngine *engine);

Returns the widget path used for style matching.

`engine` : | a GtkThemingEngine
Returns : | A GtkWidgetPath. [transfer none]

Since 3.0

### gtk_theming_engine_get_property ()

    void                gtk_theming_engine_get_property     (GtkThemingEngine *engine,
                                                             const gchar *property,
                                                             GtkStateFlags state,
                                                             GValue *value);

Gets a property value as retrieved from the style settings that apply to the currently rendered element.

`engine` : | a GtkThemingEngine
`property` : | the property name
`state` : | state to retrieve the value for
`value` : | return location for the property value, you must free this memory using `g_value_unset()` once you are done with it. [out][transfer full]

Since 3.0

### gtk_theming_engine_get_screen ()

    GdkScreen *         gtk_theming_engine_get_screen       (GtkThemingEngine *engine);

Returns the GdkScreen to which `engine` currently rendering to.

`engine` : | a GtkThemingEngine
Returns : | a GdkScreen, or `NULL`. [transfer none]

### gtk_theming_engine_get_state ()

    GtkStateFlags       gtk_theming_engine_get_state        (GtkThemingEngine *engine);

returns the state used when rendering.

`engine` : | a GtkThemingEngine
Returns : | the state flags

Since 3.0

### gtk_theming_engine_get_style ()

    void                gtk_theming_engine_get_style        (GtkThemingEngine *engine,
                                                             ...);

Retrieves several widget style properties from `engine` according to the currently rendered content's style.

`engine` : | a GtkThemingEngine
`...` : | property name /return value pairs, followed by `NULL`

Since 3.0

### gtk_theming_engine_get_style_property ()

    void                gtk_theming_engine_get_style_property
                                                            (GtkThemingEngine *engine,
                                                             const gchar *property_name,
                                                             GValue *value);

Gets the value for a widget style property.

`engine` : | a GtkThemingEngine
`property_name` : | the name of the widget style property
`value` : | Return location for the property value, free with `g_value_unset()` after use.

Since 3.0

### gtk_theming_engine_get_style_valist ()

    void                gtk_theming_engine_get_style_valist (GtkThemingEngine *engine,
                                                             va_list args);

Retrieves several widget style properties from `engine` according to the currently rendered content's style.

`engine` : | a GtkThemingEngine
`args` : | va_list of property name/return location pairs, followed by `NULL`

Since 3.0

### gtk_theming_engine_get_valist ()

    void                gtk_theming_engine_get_valist       (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             va_list args);

Retrieves several style property values that apply to the currently rendered element.

`engine` : | a GtkThemingEngine
`state` : | state to retrieve values for
`args` : | va_list of property name/return location pairs, followed by `NULL`

Since 3.0

### gtk_theming_engine_get_color ()

    void                gtk_theming_engine_get_color        (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GdkRGBA *color);

Gets the foreground color for a given state.

`engine` : | a GtkThemingEngine
`state` : | state to retrieve the color for
`color` : | return value for the foreground color. [out]

Since 3.0

### gtk_theming_engine_get_background_color ()

    void                gtk_theming_engine_get_background_color
                                                            (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GdkRGBA *color);

Gets the background color for a given state.

`engine` : | a GtkThemingEngine
`state` : | state to retrieve the color for
`color` : | return value for the background color. [out]

Since 3.0

### gtk_theming_engine_get_border_color ()

    void                gtk_theming_engine_get_border_color (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GdkRGBA *color);

Gets the border color for a given state.

`engine` : | a GtkThemingEngine
`state` : | state to retrieve the color for
`color` : | return value for the border color. [out]

Since 3.0

### gtk_theming_engine_get_border ()

    void                gtk_theming_engine_get_border       (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GtkBorder *border);

Gets the border for a given state as a GtkBorder.

`engine` : | a GtkThemingEngine
`state` : | state to retrieve the border for
`border` : | return value for the border settings. [out]

Since 3.0

### gtk_theming_engine_get_padding ()

    void                gtk_theming_engine_get_padding      (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GtkBorder *padding);

Gets the padding for a given state as a GtkBorder.

`engine` : | a GtkThemingEngine
`state` : | state to retrieve the padding for
`padding` : | return value for the padding settings. [out]

Since 3.0

### gtk_theming_engine_get_margin ()

    void                gtk_theming_engine_get_margin       (GtkThemingEngine *engine,
                                                             GtkStateFlags state,
                                                             GtkBorder *margin);

Gets the margin for a given state as a GtkBorder.

`engine` : | a GtkThemingEngine
`state` : | state to retrieve the border for
`margin` : | return value for the margin settings. [out]

Since 3.0

### gtk_theming_engine_get_font ()

    const PangoFontDescription * gtk_theming_engine_get_font
                                                            (GtkThemingEngine *engine,
                                                             GtkStateFlags state);

### Warning

`gtk_theming_engine_get_font` has been deprecated since version 3.8 and should not be used in newly-written code. Use `gtk_theming_engine_get()`

Returns the font description for a given state.

`engine` : | a GtkThemingEngine
`state` : | state to retrieve the font for
Returns : | the PangoFontDescription for the given state. This object is owned by GTK+ and should not be freed. [transfer none]

Since 3.0

### gtk_theming_engine_has_class ()

    gboolean            gtk_theming_engine_has_class        (GtkThemingEngine *engine,
                                                             const gchar *style_class);

Returns `TRUE` if the currently rendered contents have defined the given class name.

`engine` : | a GtkThemingEngine
`style_class` : | class name to look up
Returns : | `TRUE` if `engine` has `class_name` defined

Since 3.0

### gtk_theming_engine_has_region ()

    gboolean            gtk_theming_engine_has_region       (GtkThemingEngine *engine,
                                                             const gchar *style_region,
                                                             GtkRegionFlags *flags);

Returns `TRUE` if the currently rendered contents have the region defined. If `flags_return` is not `NULL`, it is set to the flags affecting the region.

`engine` : | a GtkThemingEngine
`style_region` : | a region name
`flags` : | return location for region flags. [out][allow-none]
Returns : | `TRUE` if region is defined

Since 3.0

### gtk_theming_engine_lookup_color ()

    gboolean            gtk_theming_engine_lookup_color     (GtkThemingEngine *engine,
                                                             const gchar *color_name,
                                                             GdkRGBA *color);

Looks up and resolves a color name in the current style's color map.

`engine` : | a GtkThemingEngine
`color_name` : | color name to lookup
`color` : | Return location for the looked up color. [out]
Returns : | `TRUE` if `color_name` was found and resolved, `FALSE` otherwise

### gtk_theming_engine_state_is_running ()

    gboolean            gtk_theming_engine_state_is_running (GtkThemingEngine *engine,
                                                             GtkStateType state,
                                                             gdouble *progress);

### Warning

`gtk_theming_engine_state_is_running` has been deprecated since version 3.6 and should not be used in newly-written code. Always returns `FALSE`

Returns `TRUE` if there is a transition animation running for the current region (see `gtk_style_context_push_animatable_region()`).

If `progress` is not `NULL`, the animation progress will be returned there, 0.0 means the state is closest to being `FALSE`, while 1.0 means it's closest to being `TRUE`. This means transition animations will run from 0 to 1 when `state` is being set to `TRUE` and from 1 to 0 when it's being set to `FALSE`.

`engine` : | a GtkThemingEngine
`state` : | a widget state
`progress` : | return location for the transition progress. [out]
Returns : | `TRUE` if there is a running transition animation for `state`.

Since 3.0

### gtk_theming_engine_load ()

    GtkThemingEngine *  gtk_theming_engine_load             (const gchar *name);

Loads and initializes a theming engine module from the standard directories.

`name` : | Theme engine name to load
Returns : | A theming engine, or `NULL` if the engine `name` doesn't exist. [transfer none]

### gtk_theming_engine_register_property ()

    void                gtk_theming_engine_register_property
                                                            (const gchar *name_space,
                                                             GtkStylePropertyParser parse_func,
                                                             GParamSpec *pspec);

### Warning

`gtk_theming_engine_register_property` has been deprecated since version 3.8 and should not be used in newly-written code. Code should use the default properties provided by CSS.

Registers a property so it can be used in the CSS file format, on the CSS file the property will look like "-${`name_space`}-${property_name}". being ${property_name} the given to `pspec`. `name_space` will usually be the theme engine name.

For any type a `parse_func` may be provided, being this function used for turning any property value (between ':' and ';') in CSS to the GValue needed. For basic types there is already builtin parsing support, so `NULL` may be provided for these cases.

### Note

Engines must ensure property registration happens exactly once, usually GTK+ deals with theming engines as singletons, so this should be guaranteed to happen once, but bear this in mind when creating GtkThemeEngines yourself.

### Note

In order to make use of the custom registered properties in the CSS file, make sure the engine is loaded first by specifying the engine property, either in a previous rule or within the same one.

    * {
        engine: someengine;
        -SomeEngine-custom-property: 2;
    }

`name_space` : | namespace for the property name
`parse_func` : | parsing function to use, or `NULL`
`pspec` : | the GParamSpec for the new property

Since 3.0

## Property Details

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

The theming engine name, this name will be used when registering custom properties, for a theming engine named "Clearlooks" registering a "glossy" custom property, it could be referenced in the CSS file as

    -Clearlooks-glossy: true;

Default value: NULL

Since 3.0

## See Also

GtkStyleContext