GtkCssProvider

GtkCssProvider — CSS-like styling for widgets

Signals

void parsing-error Run Last

Object Hierarchy

    GBoxed
    ╰── GtkCssSection
    GObject
    ╰── GtkCssProvider

Implemented Interfaces

GtkCssProvider implements GtkStyleProvider.

Includes

#include <gtk/gtk.h>

Description

GtkCssProvider is an object implementing the GtkStyleProvider interface. It is able to parse CSS-like input in order to style widgets.

An application can make GTK parse a specific CSS style sheet by calling gtk_css_provider_load_from_file() or gtk_css_provider_load_from_resource() and adding the provider with gtk_style_context_add_provider() or gtk_style_context_add_provider_for_display().

In addition, certain files will be read when GTK is initialized. First, the file $XDG_CONFIG_HOME/gtk-4.0/gtk.css is loaded if it exists. Then, GTK loads the first existing file among XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk-VARIANT.css, $HOME/.themes/THEME/gtk-VERSION/gtk-VARIANT.css, $XDG_DATA_DIRS/themes/THEME/gtk-VERSION/gtk-VARIANT.css and DATADIR/share/themes/THEME/gtk-VERSION/gtk-VARIANT.css, where THEME is the name of the current theme (see the “gtk-theme-name” setting), VARIANT is the variant to load (see the “gtk-application-prefer-dark-theme” setting), DATADIR is the prefix configured when GTK was compiled (unless overridden by the GTK_DATA_PREFIX environment variable), and VERSION is the GTK version number. If no file is found for the current version, GTK tries older versions all the way back to 4.0.

Functions

gtk_css_provider_load_named ()

void
gtk_css_provider_load_named (GtkCssProvider *provider,
                             const char *name,
                             const char *variant);

Loads a theme from the usual theme paths. The actual process of finding the theme might change between releases, but it is guaranteed that this function uses the same mechanism to load the theme that GTK uses for loading its own theme.

Parameters

provider

a GtkCssProvider

 

name

A theme name

 

variant

variant to load, for example, "dark", or NULL for the default.

[allow-none]

gtk_css_provider_load_from_data ()

void
gtk_css_provider_load_from_data (GtkCssProvider *css_provider,
                                 const gchar *data,
                                 gssize length);

Loads data into css_provider , and by doing so clears any previously loaded information.

Parameters

css_provider

a GtkCssProvider

 

data

CSS data loaded in memory.

[array length=length][element-type guint8]

length

the length of data in bytes, or -1 for NUL terminated strings. If length is not -1, the code will assume it is not NUL terminated and will potentially do a copy.

 

gtk_css_provider_load_from_file ()

void
gtk_css_provider_load_from_file (GtkCssProvider *css_provider,
                                 GFile *file);

Loads the data contained in file into css_provider , making it clear any previously loaded information.

Parameters

css_provider

a GtkCssProvider

 

file

GFile pointing to a file to load

 

gtk_css_provider_load_from_path ()

void
gtk_css_provider_load_from_path (GtkCssProvider *css_provider,
                                 const gchar *path);

Loads the data contained in path into css_provider , making it clear any previously loaded information.

Parameters

css_provider

a GtkCssProvider

 

path

the path of a filename to load, in the GLib filename encoding

 

gtk_css_provider_load_from_resource ()

void
gtk_css_provider_load_from_resource (GtkCssProvider *css_provider,
                                     const gchar *resource_path);

Loads the data contained in the resource at resource_path into the GtkCssProvider, clearing any previously loaded information.

To track errors while loading CSS, connect to the “parsing-error” signal.

Parameters

css_provider

a GtkCssProvider

 

resource_path

a GResource resource path

 

gtk_css_provider_new ()

GtkCssProvider *
gtk_css_provider_new (void);

Returns a newly created GtkCssProvider.

Returns

A new GtkCssProvider


gtk_css_provider_to_string ()

char *
gtk_css_provider_to_string (GtkCssProvider *provider);

Converts the provider into a string representation in CSS format.

Using gtk_css_provider_load_from_data() with the return value from this function on a new provider created with gtk_css_provider_new() will basically create a duplicate of this provider .

Parameters

provider

the provider to write to a string

 

Returns

a new string representing the provider .


gtk_css_section_new ()

GtkCssSection *
gtk_css_section_new (GFile *file,
                     const GtkCssLocation *start,
                     const GtkCssLocation *end);

Creates a new GtkCssSection referring to the section in the given file from the start location to the end location.

[constructor]

Parameters

file

The file this section refers to.

[nullable][transfer none]

start

The start location

 

end

The end location

 

Returns

a new GtkCssSection


gtk_css_section_ref ()

GtkCssSection *
gtk_css_section_ref (GtkCssSection *section);

Increments the reference count on section .

Parameters

section

a GtkCssSection

 

Returns

section itself.


gtk_css_section_unref ()

void
gtk_css_section_unref (GtkCssSection *section);

Decrements the reference count on section , freeing the structure if the reference count reaches 0.

Parameters

section

a GtkCssSection

 

gtk_css_section_print ()

void
gtk_css_section_print (const GtkCssSection *section,
                       GString *string);

