|  |  |  | GTK+ 3 Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | ||||
#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);
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.
gint gtk_widget_path_append_type (GtkWidgetPath *path,GType type);
Appends a widget type to the widget hierachy represented by path.
| 
 | a GtkWidgetPath | 
| 
 | widget type to append | 
| Returns : | the position where the element was inserted | 
Since 3.0
GtkWidgetPath *     gtk_widget_path_copy                (const GtkWidgetPath *path);
Returns a copy of path
| 
 | a GtkWidgetPath | 
| Returns : | a copy of path. [transfer full] | 
Since 3.0
void                gtk_widget_path_free                (GtkWidgetPath *path);
Frees a GtkWidgetPath.
| 
 | a GtkWidgetPath | 
Since 3.0
GType               gtk_widget_path_get_object_type     (const GtkWidgetPath *path);
Returns the topmost object type, that is, the object type this path is representing.
| 
 | a GtkWidget | 
| Returns : | The object type | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | widget type to check in parents | 
| Returns : | TRUEif any parent is of typetype | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | widget type to match | 
| Returns : | TRUEif the widget represented bypathis of typetype | 
Since 3.0
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().
| 
 | a GtkWidget | 
| 
 | position to modify, -1 for the path head | 
| 
 | a class name | 
Since 3.0
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().
Region names must only contain lowercase letters and '-', starting always with a lowercase letter.
| 
 | a GtkWidgetPath | 
| 
 | position to modify, -1 for the path head | 
| 
 | region name | 
| 
 | flags affecting the region | 
Since 3.0
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.
| 
 | a GtkWidget | 
| 
 | position to modify, -1 for the path head | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | position to modify, -1 for the path head | 
Since 3.0
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
| 
 | a GtkWidgetPath | 
| 
 | position to get the widget name for, -1 for the path head | 
| Returns : | The widget name, or NULLif none was set. | 
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.
| 
 | a GtkWidgetPath | 
| 
 | position to get the object type for, -1 for the path head | 
| Returns : | a widget type | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | position to query, -1 for the path head | 
| 
 | class name | 
| Returns : | TRUEif the classnameis defined for the widget atpos | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | position to query, -1 for the path head | 
| 
 | a widget name | 
| Returns : | TRUEif the widget atposhas this name | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | position to query, -1 for the path head | 
| 
 | class name as a GQuark | 
| Returns : | TRUEif the widget atposhas the class defined. | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | position to query, -1 for the path head | 
| 
 | widget name as a GQuark | 
| Returns : | TRUEif the widget atposhas this name | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | position to query, -1 for the path head | 
| 
 | region name as a GQuark | 
| 
 | return location for the region flags. [out] | 
| Returns : | TRUEif the widget atposhas the region defined. | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | position to query, -1 for the path head | 
| 
 | region name | 
| 
 | return location for the region flags. [out] | 
| Returns : | TRUEif the classnameis defined for the widget atpos | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | 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
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.
| 
 | a GtkWidgetPath | 
| 
 | 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
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.
| 
 | a GtkWidgetPath | 
| 
 | position to modify, -1 for the path head | 
| 
 | class name | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | position to modify, -1 for the path head | 
| 
 | region name | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | position to modify, -1 for the path head | 
| 
 | widget name | 
Since 3.0
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.
| 
 | a GtkWidgetPath | 
| 
 | position to modify, -1 for the path head | 
| 
 | object type to set | 
Since 3.0
gint                gtk_widget_path_length              (const GtkWidgetPath *path);
Returns the number of GtkWidget GTypes between the represented widget and its topmost container.
| 
 | a GtkWidgetPath | 
| Returns : | the number of elements in the path | 
Since 3.0
GtkWidgetPath *     gtk_widget_path_new                 (void);
Returns an empty widget path.
| Returns : | A newly created, empty, GtkWidgetPath. [transfer full] | 
Since 3.0
void gtk_widget_path_prepend_type (GtkWidgetPath *path,GType type);
Prepends a widget type to the widget hierachy represented by path.
| 
 | a GtkWidgetPath | 
| 
 | widget type to prepend | 
Since 3.0