GtkStyleContext

GtkStyleContext — Rendering UI elements

Functions

Properties

GdkDisplay * display Read / Write

Types and Values

enum GtkBorderStyle
#define GTK_STYLE_CLASS_ACCELERATOR
#define GTK_STYLE_CLASS_ARROW
#define GTK_STYLE_CLASS_BACKGROUND
#define GTK_STYLE_CLASS_BOTTOM
#define GTK_STYLE_CLASS_BUTTON
#define GTK_STYLE_CLASS_CALENDAR
#define GTK_STYLE_CLASS_CELL
#define GTK_STYLE_CLASS_COMBOBOX_ENTRY
#define GTK_STYLE_CLASS_CONTEXT_MENU
#define GTK_STYLE_CLASS_CHECK
#define GTK_STYLE_CLASS_CSD
#define GTK_STYLE_CLASS_CURSOR_HANDLE
#define GTK_STYLE_CLASS_DEFAULT
#define GTK_STYLE_CLASS_DESTRUCTIVE_ACTION
#define GTK_STYLE_CLASS_DIM_LABEL
#define GTK_STYLE_CLASS_DND
#define GTK_STYLE_CLASS_DOCK
#define GTK_STYLE_CLASS_ENTRY
#define GTK_STYLE_CLASS_ERROR
#define GTK_STYLE_CLASS_EXPANDER
#define GTK_STYLE_CLASS_FRAME
#define GTK_STYLE_CLASS_FLAT
#define GTK_STYLE_CLASS_HEADER
#define GTK_STYLE_CLASS_HIGHLIGHT
#define GTK_STYLE_CLASS_HORIZONTAL
#define GTK_STYLE_CLASS_IMAGE
#define GTK_STYLE_CLASS_INFO
#define GTK_STYLE_CLASS_INSERTION_CURSOR
#define GTK_STYLE_CLASS_LABEL
#define GTK_STYLE_CLASS_LEFT
#define GTK_STYLE_CLASS_LEVEL_BAR
#define GTK_STYLE_CLASS_LINKED
#define GTK_STYLE_CLASS_LIST
#define GTK_STYLE_CLASS_LIST_ROW
#define GTK_STYLE_CLASS_MARK
#define GTK_STYLE_CLASS_MENU
#define GTK_STYLE_CLASS_MENUBAR
#define GTK_STYLE_CLASS_MENUITEM
#define GTK_STYLE_CLASS_MESSAGE_DIALOG
#define GTK_STYLE_CLASS_MONOSPACE
#define GTK_STYLE_CLASS_NEEDS_ATTENTION
#define GTK_STYLE_CLASS_NOTEBOOK
#define GTK_STYLE_CLASS_OSD
#define GTK_STYLE_CLASS_OVERSHOOT
#define GTK_STYLE_CLASS_PANE_SEPARATOR
#define GTK_STYLE_CLASS_PAPER
#define GTK_STYLE_CLASS_POPUP
#define GTK_STYLE_CLASS_POPOVER
#define GTK_STYLE_CLASS_PROGRESSBAR
#define GTK_STYLE_CLASS_PULSE
#define GTK_STYLE_CLASS_QUESTION
#define GTK_STYLE_CLASS_RADIO
#define GTK_STYLE_CLASS_RAISED
#define GTK_STYLE_CLASS_READ_ONLY
#define GTK_STYLE_CLASS_RIGHT
#define GTK_STYLE_CLASS_RUBBERBAND
#define GTK_STYLE_CLASS_SCALE
#define GTK_STYLE_CLASS_SCALE_HAS_MARKS_ABOVE
#define GTK_STYLE_CLASS_SCALE_HAS_MARKS_BELOW
#define GTK_STYLE_CLASS_SCROLLBAR
#define GTK_STYLE_CLASS_SCROLLBARS_JUNCTION
#define GTK_STYLE_CLASS_SEPARATOR
#define GTK_STYLE_CLASS_SIDEBAR
#define GTK_STYLE_CLASS_SLIDER
#define GTK_STYLE_CLASS_SPINBUTTON
#define GTK_STYLE_CLASS_SPINNER
#define GTK_STYLE_CLASS_STATUSBAR
#define GTK_STYLE_CLASS_SUBTITLE
#define GTK_STYLE_CLASS_SUGGESTED_ACTION
#define GTK_STYLE_CLASS_TITLE
#define GTK_STYLE_CLASS_TITLEBAR
#define GTK_STYLE_CLASS_TOOLBAR
#define GTK_STYLE_CLASS_TOOLTIP
#define GTK_STYLE_CLASS_TOUCH_SELECTION
#define GTK_STYLE_CLASS_TOP
#define GTK_STYLE_CLASS_TROUGH
#define GTK_STYLE_CLASS_UNDERSHOOT
#define GTK_STYLE_CLASS_VERTICAL
#define GTK_STYLE_CLASS_VIEW
#define GTK_STYLE_CLASS_WARNING
#define GTK_STYLE_CLASS_WIDE
  GtkStyleContext
