CtkWidgetPath: CTK+ 3 Reference Manual

## CtkWidgetPath CtkWidgetPath — Widget path abstraction |

## Functions

gint | ctk_widget_path_append_type ()
gint | ctk_widget_path_append_with_siblings ()
gint | ctk_widget_path_append_for_widget ()
CtkWidgetPath * | ctk_widget_path_copy ()
CtkWidgetPath * | ctk_widget_path_ref ()
void | ctk_widget_path_unref ()
void | ctk_widget_path_free ()
GType | ctk_widget_path_get_object_type ()
gboolean | ctk_widget_path_has_parent ()
gboolean | ctk_widget_path_is_type ()
void | ctk_widget_path_iter_add_class ()
void | ctk_widget_path_iter_add_region ()
void | ctk_widget_path_iter_clear_classes ()
void | ctk_widget_path_iter_clear_regions ()
const gchar * | ctk_widget_path_iter_get_name ()
const char * | ctk_widget_path_iter_get_object_name ()
GType | ctk_widget_path_iter_get_object_type ()
const CtkWidgetPath * | ctk_widget_path_iter_get_siblings ()
guint | ctk_widget_path_iter_get_sibling_index ()
CtkStateFlags | ctk_widget_path_iter_get_state ()
gboolean | ctk_widget_path_iter_has_class ()
gboolean | ctk_widget_path_iter_has_name ()
gboolean | ctk_widget_path_iter_has_qclass ()
gboolean | ctk_widget_path_iter_has_qname ()
gboolean | ctk_widget_path_iter_has_qregion ()
gboolean | ctk_widget_path_iter_has_region ()
GSList * | ctk_widget_path_iter_list_classes ()
GSList * | ctk_widget_path_iter_list_regions ()
void | ctk_widget_path_iter_remove_class ()
void | ctk_widget_path_iter_remove_region ()
void | ctk_widget_path_iter_set_name ()
void | ctk_widget_path_iter_set_object_name ()
void | ctk_widget_path_iter_set_object_type ()
void | ctk_widget_path_iter_set_state ()
gint | ctk_widget_path_length ()
CtkWidgetPath * | ctk_widget_path_new ()
void | ctk_widget_path_prepend_type ()
char * | ctk_widget_path_to_string ()

## Types and Values

| CtkWidgetPath

## Includes

    #include <ctk/ctk.h>

## Description

CtkWidgetPath is a boxed type that represents a widget hierarchy from the topmost widget, typically a toplevel, to any child. This widget path abstraction is used in CtkStyleContext on behalf of the real widget in order to query style information.

If you are using CTK+ widgets, you probably will not need to use this API directly, as there is `ctk_widget_get_path()`, and the style context returned by `ctk_widget_get_style_context()` will be automatically updated on widget hierarchy changes.

The widget path generation is generally simple:

#### Defining a button within a window

    1
    2
    3
    4
    5
    6
    7
    {
      CtkWidgetPath *path;

      path = ctk_widget_path_new ();
      ctk_widget_path_append_type (path, CTK_TYPE_WINDOW);
      ctk_widget_path_append_type (path, CTK_TYPE_BUTTON);
    }

Although more complex information, such as widget names, or different classes (property that may be used by other widget types) and intermediate regions may be included:

#### Defining the first tab widget in a notebook

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    {
      CtkWidgetPath *path;
      guint pos;

      path = ctk_widget_path_new ();

      pos = ctk_widget_path_append_type (path, CTK_TYPE_NOTEBOOK);
      ctk_widget_path_iter_add_region (path, pos, "tab", CTK_REGION_EVEN | CTK_REGION_FIRST);

      pos = ctk_widget_path_append_type (path, CTK_TYPE_LABEL);
      ctk_widget_path_iter_set_name (path, pos, "first tab label");
    }

All this information will be used to match the style information that applies to the described widget.

## Functions

### ctk_widget_path_append_type ()

    gint
    ctk_widget_path_append_type (CtkWidgetPath *path,
                                 GType type);

Appends a widget type to the widget hierarchy represented by `path` .

#### Parameters

path | a CtkWidgetPath |
type | widget type to append |

#### Returns

