GtkWidgetPath

## GtkWidgetPath GtkWidgetPath — Widget path abstraction |

## Synopsis

    #include <gtk/gtk.h>

                        GtkWidgetPath;
    gint                gtk_widget_path_append_type         (GtkWidgetPath *path,
                                                             GType type);
    GtkWidgetPath *     gtk_widget_path_copy                (const GtkWidgetPath *path);
    void                gtk_widget_path_free                (GtkWidgetPath *path);
    GType               gtk_widget_path_get_object_type     (const GtkWidgetPath *path);
    gboolean            gtk_widget_path_has_parent          (const GtkWidgetPath *path,
                                                             GType type);
    gboolean            gtk_widget_path_is_type             (const GtkWidgetPath *path,
                                                             GType type);
    void                gtk_widget_path_iter_add_class      (GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);
    void                gtk_widget_path_iter_add_region     (GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name,
                                                             GtkRegionFlags flags);
    void                gtk_widget_path_iter_clear_classes  (GtkWidgetPath *path,
                                                             gint pos);
    void                gtk_widget_path_iter_clear_regions  (GtkWidgetPath *path,
                                                             gint pos);
    const gchar *       gtk_widget_path_iter_get_name       (const GtkWidgetPath *path,
                                                             gint pos);
    GType               gtk_widget_path_iter_get_object_type
                                                            (const GtkWidgetPath *path,
                                                             gint pos);
    gboolean            gtk_widget_path_iter_has_class      (const GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);
    gboolean            gtk_widget_path_iter_has_name       (const GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);
    gboolean            gtk_widget_path_iter_has_qclass     (const GtkWidgetPath *path,
                                                             gint pos,
                                                             GQuark qname);
    gboolean            gtk_widget_path_iter_has_qname      (const GtkWidgetPath *path,
                                                             gint pos,
                                                             GQuark qname);
    gboolean            gtk_widget_path_iter_has_qregion    (const GtkWidgetPath *path,
                                                             gint pos,
                                                             GQuark qname,
                                                             GtkRegionFlags *flags);
    gboolean            gtk_widget_path_iter_has_region     (const GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name,
                                                             GtkRegionFlags *flags);
    GSList *            gtk_widget_path_iter_list_classes   (const GtkWidgetPath *path,
                                                             gint pos);
    GSList *            gtk_widget_path_iter_list_regions   (const GtkWidgetPath *path,
                                                             gint pos);
    void                gtk_widget_path_iter_remove_class   (GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);
    void                gtk_widget_path_iter_remove_region  (GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);
    void                gtk_widget_path_iter_set_name       (GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);
    void                gtk_widget_path_iter_set_object_type
                                                            (GtkWidgetPath *path,
                                                             gint pos,
                                                             GType type);
    gint                gtk_widget_path_length              (const GtkWidgetPath *path);
    GtkWidgetPath *     gtk_widget_path_new                 (void);
    void                gtk_widget_path_prepend_type        (GtkWidgetPath *path,
                                                             GType type);

## Description

GtkWidgetPath 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 GtkStyleContext on behalf of the real widget in order to query style information.

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

The widget path generation is generally simple:

