GtkThemingEngine: GTK+ 3 Reference Manual

## GtkThemingEngine GtkThemingEngine — Theming renderers |

## Functions

void | gtk_theming_engine_get ()
GtkTextDirection | gtk_theming_engine_get_direction ()
GtkJunctionSides | gtk_theming_engine_get_junction_sides ()
const GtkWidgetPath * | gtk_theming_engine_get_path ()
void | gtk_theming_engine_get_property ()
GdkScreen * | gtk_theming_engine_get_screen ()
GtkStateFlags | gtk_theming_engine_get_state ()
void | gtk_theming_engine_get_style ()
void | gtk_theming_engine_get_style_property ()
void | gtk_theming_engine_get_style_valist ()
void | gtk_theming_engine_get_valist ()
void | gtk_theming_engine_get_color ()
void | gtk_theming_engine_get_background_color ()
void | gtk_theming_engine_get_border_color ()
void | gtk_theming_engine_get_border ()
void | gtk_theming_engine_get_padding ()
void | gtk_theming_engine_get_margin ()
const PangoFontDescription * | gtk_theming_engine_get_font ()
gboolean | gtk_theming_engine_has_class ()
gboolean | gtk_theming_engine_has_region ()
gboolean | gtk_theming_engine_lookup_color ()
gboolean | gtk_theming_engine_state_is_running ()
GtkThemingEngine * | gtk_theming_engine_load ()
void | gtk_theming_engine_register_property ()

## Properties

gchar * | name | Read / Write / Construct Only

## Types and Values

struct | GtkThemingEngineClass
struct | GtkThemingEngine

## Object Hierarchy

        GObject
        ╰── GtkThemingEngine

## Includes

    #include <gtk/gtk.h>

## Description

GtkThemingEngine was the object used for rendering themed content in GTK+ widgets. It used to allow overriding GTK+'s default implementation of rendering functions by allowing engines to be loaded as modules.

GtkThemingEngine has been deprecated in GTK+ 3.14 and will be ignored for rendering. The advancements in CSS theming are good enough to allow themers to achieve their goals without the need to modify source code.

## Functions

### gtk_theming_engine_get ()

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

`gtk_theming_engine_get` has been deprecated since version 3.14 and should not be used in newly-written code.

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

#### Parameters

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);

`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.

#### Parameters

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);

`gtk_theming_engine_get_junction_sides` has been deprecated since version 3.14 and should not be used in newly-written code.

Returns the widget direction used for rendering.

#### Parameters

engine | a GtkThemingEngine |

#### Returns

the widget direction

Since: 3.0

### gtk_theming_engine_get_path ()

    const GtkWidgetPath *
    gtk_theming_engine_get_path (GtkThemingEngine *engine);

`gtk_theming_engine_get_path` has been deprecated since version 3.14 and should not be used in newly-written code.

Returns the widget path used for style matching.

#### Parameters

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);

`gtk_theming_engine_get_property` has been deprecated since version 3.14 and should not be used in newly-written code.

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

#### Parameters

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);

`gtk_theming_engine_get_screen` has been deprecated since version 3.14 and should not be used in newly-written code.

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

#### Parameters

engine | a GtkThemingEngine |

#### Returns

a GdkScreen, or `NULL`.

[transfer none]

### gtk_theming_engine_get_state ()

    GtkStateFlags
    gtk_theming_engine_get_state (GtkThemingEngine *engine);

`gtk_theming_engine_get_state` has been deprecated since version 3.14 and should not be used in newly-written code.

returns the state used when rendering.

#### Parameters

engine | a GtkThemingEngine |

#### Returns

the state flags

Since: 3.0

### gtk_theming_engine_get_style ()

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

`gtk_theming_engine_get_style` has been deprecated since version 3.14 and should not be used in newly-written code.

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

#### Parameters

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);

`gtk_theming_engine_get_style_property` has been deprecated since version 3.14 and should not be used in newly-written code.

Gets the value for a widget style property.

#### Parameters

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. | [out]

Since: 3.0

### gtk_theming_engine_get_style_valist ()

    void
    gtk_theming_engine_get_style_valist (GtkThemingEngine *engine,
                                         va_list args);

`gtk_theming_engine_get_style_valist` has been deprecated since version 3.14 and should not be used in newly-written code.

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

#### Parameters

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);

`gtk_theming_engine_get_valist` has been deprecated since version 3.14 and should not be used in newly-written code.

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

#### Parameters

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);

`gtk_theming_engine_get_color` has been deprecated since version 3.14 and should not be used in newly-written code.

Gets the foreground color for a given state.

#### Parameters

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);

`gtk_theming_engine_get_background_color` has been deprecated since version 3.14 and should not be used in newly-written code.

Gets the background color for a given state.

#### Parameters

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);

`gtk_theming_engine_get_border_color` has been deprecated since version 3.14 and should not be used in newly-written code.

Gets the border color for a given state.

#### Parameters

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);

`gtk_theming_engine_get_border` has been deprecated since version 3.14 and should not be used in newly-written code.

Gets the border for a given state as a GtkBorder.

#### Parameters

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);

`gtk_theming_engine_get_padding` has been deprecated since version 3.14 and should not be used in newly-written code.

Gets the padding for a given state as a GtkBorder.

#### Parameters

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);

`gtk_theming_engine_get_margin` has been deprecated since version 3.14 and should not be used in newly-written code.

Gets the margin for a given state as a GtkBorder.

#### Parameters

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);

`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.

#### Parameters

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);

`gtk_theming_engine_has_class` has been deprecated since version 3.14 and should not be used in newly-written code.

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

#### Parameters

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);

`gtk_theming_engine_has_region` has been deprecated since version 3.14 and should not be used in newly-written code.

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.

#### Parameters

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);

`gtk_theming_engine_lookup_color` has been deprecated since version 3.14 and should not be used in newly-written code.

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

#### Parameters

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

Since: 3.0

### gtk_theming_engine_state_is_running ()

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

`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`.

#### Parameters

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);

`gtk_theming_engine_load` has been deprecated since version 3.14 and should not be used in newly-written code.

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

#### Parameters

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);

`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.

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.

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.

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

[skip]

#### Parameters

name_space | namespace for the property name |
parse_func | parsing function to use, or `NULL`. | [nullable]
pspec | the GParamSpec for the new property |

Since: 3.0

## Types and Values

### 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.

#### Members

`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;

## Property Details

### The `“name”` property

      “name”                     gchar *

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

    1
    -Clearlooks-glossy: true;

Flags: Read / Write / Construct Only

Default value: NULL

Since: 3.0

## See Also

GtkStyleContext