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

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.

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

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

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

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

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
Generated by GTK-Doc V1.17