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_widget_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_widget_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_widget_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 36. 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 37. 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_widget_type ()

GType               gtk_widget_path_get_widget_type     (const GtkWidgetPath *path);

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

path :

a GtkWidget

Returns :

The widget 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().

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_widget_type ()

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

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

path :

a GtkWidgetPath

pos :

position to get the widget 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][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][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_widget_type ()

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

Sets the widget type for a given position in the widget hierarchy defined by path. type must be a GtkWidget derived GType.

path :

a GtkWidgetPath

pos :

position to modify, -1 for the path head

type :

widget 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