enum GtkStyleContextPrintFlags
struct GtkBorder

Object Hierarchy

    GObject
    ╰── GtkStyleContext

Includes

#include <gtk/gtk.h>

Description

GtkStyleContext is an object that stores styling information affecting a widget.

In order to construct the final style information, GtkStyleContext queries information from all attached GtkStyleProviders. Style providers can be either attached explicitly to the context through gtk_style_context_add_provider(), or to the display through gtk_style_context_add_provider_for_display(). The resulting style is a combination of all providers’ information in priority order.

For GTK+ widgets, any GtkStyleContext returned by gtk_widget_get_style_context() will already have a GdkDisplay and RTL/LTR information set. The style context will also be updated automatically if any of these settings change on the widget.

Style Classes

Widgets can add style classes to their context, which can be used to associate different styles by class. The documentation for individual widgets lists which style classes it uses itself, and which style classes may be added by applications to affect their appearance.

GTK+ defines macros for a number of style classes.


Custom styling in UI libraries and applications

If you are developing a library with custom GtkWidgets that render differently than standard components, you may need to add a GtkStyleProvider yourself with the GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority, either a GtkCssProvider or a custom object implementing the GtkStyleProvider interface. This way themes may still attempt to style your UI elements in a different way if needed so.

If you are using custom styling on an applications, you probably want then to make your style information prevail to the theme’s, so you must use a GtkStyleProvider with the GTK_STYLE_PROVIDER_PRIORITY_APPLICATION priority, keep in mind that the user settings in XDG_CONFIG_HOME/gtk-4.0/gtk.css will still take precedence over your changes, as it uses the GTK_STYLE_PROVIDER_PRIORITY_USER priority.

Functions

gtk_style_context_add_provider ()

void
gtk_style_context_add_provider (GtkStyleContext *context,
                                GtkStyleProvider *provider,
                                guint priority);

Adds a style provider to context , to be used in style construction. Note that a style provider added by this function only affects the style of the widget to which context belongs. If you want to affect the style of all widgets, use gtk_style_context_add_provider_for_display().

Note: If both priorities are the same, a GtkStyleProvider added through this function takes precedence over another added through gtk_style_context_add_provider_for_display().

Parameters

context

a GtkStyleContext

 

provider

a GtkStyleProvider

 

priority

the priority of the style provider. The lower it is, the earlier it will be used in the style construction. Typically this will be in the range between GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and GTK_STYLE_PROVIDER_PRIORITY_USER

 

gtk_style_context_add_provider_for_display ()

void
gtk_style_context_add_provider_for_display
                               (GdkDisplay *display,
                                GtkStyleProvider *provider,
                                guint priority);

Adds a global style provider to display , which will be used in style construction for all GtkStyleContexts under display .

GTK+ uses this to make styling information from GtkSettings available.

Note: If both priorities are the same, A GtkStyleProvider added through gtk_style_context_add_provider() takes precedence over another added through this function.

Parameters

display

a GdkDisplay

 

provider

a GtkStyleProvider

 

priority

the priority of the style provider. The lower it is, the earlier it will be used in the style construction. Typically this will be in the range between GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and GTK_STYLE_PROVIDER_PRIORITY_USER

 

gtk_style_context_get_display ()

GdkDisplay *
gtk_style_context_get_display (GtkStyleContext *context);

Returns the GdkDisplay to which context is attached.

Parameters

context

a GtkStyleContext

 

Returns

a GdkDisplay.

[transfer none]


gtk_style_context_get_state ()

GtkStateFlags
gtk_style_context_get_state (GtkStyleContext *context);

Returns the state used for style matching.

This method should only be used to retrieve the GtkStateFlags to pass to GtkStyleContext methods, like gtk_style_context_get_padding(). If you need to retrieve the current state of a GtkWidget, use gtk_widget_get_state_flags().

Parameters

context

a GtkStyleContext

 

Returns

the state flags


gtk_style_context_get_color ()

void
gtk_style_context_get_color (GtkStyleContext *context,
                             GdkRGBA *color);