Prints the section into string in a human-readable form. This is a form like gtk.css:32:1-23 to denote line 32, characters 1 to 23 in the file gtk.css.

Parameters

section

a section

 

string

a GString to print to

 

gtk_css_section_to_string ()

char *
gtk_css_section_to_string (const GtkCssSection *section);

Prints the section into a human-readable text form using gtk_css_section_print().

Parameters

section

a GtkCssSection

 

Returns

A new string.

[transfer full]


gtk_css_section_get_file ()

GFile *
gtk_css_section_get_file (const GtkCssSection *section);

Gets the file that section was parsed from. If no such file exists, for example because the CSS was loaded via gtk_css_provider_load_from_data() , then NULL is returned.

Parameters

section

the section

 

Returns

the GFile that section was parsed from or NULL if section was parsed from other data.

[transfer none]


gtk_css_section_get_parent ()

GtkCssSection *
gtk_css_section_get_parent (const GtkCssSection *section);

Gets the parent section for the given section . The parent section is the section that contains this section . A special case are sections of type GTK_CSS_SECTION_DOCUMENT. Their parent will either be NULL if they are the original CSS document that was loaded by gtk_css_provider_load_from_file() or a section of type GTK_CSS_SECTION_IMPORT if it was loaded with an import rule from a different file.

Parameters

section

the section

 

Returns

the parent section or NULL if none.

[nullable][transfer none]


gtk_css_section_get_start_location ()

const GtkCssLocation *
gtk_css_section_get_start_location (const GtkCssSection *section);

Returns the location in the CSS document where this section starts.

Parameters

section

the section

 

Returns

The start location of this section.

[transfer none][not nullable]


gtk_css_section_get_end_location ()

const GtkCssLocation *
gtk_css_section_get_end_location (const GtkCssSection *section);

Returns the location in the CSS document where this section ends.

Parameters

section

the section

 

Returns

The end location of this section.

[transfer none][not nullable]

Types and Values

struct GtkCssProvider

struct GtkCssProvider;

GTK_CSS_PARSER_ERROR

#define GTK_CSS_PARSER_ERROR (gtk_css_parser_error_quark ())

Domain for GtkCssParser errors.


enum GtkCssParserError

Errors that can occur while parsing CSS.

These errors are unexpected and will cause parts of the given CSS to be ignored.

Members

GTK_CSS_PARSER_ERROR_FAILED

Unknown failure.

 

GTK_CSS_PARSER_ERROR_SYNTAX

The given text does not form valid syntax

 

GTK_CSS_PARSER_ERROR_IMPORT

Failed to import a resource

 

GTK_CSS_PARSER_ERROR_NAME

The given name has not been defined

 

GTK_CSS_PARSER_ERROR_UNKNOWN_VALUE

The given value is not correct

 

enum GtkCssParserWarning

Warnings that can occur while parsing CSS.

Unlike GtkCssParserErrors, warnings do not cause the parser to skip any input, but they indicate issues that should be fixed.

Members

GTK_CSS_PARSER_WARNING_DEPRECATED

The given construct is deprecated and will be removed in a future version

 

GTK_CSS_PARSER_WARNING_SYNTAX

A syntax construct was used that should be avoided

 

GTK_CSS_PARSER_WARNING_UNIMPLEMENTED

A feature is not implemented

 

struct GtkCssLocation

struct GtkCssLocation {
  gsize                  bytes;
  gsize                  chars;
  gsize                  lines;
  gsize                  line_bytes;
  gsize                  line_chars;
};

GtkCssLocation is used to present a location in a file - or other source of data parsed by the CSS engine.

The bytes and line_bytes offsets are meant to be used to programmatically match data. The lines and line_chars offsets can be used for printing the location in a file.

Note that the lines parameter starts from 0 and is increased whenever a CSS line break is encountered. (CSS defines the C character sequences "\r\n", "\r", "\n" and "\f" as newlines.) If your document uses different rules for line breaking, you might want run into problems here.

Members

gsize bytes;

number of bytes parsed since the beginning

 

gsize chars;

number of characters parsed since the beginning

 

gsize lines;

number of full lines that have been parsed If you want to display this as a line number, you need to add 1 to this.

 

gsize line_bytes;

Number of bytes parsed since the last line break

 

gsize line_chars;

Number of characters parsed since the last line break

 

GtkCssSection

typedef struct _GtkCssSection GtkCssSection;

Defines a part of a CSS document. Because sections are nested into one another, you can use gtk_css_section_get_parent() to get the containing region.

Signal Details

The “parsing-error” signal

void
user_function (GtkCssProvider *provider,
               GtkCssSection  *section,
               GError         *error,
               gpointer        user_data)

Signals that a parsing error occurred. the path , line and position describe the actual location of the error as accurately as possible.

Parsing errors are never fatal, so the parsing will resume after the error. Errors may however cause parts of the given data or even all of it to not be parsed at all. So it is a useful idea to check that the parsing succeeds by connecting to this signal.

Note that this signal may be emitted at any time as the css provider may opt to defer parsing parts or all of the input to a later time than when a loading function was called.

Parameters

provider

the provider that had a parsing error

 

section

section the error happened in

 

error

The parsing error

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last