Example 40. Defining a button within a window

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

      path = gtk_widget_path_new ();
      gtk_widget_path_append_type (path, GTK_TYPE_WINDOW);
      gtk_widget_path_append_type (path, GTK_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:

Example 41. Defining the first tab widget in a notebook

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

      path = gtk_widget_path_new ();

      pos = gtk_widget_path_append_type (path, GTK_TYPE_NOTEBOOK);
      gtk_widget_path_iter_add_region (path, pos, "tab", GTK_REGION_EVEN | GTK_REGION_FIRST);

      pos = gtk_widget_path_append_type (path, GTK_TYPE_LABEL);
      gtk_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.

## Details

### GtkWidgetPath

    typedef struct _GtkWidgetPath GtkWidgetPath;

### gtk_widget_path_append_type ()

    gint                gtk_widget_path_append_type         (GtkWidgetPath *path,
                                                             GType type);

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

`path` : | a GtkWidgetPath
`type` : | widget type to append
Returns : | the position where the element was inserted

Since 3.0

### gtk_widget_path_copy ()

    GtkWidgetPath *     gtk_widget_path_copy                (const GtkWidgetPath *path);

Returns a copy of `path`

`path` : | a GtkWidgetPath
Returns : | a copy of `path`. [transfer full]

Since 3.0

### gtk_widget_path_free ()

    void                gtk_widget_path_free                (GtkWidgetPath *path);

Frees a GtkWidgetPath.

`path` : | a GtkWidgetPath

Since 3.0

### gtk_widget_path_get_object_type ()

    GType               gtk_widget_path_get_object_type     (const GtkWidgetPath *path);

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

`path` : | a GtkWidget
Returns : | The object type

Since 3.0

### gtk_widget_path_has_parent ()

    gboolean            gtk_widget_path_has_parent          (const GtkWidgetPath *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.

`path` : | a GtkWidgetPath
`type` : | widget type to check in parents
Returns : | `TRUE` if any parent is of type `type`

Since 3.0

### gtk_widget_path_is_type ()

    gboolean            gtk_widget_path_is_type             (const GtkWidgetPath *path,
                                                             GType type);

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

`path` : | a GtkWidgetPath
`type` : | widget type to match
Returns : | `TRUE` if the widget represented by `path` is of type `type`

Since 3.0

### gtk_widget_path_iter_add_class ()

    void                gtk_widget_path_iter_add_class      (GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);

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

`path` : | a GtkWidget
`pos` : | position to modify, -1 for the path head
`name` : | a class name

Since 3.0

### gtk_widget_path_iter_add_region ()

    void                gtk_widget_path_iter_add_region     (GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name,
                                                             GtkRegionFlags flags);

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

### Note

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

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

Since 3.0

### gtk_widget_path_iter_clear_classes ()

    void                gtk_widget_path_iter_clear_classes  (GtkWidgetPath *path,
                                                             gint pos);

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

`path` : | a GtkWidget
`pos` : | position to modify, -1 for the path head

Since 3.0

### gtk_widget_path_iter_clear_regions ()

    void                gtk_widget_path_iter_clear_regions  (GtkWidgetPath *path,
                                                             gint pos);

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

`path` : | a GtkWidgetPath
`pos` : | position to modify, -1 for the path head

Since 3.0

### gtk_widget_path_iter_get_name ()

    const gchar *       gtk_widget_path_iter_get_name       (const GtkWidgetPath *path,
                                                             gint pos);

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

`path` : | a GtkWidgetPath
`pos` : | position to get the widget name for, -1 for the path head
Returns : | The widget name, or `NULL` if none was set.

### gtk_widget_path_iter_get_object_type ()

    GType               gtk_widget_path_iter_get_object_type
                                                            (const GtkWidgetPath *path,
                                                             gint pos);

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

`path` : | a GtkWidgetPath
`pos` : | position to get the object type for, -1 for the path head
Returns : | a widget type

Since 3.0

### gtk_widget_path_iter_has_class ()

    gboolean            gtk_widget_path_iter_has_class      (const GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);

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

`path` : | a GtkWidgetPath
`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

### gtk_widget_path_iter_has_name ()

    gboolean            gtk_widget_path_iter_has_name       (const GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);

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

`path` : | a GtkWidgetPath
`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

### gtk_widget_path_iter_has_qclass ()

    gboolean            gtk_widget_path_iter_has_qclass     (const GtkWidgetPath *path,
                                                             gint pos,
                                                             GQuark qname);

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

`path` : | a GtkWidgetPath
`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

### gtk_widget_path_iter_has_qname ()

    gboolean            gtk_widget_path_iter_has_qname      (const GtkWidgetPath *path,
                                                             gint pos,
                                                             GQuark qname);

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

`path` : | a GtkWidgetPath
`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

### gtk_widget_path_iter_has_qregion ()

    gboolean            gtk_widget_path_iter_has_qregion    (const GtkWidgetPath *path,
                                                             gint pos,
                                                             GQuark qname,
                                                             GtkRegionFlags *flags);

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

`path` : | a GtkWidgetPath
`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

### gtk_widget_path_iter_has_region ()

    gboolean            gtk_widget_path_iter_has_region     (const GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name,
                                                             GtkRegionFlags *flags);

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

`path` : | a GtkWidgetPath
`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

### gtk_widget_path_iter_list_classes ()

    GSList *            gtk_widget_path_iter_list_classes   (const GtkWidgetPath *path,
                                                             gint pos);

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

`path` : | a GtkWidgetPath
`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 GTK+, but you should use `g_slist_free()` to free the list itself. [transfer container][element-type utf8]

Since 3.0

### gtk_widget_path_iter_list_regions ()

    GSList *            gtk_widget_path_iter_list_regions   (const GtkWidgetPath *path,
                                                             gint pos);

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

`path` : | a GtkWidgetPath
`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 GTK+, but you should use `g_slist_free()` to free the list itself. [transfer container][element-type utf8]

Since 3.0

### gtk_widget_path_iter_remove_class ()

    void                gtk_widget_path_iter_remove_class   (GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);

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

`path` : | a GtkWidgetPath
`pos` : | position to modify, -1 for the path head
`name` : | class name

Since 3.0

### gtk_widget_path_iter_remove_region ()

    void                gtk_widget_path_iter_remove_region  (GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);

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

`path` : | a GtkWidgetPath
`pos` : | position to modify, -1 for the path head
`name` : | region name

Since 3.0

### gtk_widget_path_iter_set_name ()

    void                gtk_widget_path_iter_set_name       (GtkWidgetPath *path,
                                                             gint pos,
                                                             const gchar *name);

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

`path` : | a GtkWidgetPath
`pos` : | position to modify, -1 for the path head
`name` : | widget name

Since 3.0

### gtk_widget_path_iter_set_object_type ()

    void                gtk_widget_path_iter_set_object_type
                                                            (GtkWidgetPath *path,
                                                             gint pos,
                                                             GType type);

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

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

Since 3.0

### gtk_widget_path_length ()

    gint                gtk_widget_path_length              (const GtkWidgetPath *path);

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

`path` : | a GtkWidgetPath
Returns : | the number of elements in the path

Since 3.0

### gtk_widget_path_new ()

    GtkWidgetPath *     gtk_widget_path_new                 (void);

Returns an empty widget path.

Returns : | A newly created, empty, GtkWidgetPath. [transfer full]

Since 3.0

### gtk_widget_path_prepend_type ()

    void                gtk_widget_path_prepend_type        (GtkWidgetPath *path,
                                                             GType type);

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

`path` : | a GtkWidgetPath
`type` : | widget type to prepend

Since 3.0

## See Also

GtkStyleContext