Gets the foreground color for a given state.

See gtk_style_context_get_property() and GTK_STYLE_PROPERTY_COLOR for details.

Parameters

context

a GtkStyleContext

 

color

return value for the foreground color.

[out]

gtk_style_context_get_border ()

void
gtk_style_context_get_border (GtkStyleContext *context,
                              GtkBorder *border);

Gets the border for a given state as a GtkBorder.

See gtk_style_context_get_property() and GTK_STYLE_PROPERTY_BORDER_WIDTH for details.

Parameters

context

a GtkStyleContext

 

border

return value for the border settings.

[out]

gtk_style_context_get_padding ()

void
gtk_style_context_get_padding (GtkStyleContext *context,
                               GtkBorder *padding);

Gets the padding for a given state as a GtkBorder. See gtk_style_context_get() and GTK_STYLE_PROPERTY_PADDING for details.

Parameters

context

a GtkStyleContext

 

padding

return value for the padding settings.

[out]

gtk_style_context_get_margin ()

void
gtk_style_context_get_margin (GtkStyleContext *context,
                              GtkBorder *margin);

Gets the margin for a given state as a GtkBorder. See gtk_style_property_get() and GTK_STYLE_PROPERTY_MARGIN for details.

Parameters

context

a GtkStyleContext

 

margin

return value for the margin settings.

[out]

gtk_style_context_lookup_color ()

gboolean
gtk_style_context_lookup_color (GtkStyleContext *context,
                                const gchar *color_name,
                                GdkRGBA *color);

Looks up and resolves a color name in the context color map.

Parameters

context

a GtkStyleContext

 

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_style_context_remove_provider ()

void
gtk_style_context_remove_provider (GtkStyleContext *context,
                                   GtkStyleProvider *provider);

Removes provider from the style providers list in context .

Parameters

context

a GtkStyleContext

 

provider

a GtkStyleProvider

 

gtk_style_context_remove_provider_for_display ()

void
gtk_style_context_remove_provider_for_display
                               (GdkDisplay *display,
                                GtkStyleProvider *provider);

Removes provider from the global style providers list in display .

Parameters

display

a GdkDisplay

 

provider

a GtkStyleProvider

 

gtk_style_context_reset_widgets ()

void
gtk_style_context_reset_widgets (GdkDisplay *display);

This function recomputes the styles for all widgets under a particular GdkDisplay. This is useful when some global parameter has changed that affects the appearance of all widgets, because when a widget gets a new style, it will both redraw and recompute any cached information about its appearance. As an example, it is used when the color scheme changes in the related GtkSettings object.

Parameters

display

a GdkDisplay

 

gtk_style_context_restore ()

void
gtk_style_context_restore (GtkStyleContext *context);

Restores context state to a previous stage. See gtk_style_context_save().

Parameters

context

a GtkStyleContext

 

gtk_style_context_save ()

void
gtk_style_context_save (GtkStyleContext *context);

Saves the context state, so temporary modifications done through gtk_style_context_add_class(), gtk_style_context_remove_class(), gtk_style_context_set_state(), etc. can quickly be reverted in one go through gtk_style_context_restore().

The matching call to gtk_style_context_restore() must be done before GTK returns to the main loop.

Parameters

context

a GtkStyleContext

 

gtk_style_context_add_class ()

void
gtk_style_context_add_class (GtkStyleContext *context,
                             const gchar *class_name);

Adds a style class to context , so posterior calls to gtk_style_context_get() or any of the gtk_render_*() functions will make use of this new class for styling.

In the CSS file format, a GtkEntry defining a “search” class, would be matched by:

1
entry.search { ... }

While any widget defining a “search” class would be matched by:

1
.search { ... }

Parameters

context

a GtkStyleContext

 

class_name

class name to use in styling

 

gtk_style_context_remove_class ()

void
gtk_style_context_remove_class (GtkStyleContext *context,
                                const gchar *class_name);

Removes class_name from context .

Parameters

context

a GtkStyleContext

 

class_name

class name to remove

 

gtk_style_context_has_class ()

gboolean
gtk_style_context_has_class (GtkStyleContext *context,
                             const gchar *class_name);

Returns TRUE if context currently has defined the given class name.

Parameters

context

a GtkStyleContext

 

class_name

a class name

 

Returns

TRUE if context has class_name defined


gtk_style_context_list_classes ()

GList *
gtk_style_context_list_classes (GtkStyleContext *context);

Returns the list of classes currently defined in context .

Parameters

