GtkCssProvider: GTK+ 3 Reference Manual

## GtkCssProvider GtkCssProvider — CSS-like styling for widgets |

## Functions

GtkCssProvider * | gtk_css_provider_get_default ()
GtkCssProvider * | gtk_css_provider_get_named ()
gboolean | gtk_css_provider_load_from_data ()
gboolean | gtk_css_provider_load_from_file ()
gboolean | gtk_css_provider_load_from_path ()
void | gtk_css_provider_load_from_resource ()
GtkCssProvider * | gtk_css_provider_new ()
char * | gtk_css_provider_to_string ()
guint | gtk_css_section_get_end_line ()
guint | gtk_css_section_get_end_position ()
GFile * | gtk_css_section_get_file ()
GtkCssSection * | gtk_css_section_get_parent ()
GtkCssSectionType | gtk_css_section_get_section_type ()
guint | gtk_css_section_get_start_line ()
guint | gtk_css_section_get_start_position ()
GtkCssSection * | gtk_css_section_ref ()
void | gtk_css_section_unref ()

## Signals

void | parsing-error | Run Last

## Types and Values

struct | GtkCssProvider
#define | GTK_CSS_PROVIDER_ERROR
enum | GtkCssProviderError
| GtkCssSection
enum | GtkCssSectionType

## Object Hierarchy

        GBoxed
        ╰── GtkCssSection
        GObject
        ╰── GtkCssProvider

## Implemented Interfaces

GtkCssProvider implements GtkStyleProvider and GtkStyleProviderPrivate.

## 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_screen()`.