the position where the element was inserted

Since: 3.0

### ctk_widget_path_append_with_siblings ()

    gint
    ctk_widget_path_append_with_siblings (CtkWidgetPath *path,
                                          CtkWidgetPath *siblings,
                                          guint sibling_index);

Appends a widget type with all its siblings to the widget hierarchy represented by `path` . Using this function instead of `ctk_widget_path_append_type()` will allow the CSS theming to use sibling matches in selectors and apply :nth-`child()` pseudo classes. In turn, it requires a lot more care in widget implementations as widgets need to make sure to call `ctk_widget_reset_style()` on all involved widgets when the `siblings` path changes.

#### Parameters

path | the widget path to append to |
siblings | a widget path describing a list of siblings. This path may not contain any siblings itself and it must not be modified afterwards. |
sibling_index | index into `siblings` for where the added element is positioned. |

#### Returns

the position where the element was inserted.

Since: 3.2

### ctk_widget_path_append_for_widget ()

    gint
    ctk_widget_path_append_for_widget (CtkWidgetPath *path,
                                       CtkWidget *widget);

Appends the data from `widget` to the widget hierarchy represented by `path` . This function is a shortcut for adding information from `widget` to the given `path` . This includes setting the name or adding the style classes from `widget` .

#### Parameters

path | a widget path |
widget | the widget to append to the widget path |

#### Returns

the position where the data was inserted

Since: 3.2

### ctk_widget_path_copy ()

    CtkWidgetPath *
    ctk_widget_path_copy (const CtkWidgetPath *path);

Returns a copy of `path`

#### Parameters

path | a CtkWidgetPath |

#### Returns

a copy of `path` .

[transfer full]

Since: 3.0

### ctk_widget_path_ref ()

    CtkWidgetPath *
    ctk_widget_path_ref (CtkWidgetPath *path);

Increments the reference count on `path` .

#### Parameters

path | a CtkWidgetPath |

#### Returns

`path` itself.

Since: 3.2

### ctk_widget_path_unref ()

    void
    ctk_widget_path_unref (CtkWidgetPath *path);

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

#### Parameters

path | a CtkWidgetPath |

Since: 3.2

### ctk_widget_path_free ()

    void
    ctk_widget_path_free (CtkWidgetPath *path);

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

#### Parameters

path | a CtkWidgetPath |

Since: 3.0

### ctk_widget_path_get_object_type ()

    GType
    ctk_widget_path_get_object_type (const CtkWidgetPath *path);

Returns the topmost object type, that is, the object type this path is representing.

#### Parameters

path | a CtkWidget |

#### Returns

The object type

Since: 3.0

### ctk_widget_path_has_parent ()

    gboolean
    ctk_widget_path_has_parent (const CtkWidgetPath *path,
                                GType type);

Returns `TRUE` if any of the parents of the widget represented in `path` is of type `type` , or any subtype of it.

#### Parameters

path | a CtkWidgetPath |
type | widget type to check in parents |

#### Returns

`TRUE` if any parent is of type `type`

Since: 3.0

### ctk_widget_path_is_type ()

    gboolean
    ctk_widget_path_is_type (const CtkWidgetPath *path,
                             GType type);

Returns `TRUE` if the widget type represented by this path is `type` , or a subtype of it.

#### Parameters

path | a CtkWidgetPath |
type | widget type to match |

#### Returns

`TRUE` if the widget represented by `path` is of type `type`

Since: 3.0

### ctk_widget_path_iter_add_class ()

    void
    ctk_widget_path_iter_add_class (CtkWidgetPath *path,
                                    gint pos,
                                    const gchar *name);

Adds the class `name` to the widget at position `pos` in the hierarchy defined in `path` . See `ctk_style_context_add_class()`.

#### Parameters

path | a CtkWidget |
pos | position to modify, -1 for the path head |
name | a class name |

Since: 3.0

### ctk_widget_path_iter_add_region ()

    void
    ctk_widget_path_iter_add_region (CtkWidgetPath *path,
                                     gint pos,
                                     const gchar *name,
                                     CtkRegionFlags flags);

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

The use of regions is deprecated.