context

a GtkStyleContext

 

Returns

a GList of strings with the currently defined classes. The contents of the list are owned by GTK+, but you must free the list itself with g_list_free() when you are done with it.

[transfer container][element-type utf8]


gtk_style_context_set_display ()

void
gtk_style_context_set_display (GtkStyleContext *context,
                               GdkDisplay *display);

Attaches context to the given display.

The display is used to add style information from “global” style providers, such as the display's GtkSettings instance.

If you are using a GtkStyleContext returned from gtk_widget_get_style_context(), you do not need to call this yourself.

Parameters

context

a GtkStyleContext

 

display

a GdkDisplay

 

gtk_style_context_set_state ()

void
gtk_style_context_set_state (GtkStyleContext *context,
                             GtkStateFlags flags);

Sets the state to be used for style matching.

Parameters

context

a GtkStyleContext

 

flags

state to represent

 

gtk_style_context_set_scale ()

void
gtk_style_context_set_scale (GtkStyleContext *context,
                             gint scale);

Sets the scale to use when getting image assets for the style.

Parameters

context

a GtkStyleContext

 

scale

scale

 

gtk_style_context_get_scale ()

gint
gtk_style_context_get_scale (GtkStyleContext *context);

Returns the scale used for assets.

Parameters

context

a GtkStyleContext

 

Returns

the scale


gtk_style_context_to_string ()

char *
gtk_style_context_to_string (GtkStyleContext *context,
                             GtkStyleContextPrintFlags flags);

Converts the style context into a string representation.

The string representation always includes information about the name, state, id, visibility and style classes of the CSS node that is backing context . Depending on the flags, more information may be included.

This function is intended for testing and debugging of the CSS implementation in GTK+. There are no guarantees about the format of the returned string, it may change.

Parameters

context

a GtkStyleContext

 

flags

Flags that determine what to print

 

Returns

a newly allocated string representing context


gtk_border_new ()

GtkBorder *
gtk_border_new (void);

Allocates a new GtkBorder and initializes its elements to zero.

Returns

a newly allocated GtkBorder. Free with gtk_border_free().

[transfer full]


gtk_border_copy ()

GtkBorder *
gtk_border_copy (const GtkBorder *border_);

Copies a GtkBorder.

Parameters

border_

a GtkBorder

 

Returns

a copy of border_ .

[transfer full]


gtk_border_free ()

void
gtk_border_free (GtkBorder *border_);

Frees a GtkBorder.

Parameters

border_

a GtkBorder

 

gtk_render_arrow ()

void
gtk_render_arrow (GtkStyleContext *context,
                  cairo_t *cr,
                  gdouble angle,
                  gdouble x,
                  gdouble y,
                  gdouble size);

Renders an arrow pointing to angle .

Typical arrow rendering at 0, 1⁄2 π;, π; and 3⁄2 π:

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

angle

arrow angle from 0 to 2 * G_PI, being 0 the arrow pointing to the north

 

x

X origin of the render area

 

y

Y origin of the render area

 

size

square side for render area

 

gtk_render_background ()

void
gtk_render_background (GtkStyleContext *context,
                       cairo_t *cr,
                       gdouble x,
                       gdouble y,
                       gdouble width,
                       gdouble height);

Renders the background of an element.

Typical background rendering, showing the effect of background-image, border-width and border-radius:

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

x

X origin of the rectangle

 

y

Y origin of the rectangle

 

width

rectangle width

 

height

rectangle height

 

gtk_render_check ()

void
gtk_render_check (GtkStyleContext *context,
                  cairo_t *cr,
                  gdouble x,
                  gdouble y,
                  gdouble width,
                  gdouble height);

Renders a checkmark (as in a GtkCheckButton).

The GTK_STATE_FLAG_CHECKED state determines whether the check is on or off, and GTK_STATE_FLAG_INCONSISTENT determines whether it should be marked as undefined.

Typical checkmark rendering:

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

x

X origin of the rectangle

 

y

Y origin of the rectangle

 

width

rectangle width

 

height

rectangle height

 

gtk_render_expander ()

void
gtk_render_expander (GtkStyleContext *context,
                     cairo_t *cr,
                     gdouble x,
                     gdouble y,
                     gdouble width,
                     gdouble height);

Renders an expander (as used in GtkTreeView and GtkExpander) in the area defined by x , y , width , height . The state GTK_STATE_FLAG_CHECKED determines whether the expander is collapsed or expanded.

Typical expander rendering:

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

x

X origin of the rectangle

 

y

