![]() |
![]() |
![]() |
GTK+ 3 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <gtk/gtk.h> GtkWidgetPath; gint gtk_widget_path_append_type (GtkWidgetPath *path
,GType type
); gint gtk_widget_path_append_with_siblings (GtkWidgetPath *path
,GtkWidgetPath *siblings
,guint sibling_index
); gint gtk_widget_path_append_for_widget (GtkWidgetPath *path
,GtkWidget *widget
); GtkWidgetPath * gtk_widget_path_copy (const GtkWidgetPath *path
); GtkWidgetPath * gtk_widget_path_ref (GtkWidgetPath *path
); void gtk_widget_path_unref (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
); const GtkWidgetPath * gtk_widget_path_iter_get_siblings (const GtkWidgetPath *path
,gint pos
); guint gtk_widget_path_iter_get_sibling_index (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
); char * gtk_widget_path_to_string (const GtkWidgetPath *path
);
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
{ 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
{ 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 hierarchy represented by path
.
|
a GtkWidgetPath |
|
widget type to append |
Returns : |
the position where the element was inserted |
Since 3.0
gint gtk_widget_path_append_with_siblings (GtkWidgetPath *path
,GtkWidgetPath *siblings
,guint sibling_index
);
Appends a widget type with all its siblings to the widget hierarchy
represented by path
. Using this function instead of
gtk_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 gtk_widget_reset_style()
on all
involved widgets when the siblings
path changes.
|
the widget path to append to |
|
a widget path describing a list of siblings. This path may not contain any siblings itself and it must not be modified afterwards. |
|
index into siblings for where the added element is
positioned. |
Returns : |
the position where the element was inserted. |
Since 3.2
gint gtk_widget_path_append_for_widget (GtkWidgetPath *path
,GtkWidget *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
.
|
a widget path |
|
the widget to append to the widget path |
Returns : |
the position where the data was inserted |
Since 3.2
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
GtkWidgetPath * gtk_widget_path_ref (GtkWidgetPath *path
);
Increments the reference count on path
.
|
a GtkWidgetPath |
Returns : |
path itself. |
Since 3.2
void gtk_widget_path_unref (GtkWidgetPath *path
);
Decrements the reference count on path
, freeing the structure
if the reference count reaches 0.
|
a GtkWidgetPath |
Since 3.2
void gtk_widget_path_free (GtkWidgetPath *path
);
Decrements the reference count on path
, freeing the structure
if the reference count reaches 0.
|
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 : |
TRUE if any parent is of type type
|
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 : |
TRUE if the widget represented by path is of type type
|
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 NULL if 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
const GtkWidgetPath * gtk_widget_path_iter_get_siblings (const GtkWidgetPath *path
,gint pos
);
Returns the list of siblings for the element at pos
. If the element
was not added with siblings, NULL
is returned.
|
a GtkWidgetPath |
|
position to get the siblings for, -1 for the path head |
Returns : |
NULL or the list of siblings for the element at pos . |
guint gtk_widget_path_iter_get_sibling_index (const GtkWidgetPath *path
,gint pos
);
Returns the index into the list of siblings for the element at pos
as
returned by gtk_widget_path_iter_get_siblings()
. If that function would
return NULL
because the element at pos
has no siblings, this function
will return 0.
|
a GtkWidgetPath |
|
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 . |
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 : |
TRUE if the class name is defined for the widget at pos
|
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 : |
TRUE if the widget at pos has 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 : |
TRUE if the widget at pos has 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 : |
TRUE if the widget at pos has 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 : |
TRUE if the widget at pos has 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 : |
TRUE if the class name is defined for the widget at pos
|
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
char * gtk_widget_path_to_string (const GtkWidgetPath *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.
|
the path |
Returns : |
A new string describing path . |
Since 3.2