Adds the region `name` to the widget at position `pos` in the hierarchy defined in `path` . See `ctk_style_context_add_region()`.

Region names must only contain lowercase letters and “-”, starting always with a lowercase letter.

#### Parameters

path | a CtkWidgetPath |
pos | position to modify, -1 for the path head |
name | region name |
flags | flags affecting the region |

Since: 3.0

### ctk_widget_path_iter_clear_classes ()

    void
    ctk_widget_path_iter_clear_classes (CtkWidgetPath *path,
                                        gint pos);

Removes all classes from the widget at position `pos` in the hierarchy defined in `path` .

#### Parameters

path | a CtkWidget |
pos | position to modify, -1 for the path head |

Since: 3.0

### ctk_widget_path_iter_clear_regions ()

    void
    ctk_widget_path_iter_clear_regions (CtkWidgetPath *path,
                                        gint pos);

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

The use of regions is deprecated.

Removes all regions from the widget at position `pos` in the hierarchy defined in `path` .

#### Parameters

path | a CtkWidgetPath |
pos | position to modify, -1 for the path head |

Since: 3.0

### ctk_widget_path_iter_get_name ()

    const gchar *
    ctk_widget_path_iter_get_name (const CtkWidgetPath *path,
                                   gint pos);

Returns the name corresponding to the widget found at the position `pos` in the widget hierarchy defined by `path`

#### Parameters

path | a CtkWidgetPath |
pos | position to get the widget name for, -1 for the path head |

#### Returns

The widget name, or `NULL` if none was set.

[nullable]

### ctk_widget_path_iter_get_object_name ()

    const char *
    ctk_widget_path_iter_get_object_name (const CtkWidgetPath *path,
                                          gint pos);

Returns the object name that is at position `pos` in the widget hierarchy defined in `path` .

#### Parameters

path | a CtkWidgetPath |
pos | position to get the object name for, -1 for the path head |

#### Returns

the name or `NULL`.

[nullable]

Since: 3.20

### ctk_widget_path_iter_get_object_type ()

    GType
    ctk_widget_path_iter_get_object_type (const CtkWidgetPath *path,
                                          gint pos);

Returns the object GType that is at position `pos` in the widget hierarchy defined in `path` .

#### Parameters

path | a CtkWidgetPath |
pos | position to get the object type for, -1 for the path head |

#### Returns

a widget type

Since: 3.0

### ctk_widget_path_iter_get_siblings ()

    const CtkWidgetPath *
    ctk_widget_path_iter_get_siblings (const CtkWidgetPath *path,
                                       gint pos);

Returns the list of siblings for the element at `pos` . If the element was not added with siblings, `NULL` is returned.

#### Parameters

path | a CtkWidgetPath |
pos | position to get the siblings for, -1 for the path head |

#### Returns

`NULL` or the list of siblings for the element at `pos` .

### ctk_widget_path_iter_get_sibling_index ()

    guint
    ctk_widget_path_iter_get_sibling_index
                                   (const CtkWidgetPath *path,
                                    gint pos);

Returns the index into the list of siblings for the element at `pos` as returned by `ctk_widget_path_iter_get_siblings()`. If that function would return `NULL` because the element at `pos` has no siblings, this function will return 0.

#### Parameters

path | a CtkWidgetPath |
pos | position to get the sibling index for, -1 for the path head |

#### Returns

0 or the index into the list of siblings for the element at `pos` .

### ctk_widget_path_iter_get_state ()

    CtkStateFlags
    ctk_widget_path_iter_get_state (const CtkWidgetPath *path,
                                    gint pos);

Returns the state flags corresponding to the widget found at the position `pos` in the widget hierarchy defined by `path`

#### Parameters

path | a CtkWidgetPath |
pos | position to get the state for, -1 for the path head |

#### Returns

The state flags

Since: 3.14

### ctk_widget_path_iter_has_class ()

    gboolean
    ctk_widget_path_iter_has_class (const CtkWidgetPath *path,
                                    gint pos,
                                    const gchar *name);

Returns `TRUE` if the widget at position `pos` has the class `name` defined, `FALSE` otherwise.

#### Parameters

path | a CtkWidgetPath |
pos | position to query, -1 for the path head |
name | class name |

