CtkThemingEngine: CTK+ 3 Reference Manual

CtkThemingEngine

CtkThemingEngine — Theming renderers

Functions

void	ctk_theming_engine_get ()
CtkTextDirection	ctk_theming_engine_get_direction ()
CtkJunctionSides	ctk_theming_engine_get_junction_sides ()
const CtkWidgetPath *	ctk_theming_engine_get_path ()
void	ctk_theming_engine_get_property ()
CdkScreen *	ctk_theming_engine_get_screen ()
CtkStateFlags	ctk_theming_engine_get_state ()
void	ctk_theming_engine_get_style ()
void	ctk_theming_engine_get_style_property ()
void	ctk_theming_engine_get_style_valist ()
void	ctk_theming_engine_get_valist ()
void	ctk_theming_engine_get_color ()
void	ctk_theming_engine_get_background_color ()
void	ctk_theming_engine_get_border_color ()
void	ctk_theming_engine_get_border ()
void	ctk_theming_engine_get_padding ()
void	ctk_theming_engine_get_margin ()
const PangoFontDescription *	ctk_theming_engine_get_font ()
gboolean	ctk_theming_engine_has_class ()
gboolean	ctk_theming_engine_has_region ()
gboolean	ctk_theming_engine_lookup_color ()
gboolean	ctk_theming_engine_state_is_running ()
CtkThemingEngine *	ctk_theming_engine_load ()
void	ctk_theming_engine_register_property ()

Properties

char *

name

Read / Write / Construct Only

Types and Values

struct	CtkThemingEngineClass
struct	CtkThemingEngine

Object Hierarchy

    GObject
    ╰── CtkThemingEngine

Includes

#include <ctk/ctk.h>

Description

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

CtkThemingEngine has been deprecated in CTK+ 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

ctk_theming_engine_get ()

void
ctk_theming_engine_get (CtkThemingEngine *engine,
                        CtkStateFlags state,
                        ...);

ctk_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 CtkThemingEngine
state	state to retrieve values for
...	property name /return value pairs, followed by `NULL`

Since: 3.0

ctk_theming_engine_get_direction ()

CtkTextDirection
ctk_theming_engine_get_direction (CtkThemingEngine *engine);

ctk_theming_engine_get_direction has been deprecated since version 3.8 and should not be used in newly-written code.

Use ctk_theming_engine_get_state() and check for CTK_STATE_FLAG_DIR_LTR and CTK_STATE_FLAG_DIR_RTL instead.

Returns the widget direction used for rendering.

Parameters

engine

a CtkThemingEngine

Returns

the widget direction

Since: 3.0

ctk_theming_engine_get_junction_sides ()

CtkJunctionSides
ctk_theming_engine_get_junction_sides (CtkThemingEngine *engine);

ctk_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 CtkThemingEngine

Returns

the widget direction

Since: 3.0

ctk_theming_engine_get_path ()

const CtkWidgetPath *
ctk_theming_engine_get_path (CtkThemingEngine *engine);

ctk_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 CtkThemingEngine

Returns

A CtkWidgetPath.

[transfer none]

Since: 3.0

ctk_theming_engine_get_property ()

void
ctk_theming_engine_get_property (CtkThemingEngine *engine,
                                 const gchar *property,
                                 CtkStateFlags state,
                                 GValue *value);

ctk_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 CtkThemingEngine
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

ctk_theming_engine_get_screen ()

CdkScreen *
ctk_theming_engine_get_screen (CtkThemingEngine *engine);

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

Returns the CdkScreen to which engine currently rendering to.

Parameters

engine

a CtkThemingEngine

Returns

a CdkScreen, or NULL.

[nullable][transfer none]

ctk_theming_engine_get_state ()

CtkStateFlags
ctk_theming_engine_get_state (CtkThemingEngine *engine);

ctk_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 CtkThemingEngine

Returns

the state flags

Since: 3.0

ctk_theming_engine_get_style ()

void
ctk_theming_engine_get_style (CtkThemingEngine *engine,
                              ...);

ctk_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 CtkThemingEngine
...	property name /return value pairs, followed by `NULL`

Since: 3.0

ctk_theming_engine_get_style_property ()

void
ctk_theming_engine_get_style_property (CtkThemingEngine *engine,
                                       const gchar *property_name,
                                       GValue *value);

ctk_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 CtkThemingEngine
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

ctk_theming_engine_get_style_valist ()

void
ctk_theming_engine_get_style_valist (CtkThemingEngine *engine,
                                     va_list args);

ctk_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 CtkThemingEngine
args	va_list of property name/return location pairs, followed by `NULL`

Since: 3.0

ctk_theming_engine_get_valist ()

void
ctk_theming_engine_get_valist (CtkThemingEngine *engine,
                               CtkStateFlags state,
                               va_list args);

ctk_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 CtkThemingEngine
state	state to retrieve values for
args	va_list of property name/return location pairs, followed by `NULL`

Since: 3.0

ctk_theming_engine_get_color ()

void
ctk_theming_engine_get_color (CtkThemingEngine *engine,
                              CtkStateFlags state,
                              CdkRGBA *color);

ctk_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 CtkThemingEngine
state	state to retrieve the color for
color	return value for the foreground color.	[out]