In addition, certain files will be read when GTK+ is initialized. First, the file `$XDG_CONFIG_HOME/gtk-3.0/gtk.css` is loaded if it exists. Then, GTK+ loads the first existing file among `XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk.css`, `$HOME/.themes/THEME/gtk-VERSION/gtk.css`, `$XDG_DATA_DIRS/themes/THEME/gtk-VERSION/gtk.css` and `DATADIR/share/themes/THEME/gtk-VERSION/gtk.css`, where `THEME` is the name of the current theme (see the “gtk-theme-name” 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 3.0.

In the same way, GTK+ tries to load a gtk-keys.css file for the current key theme, as defined by “gtk-key-theme-name”.

## Functions

### gtk_css_provider_get_default ()

    GtkCssProvider *
    gtk_css_provider_get_default (void);

`gtk_css_provider_get_default` has been deprecated since version 3.24 and should not be used in newly-written code.

Use `gtk_css_provider_new()` instead.

Returns the provider containing the style settings used as a fallback for all widgets.

#### Returns

The provider used for fallback styling. This memory is owned by GTK+, and you must not free it.

[transfer none]

### gtk_css_provider_get_named ()

    GtkCssProvider *
    gtk_css_provider_get_named (const gchar *name,
                                const gchar *variant);

Loads a theme from the usual theme paths

#### Parameters

name | A theme name |
variant | variant to load, for example, "dark", or `NULL` for the default. | [allow-none]

#### Returns

a GtkCssProvider with the theme loaded. This memory is owned by GTK+, and you must not free it.

[transfer none]

### gtk_css_provider_load_from_data ()

    gboolean
    gtk_css_provider_load_from_data (GtkCssProvider *css_provider,
                                     const gchar *data,
                                     gssize length,
                                     GError **error);

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. |
error | return location for a GError, or `NULL`. | [out][allow-none]

#### Returns

`TRUE`. The return value is deprecated and `FALSE` will only be returned for backwards compatibility reasons if an `error` is not `NULL` and a loading error occurred. To track errors while loading CSS, connect to the “parsing-error” signal.

### gtk_css_provider_load_from_file ()

    gboolean
    gtk_css_provider_load_from_file (GtkCssProvider *css_provider,
                                     GFile *file,
                                     GError **error);

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 |
error | return location for a GError, or `NULL`. | [out][allow-none]

#### Returns

`TRUE`. The return value is deprecated and `FALSE` will only be returned for backwards compatibility reasons if an `error` is not `NULL` and a loading error occurred. To track errors while loading CSS, connect to the “parsing-error” signal.

### gtk_css_provider_load_from_path ()

    gboolean
    gtk_css_provider_load_from_path (GtkCssProvider *css_provider,
                                     const gchar *path,
                                     GError **error);

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 |
error | return location for a GError, or `NULL`. | [out][allow-none]

#### Returns

`TRUE`. The return value is deprecated and `FALSE` will only be returned for backwards compatibility reasons if an `error` is not `NULL` and a loading error occurred. To track errors while loading CSS, connect to the “parsing-error” signal.

### 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 |

Since: 3.16

### 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` .

Since: 3.2

### gtk_css_section_get_end_line ()

    guint
    gtk_css_section_get_end_line (const GtkCssSection *section);

Returns the line in the CSS document where this section end. The line number is 0-indexed, so the first line of the document will return 0. This value may change in future invocations of this function if `section` is not yet parsed completely. This will for example happen in the GtkCssProvider::parsing-error signal. The end position and line may be identical to the start position and line for sections which failed to parse anything successfully.

#### Parameters

section | the section |

#### Returns

the line number

Since: 3.2

### gtk_css_section_get_end_position ()

    guint
    gtk_css_section_get_end_position (const GtkCssSection *section);

Returns the offset in bytes from the start of the current line returned via `gtk_css_section_get_end_line()`. This value may change in future invocations of this function if `section` is not yet parsed completely. This will for example happen in the GtkCssProvider::parsing-error signal. The end position and line may be identical to the start position and line for sections which failed to parse anything successfully.

#### Parameters

section | the section |

#### Returns

the offset in bytes from the start of the line.

Since: 3.2

### 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]

Since: 3.2

### 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]

Since: 3.2

### gtk_css_section_get_section_type ()

    GtkCssSectionType
    gtk_css_section_get_section_type (const GtkCssSection *section);

Gets the type of information that `section` describes.

#### Parameters

section | the section |

#### Returns

the type of `section`

Since: 3.2

### gtk_css_section_get_start_line ()

    guint
    gtk_css_section_get_start_line (const GtkCssSection *section);

Returns the line in the CSS document where this section starts. The line number is 0-indexed, so the first line of the document will return 0.

#### Parameters

section | the section |

#### Returns

the line number

Since: 3.2

### gtk_css_section_get_start_position ()

    guint
    gtk_css_section_get_start_position (const GtkCssSection *section);

Returns the offset in bytes from the start of the current line returned via `gtk_css_section_get_start_line()`.

#### Parameters

section | the section |

#### Returns

the offset in bytes from the start of the line.

Since: 3.2

### gtk_css_section_ref ()

    GtkCssSection *
    gtk_css_section_ref (GtkCssSection *section);

Increments the reference count on `section` .

#### Parameters

section | a GtkCssSection |

#### Returns

`section` itself.

Since: 3.2

### 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 |

Since: 3.2

## Types and Values

### struct GtkCssProvider

    struct GtkCssProvider;

### GTK_CSS_PROVIDER_ERROR

    #define GTK_CSS_PROVIDER_ERROR (gtk_css_provider_error_quark ())

Domain for GtkCssProvider errors.

### enum GtkCssProviderError

Error codes for `GTK_CSS_PROVIDER_ERROR`.

#### Members

GTK_CSS_PROVIDER_ERROR_FAILED | Failed. |
GTK_CSS_PROVIDER_ERROR_SYNTAX | Syntax error. |
GTK_CSS_PROVIDER_ERROR_IMPORT | Import error. |
GTK_CSS_PROVIDER_ERROR_NAME | Name error. |
GTK_CSS_PROVIDER_ERROR_DEPRECATED | Deprecation error. |
GTK_CSS_PROVIDER_ERROR_UNKNOWN_VALUE | Unknown value. |

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

Since: 3.2

### enum GtkCssSectionType

The different types of sections indicate parts of a CSS document as parsed by GTK’s CSS parser. They are oriented towards the CSS Grammar, but may contain extensions.

More types might be added in the future as the parser incorporates more features.

#### Members

GTK_CSS_SECTION_DOCUMENT | The section describes a complete document. This section time is the only one where `gtk_css_section_get_parent()` might return `NULL`. |
GTK_CSS_SECTION_IMPORT | The section defines an import rule. |
GTK_CSS_SECTION_COLOR_DEFINITION | The section defines a color. This is a GTK extension to CSS. |
GTK_CSS_SECTION_BINDING_SET | The section defines a binding set. This is a GTK extension to CSS. |
GTK_CSS_SECTION_RULESET | The section defines a CSS ruleset. |
GTK_CSS_SECTION_SELECTOR | The section defines a CSS selector. |
GTK_CSS_SECTION_DECLARATION | The section defines the declaration of a CSS variable. |
GTK_CSS_SECTION_VALUE | The section defines the value of a CSS declaration. |
GTK_CSS_SECTION_KEYFRAMES | The section defines keyframes. See CSS Animations for details. Since 3.6 |

Since: 3.2

## 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

## See Also

GtkStyleContext, GtkStyleProvider