#### Returns

`TRUE` if the class `name` is defined for the widget at `pos`

Since: 3.0

### ctk_widget_path_iter_has_name ()

    gboolean
    ctk_widget_path_iter_has_name (const CtkWidgetPath *path,
                                   gint pos,
                                   const gchar *name);

Returns `TRUE` if the widget at position `pos` has the name `name` , `FALSE` otherwise.

#### Parameters

path | a CtkWidgetPath |
pos | position to query, -1 for the path head |
name | a widget name |

#### Returns

`TRUE` if the widget at `pos` has this name

Since: 3.0

### ctk_widget_path_iter_has_qclass ()

    gboolean
    ctk_widget_path_iter_has_qclass (const CtkWidgetPath *path,
                                     gint pos,
                                     GQuark qname);

See `ctk_widget_path_iter_has_class()`. This is a version that operates with GQuarks.

#### Parameters

path | a CtkWidgetPath |
pos | position to query, -1 for the path head |
qname | class name as a GQuark |

#### Returns

`TRUE` if the widget at `pos` has the class defined.

Since: 3.0

### ctk_widget_path_iter_has_qname ()

    gboolean
    ctk_widget_path_iter_has_qname (const CtkWidgetPath *path,
                                    gint pos,
                                    GQuark qname);

See `ctk_widget_path_iter_has_name()`. This is a version that operates on GQuarks.

#### Parameters

path | a CtkWidgetPath |
pos | position to query, -1 for the path head |
qname | widget name as a GQuark |

#### Returns

`TRUE` if the widget at `pos` has this name

Since: 3.0

### ctk_widget_path_iter_has_qregion ()

    gboolean
    ctk_widget_path_iter_has_qregion (const CtkWidgetPath *path,
                                      gint pos,
                                      GQuark qname,
                                      CtkRegionFlags *flags);

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

The use of regions is deprecated.

See `ctk_widget_path_iter_has_region()`. This is a version that operates with GQuarks.

#### Parameters

path | a CtkWidgetPath |
pos | position to query, -1 for the path head |
qname | region name as a GQuark |
flags | return location for the region flags. | [out]

#### Returns

`TRUE` if the widget at `pos` has the region defined.

Since: 3.0

### ctk_widget_path_iter_has_region ()

    gboolean
    ctk_widget_path_iter_has_region (const CtkWidgetPath *path,
                                     gint pos,
                                     const gchar *name,
                                     CtkRegionFlags *flags);

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

The use of regions is deprecated.

Returns `TRUE` if the widget at position `pos` has the class `name` defined, `FALSE` otherwise.

#### Parameters

path | a CtkWidgetPath |
pos | position to query, -1 for the path head |
name | region name |
flags | return location for the region flags. | [out]

#### Returns

`TRUE` if the class `name` is defined for the widget at `pos`

Since: 3.0

### ctk_widget_path_iter_list_classes ()

    GSList *
    ctk_widget_path_iter_list_classes (const CtkWidgetPath *path,
                                       gint pos);

Returns a list with all the class names defined for the widget at position `pos` in the hierarchy defined in `path` .

#### Parameters

path | a CtkWidgetPath |
pos | position to query, -1 for the path head |

#### Returns

The list of classes, This is a list of strings, the GSList contents are owned by CTK+, but you should use `g_slist_free()` to free the list itself.

[transfer container][element-type utf8]

Since: 3.0

### ctk_widget_path_iter_list_regions ()

    GSList *
    ctk_widget_path_iter_list_regions (const CtkWidgetPath *path,
                                       gint pos);

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

The use of regions is deprecated.

Returns a list with all the region names defined for the widget at position `pos` in the hierarchy defined in `path` .

#### Parameters

path | a CtkWidgetPath |
pos | position to query, -1 for the path head |

#### Returns

The list of regions, This is a list of strings, the GSList contents are owned by CTK+, but you should use `g_slist_free()` to free the list itself.

[transfer container][element-type utf8]

Since: 3.0

### ctk_widget_path_iter_remove_class ()

    void
    ctk_widget_path_iter_remove_class (CtkWidgetPath *path,
                                       gint pos,
                                       const gchar *name);