Since: 3.0

ctk_theming_engine_get_background_color ()

void
ctk_theming_engine_get_background_color
                               (CtkThemingEngine *engine,
                                CtkStateFlags state,
                                CdkRGBA *color);

ctk_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 CtkThemingEngine
state	state to retrieve the color for
color	return value for the background color.	[out]

Since: 3.0

ctk_theming_engine_get_border_color ()

void
ctk_theming_engine_get_border_color (CtkThemingEngine *engine,
                                     CtkStateFlags state,
                                     CdkRGBA *color);

ctk_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 CtkThemingEngine
state	state to retrieve the color for
color	return value for the border color.	[out]

Since: 3.0

ctk_theming_engine_get_border ()

void
ctk_theming_engine_get_border (CtkThemingEngine *engine,
                               CtkStateFlags state,
                               CtkBorder *border);

ctk_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 CtkBorder.

Parameters

engine	a CtkThemingEngine
state	state to retrieve the border for
border	return value for the border settings.	[out]

Since: 3.0

ctk_theming_engine_get_padding ()

void
ctk_theming_engine_get_padding (CtkThemingEngine *engine,
                                CtkStateFlags state,
                                CtkBorder *padding);

ctk_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 CtkBorder.

Parameters

engine	a CtkThemingEngine
state	state to retrieve the padding for
padding	return value for the padding settings.	[out]

Since: 3.0

ctk_theming_engine_get_margin ()

void
ctk_theming_engine_get_margin (CtkThemingEngine *engine,
                               CtkStateFlags state,
                               CtkBorder *margin);

ctk_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 CtkBorder.

Parameters

engine	a CtkThemingEngine
state	state to retrieve the border for
margin	return value for the margin settings.	[out]

Since: 3.0

ctk_theming_engine_get_font ()

const PangoFontDescription *
ctk_theming_engine_get_font (CtkThemingEngine *engine,
                             CtkStateFlags state);

ctk_theming_engine_get_font has been deprecated since version 3.8 and should not be used in newly-written code.

Use ctk_theming_engine_get()

Returns the font description for a given state.

Parameters

engine	a CtkThemingEngine
state	state to retrieve the font for

Returns

the PangoFontDescription for the given state. This object is owned by CTK+ and should not be freed.

[transfer none]

Since: 3.0

ctk_theming_engine_has_class ()

gboolean
ctk_theming_engine_has_class (CtkThemingEngine *engine,
                              const gchar *style_class);

ctk_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 CtkThemingEngine
style_class	class name to look up

Returns

TRUE if engine has class_name defined

Since: 3.0

ctk_theming_engine_has_region ()

gboolean
ctk_theming_engine_has_region (CtkThemingEngine *engine,
                               const gchar *style_region,
                               CtkRegionFlags *flags);

ctk_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 CtkThemingEngine
style_region	a region name
flags	return location for region flags.	[out][allow-none]

Returns

TRUE if region is defined

Since: 3.0

ctk_theming_engine_lookup_color ()

gboolean
ctk_theming_engine_lookup_color (CtkThemingEngine *engine,
                                 const gchar *color_name,
                                 CdkRGBA *color);

ctk_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 CtkThemingEngine
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

ctk_theming_engine_state_is_running ()

gboolean
ctk_theming_engine_state_is_running (CtkThemingEngine *engine,
                                     CtkStateType state,
                                     gdouble *progress);

ctk_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 ctk_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 CtkThemingEngine
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

ctk_theming_engine_load ()

CtkThemingEngine *
ctk_theming_engine_load (const gchar *name);

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

[nullable][transfer none]

ctk_theming_engine_register_property ()

void
ctk_theming_engine_register_property (const gchar *name_space,
                                      CtkStylePropertyParser parse_func,
                                      GParamSpec *pspec);

ctk_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 CTK+ deals with theming engines as singletons, so this should be guaranteed to happen once, but bear this in mind when creating CtkThemeEngines 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.

* {
    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 CtkThemingEngineClass

struct CtkThemingEngineClass {
  GObjectClass parent_class;

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

  GdkPixbuf * (* render_icon_pixbuf) (CtkThemingEngine    *engine,
                                      const CtkIconSource *source,
                                      CtkIconSize          size);
  void (* render_icon) (CtkThemingEngine *engine,
                        cairo_t          *cr,
			GdkPixbuf        *pixbuf,
                        gdouble           x,
                        gdouble           y);
  void (* render_icon_surface) (CtkThemingEngine *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 CtkCheckButton.
`render_option` ()	Renders an option, as in CtkRadioButton.
`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 CtkExpander.
`render_focus` ()	Renders the focus indicator.
`render_layout` ()	Renders a PangoLayout
`render_slider` ()	Renders a slider control, as in CtkScale.
`render_handle` ()	Renders a handle to drag UI elements, as in CtkPaned.
`render_activity` ()	Renders an area displaying activity, such as in CtkSpinner, or CtkProgressBar.
`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 CtkThemingEngine

struct CtkThemingEngine;

Property Details

The `“name”` property

  “name”                     char *

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;

Owner: CtkThemingEngine

Flags: Read / Write / Construct Only

Default value: NULL

Since: 3.0