Gtk.StyleContext¶

class — extends GObject.Object

:::warning Deprecated since 4.10 This API is deprecated. :::

GtkStyleContext 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 StyleContext.add_provider, or to the display through StyleContext.add_provider_for_display. The resulting style is a combination of all providers’ information in priority order.

For GTK widgets, any GtkStyleContext returned by 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.

Custom styling in UI libraries and applications¶

If you are developing a library with custom widgets that render differently than standard components, you may need to add a GtkStyleProvider yourself with the 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 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 STYLE_PROVIDER_PRIORITY_USER priority.

Methods¶

add_class¶

def add_class(self, class_name: str) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Adds a style class to context, so later uses of the style context will make use of this new class for styling.

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

entry.search { ... }

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

.search { ... }

Parameters:

class_name — class name to use in styling

add_provider¶

def add_provider(self, provider: StyleProvider, priority: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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 StyleContext.add_provider_for_display.

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

Parameters:

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 STYLE_PROVIDER_PRIORITY_FALLBACK and STYLE_PROVIDER_PRIORITY_USER

get_border¶

def get_border(self) -> Border

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets the border for a given state as a GtkBorder.

get_color¶

def get_color(self) -> Gdk.RGBA

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets the foreground color for a given state.

get_display¶

def get_display(self) -> Gdk.Display

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the GdkDisplay to which context is attached.

get_margin¶

def get_margin(self) -> Border

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets the margin for a given state as a GtkBorder.

get_padding¶

def get_padding(self) -> Border

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets the padding for a given state as a GtkBorder.

get_scale¶

def get_scale(self) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the scale used for assets.

get_state¶

def get_state(self) -> StateFlags

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the state used for style matching.

This method should only be used to retrieve the GtkStateFlags to pass to GtkStyleContext methods, like StyleContext.get_padding. If you need to retrieve the current state of a GtkWidget, use Widget.get_state_flags.

has_class¶

def has_class(self, class_name: str) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

class_name — a class name

lookup_color¶

def lookup_color(self, color_name: str) -> tuple[bool, Gdk.RGBA]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

color_name — color name to lookup

remove_class¶

def remove_class(self, class_name: str) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Removes class_name from context.

Parameters:

class_name — class name to remove

remove_provider¶

def remove_provider(self, provider: StyleProvider) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Removes provider from the style providers list in context.

Parameters:

provider — a GtkStyleProvider

restore¶

def restore(self) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Restores context state to a previous stage.

See StyleContext.save.

save¶

def save(self) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Saves the context state.

This allows temporary modifications done through StyleContext.add_class, StyleContext.remove_class, StyleContext.set_state to be quickly reverted in one go through StyleContext.restore.

The matching call to StyleContext.restore must be done before GTK returns to the main loop.

set_display¶

def set_display(self, display: Gdk.Display) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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 Widget.get_style_context, you do not need to call this yourself.

Parameters:

display — a GdkDisplay

set_scale¶

def set_scale(self, scale: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

scale — scale

set_state¶

def set_state(self, flags: StateFlags | int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the state to be used for style matching.

Parameters:

flags — state to represent

to_string¶

def to_string(self, flags: StyleContextPrintFlags | int) -> str

:::warning Deprecated since 4.10 This API is deprecated. :::

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:

flags — Flags that determine what to print

Static functions¶

add_provider_for_display¶

@staticmethod
def add_provider_for_display(display: Gdk.Display, provider: StyleProvider, priority: int) -> None

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 StyleContext.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 STYLE_PROVIDER_PRIORITY_FALLBACK and STYLE_PROVIDER_PRIORITY_USER

remove_provider_for_display¶

@staticmethod
def remove_provider_for_display(display: Gdk.Display, provider: StyleProvider) -> None

Removes provider from the global style providers list in display.

Parameters:

display — a GdkDisplay
provider — a GtkStyleProvider

Virtual methods¶

do_changed¶

def do_changed(self) -> None

Properties¶

display¶

display: Gdk.Display  # read/write

The display of the style context.