Removes the class `name` from the widget at position `pos` in the hierarchy defined in `path` .

#### Parameters

path | a CtkWidgetPath |
pos | position to modify, -1 for the path head |
name | class name |

Since: 3.0

### ctk_widget_path_iter_remove_region ()

    void
    ctk_widget_path_iter_remove_region (CtkWidgetPath *path,
                                        gint pos,
                                        const gchar *name);

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

The use of regions is deprecated.

Removes the region `name` from the widget at position `pos` in the hierarchy defined in `path` .

#### Parameters

path | a CtkWidgetPath |
pos | position to modify, -1 for the path head |
name | region name |

Since: 3.0

### ctk_widget_path_iter_set_name ()

    void
    ctk_widget_path_iter_set_name (CtkWidgetPath *path,
                                   gint pos,
                                   const gchar *name);

Sets the widget name for the widget found at position `pos` in the widget hierarchy defined by `path` .

#### Parameters

path | a CtkWidgetPath |
pos | position to modify, -1 for the path head |
name | widget name |

Since: 3.0

### ctk_widget_path_iter_set_object_name ()

    void
    ctk_widget_path_iter_set_object_name (CtkWidgetPath *path,
                                          gint pos,
                                          const char *name);

Sets the object name for a given position in the widget hierarchy defined by `path` .

When set, the object name overrides the object type when matching CSS.

#### Parameters

path | a CtkWidgetPath |
pos | position to modify, -1 for the path head |
name | object name to set or `NULL` to unset. | [allow-none]

Since: 3.20

### ctk_widget_path_iter_set_object_type ()

    void
    ctk_widget_path_iter_set_object_type (CtkWidgetPath *path,
                                          gint pos,
                                          GType type);

Sets the object type for a given position in the widget hierarchy defined by `path` .

#### Parameters

path | a CtkWidgetPath |
pos | position to modify, -1 for the path head |
type | object type to set |

Since: 3.0

### ctk_widget_path_iter_set_state ()

    void
    ctk_widget_path_iter_set_state (CtkWidgetPath *path,
                                    gint pos,
                                    CtkStateFlags state);

Sets the widget name for the widget found at position `pos` in the widget hierarchy defined by `path` .

If you want to update just a single state flag, you need to do this manually, as this function updates all state flags.

#### Setting a flag

    1
    ctk_widget_path_iter_set_state (path, pos, ctk_widget_path_iter_get_state (path, pos) | flag);

#### Unsetting a flag

    1
    ctk_widget_path_iter_set_state (path, pos, ctk_widget_path_iter_get_state (path, pos) & ~flag);

#### Parameters

path | a CtkWidgetPath |
pos | position to modify, -1 for the path head |
state | state flags |

Since: 3.14

### ctk_widget_path_length ()

    gint
    ctk_widget_path_length (const CtkWidgetPath *path);

Returns the number of CtkWidget GTypes between the represented widget and its topmost container.

#### Parameters

path | a CtkWidgetPath |

#### Returns

the number of elements in the path

Since: 3.0

### ctk_widget_path_new ()

    CtkWidgetPath *
    ctk_widget_path_new (void);

Returns an empty widget path.

#### Returns

A newly created, empty, CtkWidgetPath.

[transfer full]

Since: 3.0

### ctk_widget_path_prepend_type ()

    void
    ctk_widget_path_prepend_type (CtkWidgetPath *path,
                                  GType type);

Prepends a widget type to the widget hierachy represented by `path` .

#### Parameters

path | a CtkWidgetPath |
type | widget type to prepend |

Since: 3.0

### ctk_widget_path_to_string ()

    char *
    ctk_widget_path_to_string (const CtkWidgetPath *path);

Dumps the widget path into a string representation. It tries to match the CSS style as closely as possible (Note that there might be paths that cannot be represented in CSS).

The main use of this code is for debugging purposes, so that you can `g_print()` the path or dump it in a gdb session.

#### Parameters

path | the path |

#### Returns

A new string describing `path` .

Since: 3.2

## Types and Values

### CtkWidgetPath

    typedef struct _CtkWidgetPath CtkWidgetPath;

## See Also

CtkStyleContext