Y origin of the rectangle

 

width

rectangle width

 

height

rectangle height

 

gtk_render_focus ()

void
gtk_render_focus (GtkStyleContext *context,
                  cairo_t *cr,
                  gdouble x,
                  gdouble y,
                  gdouble width,
                  gdouble height);

Renders a focus indicator on the rectangle determined by x , y , width , height .

Typical focus rendering:

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

x

X origin of the rectangle

 

y

Y origin of the rectangle

 

width

rectangle width

 

height

rectangle height

 

gtk_render_frame ()

void
gtk_render_frame (GtkStyleContext *context,
                  cairo_t *cr,
                  gdouble x,
                  gdouble y,
                  gdouble width,
                  gdouble height);

Renders a frame around the rectangle defined by x , y , width , height .

Examples of frame rendering, showing the effect of border-image, border-color, border-width, border-radius and junctions:

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

x

X origin of the rectangle

 

y

Y origin of the rectangle

 

width

rectangle width

 

height

rectangle height

 

gtk_render_handle ()

void
gtk_render_handle (GtkStyleContext *context,
                   cairo_t *cr,
                   gdouble x,
                   gdouble y,
                   gdouble width,
                   gdouble height);

Renders a handle (as in GtkPaned and GtkWindow’s resize grip), in the rectangle determined by x , y , width , height .

Handles rendered for the paned and grip classes:

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

x

X origin of the rectangle

 

y

Y origin of the rectangle

 

width

rectangle width

 

height

rectangle height

 

gtk_render_layout ()

void
gtk_render_layout (GtkStyleContext *context,
                   cairo_t *cr,
                   gdouble x,
                   gdouble y,
                   PangoLayout *layout);

Renders layout on the coordinates x , y

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

x

X origin

 

y

Y origin

 

layout

the PangoLayout to render

 

gtk_render_line ()

void
gtk_render_line (GtkStyleContext *context,
                 cairo_t *cr,
                 gdouble x0,
                 gdouble y0,
                 gdouble x1,
                 gdouble y1);

Renders a line from (x0, y0) to (x1, y1).

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

x0

X coordinate for the origin of the line

 

y0

Y coordinate for the origin of the line

 

x1

X coordinate for the end of the line

 

y1

Y coordinate for the end of the line

 

gtk_render_option ()

void
gtk_render_option (GtkStyleContext *context,
                   cairo_t *cr,
                   gdouble x,
                   gdouble y,
                   gdouble width,
                   gdouble height);

Renders an option mark (as in a GtkRadioButton), the GTK_STATE_FLAG_CHECKED state will determine whether the option is on or off, and GTK_STATE_FLAG_INCONSISTENT whether it should be marked as undefined.

Typical option mark rendering:

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

x

X origin of the rectangle

 

y

Y origin of the rectangle

 

width

rectangle width

 

height

rectangle height

 

gtk_render_activity ()

void
gtk_render_activity (GtkStyleContext *context,
                     cairo_t *cr,
                     gdouble x,
                     gdouble y,
                     gdouble width,
                     gdouble height);

Renders an activity indicator (such as in GtkSpinner). The state GTK_STATE_FLAG_CHECKED determines whether there is activity going on.

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

x

X origin of the rectangle

 

y

Y origin of the rectangle

 

width

rectangle width

 

height

rectangle height

 

gtk_render_icon ()

void
gtk_render_icon (GtkStyleContext *context,
                 cairo_t *cr,
                 GdkTexture *texture,
                 gdouble x,
                 gdouble y);

Renders the icon in texture at the specified x and y coordinates.

This function will render the icon in texture at exactly its size, regardless of scaling factors, which may not be appropriate when drawing on displays with high pixel densities.

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

texture

a GdkTexture containing the icon to draw

 

x

X position for the texture

 

y

Y position for the texture

 

gtk_render_insertion_cursor ()

void
gtk_render_insertion_cursor (GtkStyleContext *context,
                             cairo_t *cr,
                             gdouble x,
                             gdouble y,
                             PangoLayout *layout,
                             int index,
                             PangoDirection direction);

Draws a text caret on cr at the specified index of layout .

Parameters

context

a GtkStyleContext

 

cr

a cairo_t

 

x

X origin

 

y

Y origin

 

layout

the PangoLayout of the text

 

index

the index in the PangoLayout

 

direction

the PangoDirection of the text

 

Property Details

The “display” property

  “display”                  GdkDisplay *

The associated GdkDisplay.

Owner: GtkStyleContext

Flags: Read / Write