Gtk.WidgetPath¶

Fields¶

None

Methods¶

class	`new` ()
	`append_for_widget` (widget)
	`append_type` (type)
	`append_with_siblings` (siblings, sibling_index)
	`copy` ()
	`free` ()
	`get_object_type` ()
	`has_parent` (type)
	`is_type` (type)
	`iter_add_class` (pos, name)
	`iter_add_region` (pos, name, flags)
	`iter_clear_classes` (pos)
	`iter_clear_regions` (pos)
	`iter_get_name` (pos)
	`iter_get_object_name` (pos)
	`iter_get_object_type` (pos)
	`iter_get_sibling_index` (pos)
	`iter_get_siblings` (pos)
	`iter_get_state` (pos)
	`iter_has_class` (pos, name)
	`iter_has_name` (pos, name)
	`iter_has_qclass` (pos, qname)
	`iter_has_qname` (pos, qname)
	`iter_has_qregion` (pos, qname)
	`iter_has_region` (pos, name)
	`iter_list_classes` (pos)
	`iter_list_regions` (pos)
	`iter_remove_class` (pos, name)
	`iter_remove_region` (pos, name)
	`iter_set_name` (pos, name)
	`iter_set_object_name` (pos, name)
	`iter_set_object_type` (pos, type)
	`iter_set_state` (pos, state)
	`length` ()
	`prepend_type` (type)
	`ref` ()
	`to_string` ()
	`unref` ()

Details¶

class Gtk.WidgetPath¶

Gtk.WidgetPath 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 Gtk.StyleContext 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:

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:

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.

classmethod new()[source]¶

Returns:: A newly created, empty, Gtk.WidgetPath
Return type:: Gtk.WidgetPath

Returns an empty widget path.

New in version 3.0.

append_for_widget(widget)[source]¶

Parameters:: widget (Gtk.Widget) – the widget to append to the widget path
Returns:: the position where the data was inserted
Return type:: int

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

New in version 3.2.

append_type(type)[source]¶

Parameters:: type (GObject.GType) – widget type to append
Returns:: the position where the element was inserted
Return type:: int

Appends a widget type to the widget hierarchy represented by self.

New in version 3.0.

append_with_siblings(siblings, sibling_index)[source]¶

Parameters:

siblings (Gtk.WidgetPath) – 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 (int) – index into siblings for where the added element is positioned.

Returns:

the position where the element was inserted.

Return type:

int

Appends a widget type with all its siblings to the widget hierarchy represented by self. Using this function instead of Gtk.WidgetPath.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.

New in version 3.2.

copy()[source]¶

Returns:: a copy of self
Return type:: Gtk.WidgetPath

Returns a copy of self

New in version 3.0.

free()[source]¶: Decrements the reference count on self, freeing the structure if the reference count reaches 0.

New in version 3.0.

get_object_type()[source]¶

Returns:: The object type
Return type:: GObject.GType

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

New in version 3.0.

has_parent(type)[source]¶

Parameters:: type (GObject.GType) – widget type to check in parents
Returns:: True if any parent is of type type
Return type:: bool

Returns True if any of the parents of the widget represented in self is of type type, or any subtype of it.

New in version 3.0.

is_type(type)[source]¶

Parameters:: type (GObject.GType) – widget type to match
Returns:: True if the widget represented by self is of type type
Return type:: bool

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

New in version 3.0.

iter_add_class(pos, name)[source]¶

Parameters:

pos (int) – position to modify, -1 for the path head
name (str) – a class name

Adds the class name to the widget at position pos in the hierarchy defined in self. See Gtk.StyleContext.add_class().

New in version 3.0.

iter_add_region(pos, name, flags)[source]¶

Parameters:

pos (int) – position to modify, -1 for the path head
name (str) – region name
flags (Gtk.RegionFlags) – flags affecting the region

Adds the region name to the widget at position pos in the hierarchy defined in self. See Gtk.StyleContext.add_region().

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

New in version 3.0.

Deprecated since version 3.14: The use of regions is deprecated.

iter_clear_classes(pos)[source]¶

Parameters:: pos (int) – position to modify, -1 for the path head

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

New in version 3.0.

iter_clear_regions(pos)[source]¶

Parameters:: pos (int) – position to modify, -1 for the path head

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

New in version 3.0.

Deprecated since version 3.14: The use of regions is deprecated.

iter_get_name(pos)[source]¶

Parameters:: pos (int) – position to get the widget name for, -1 for the path head
Returns:: The widget name, or None if none was set.
Return type:: str or None

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

iter_get_object_name(pos)[source]¶

Parameters:: pos (int) – position to get the object name for, -1 for the path head
Returns:: the name or None
Return type:: str or None

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

New in version 3.20.

iter_get_object_type(pos)[source]¶

Parameters:: pos (int) – position to get the object type for, -1 for the path head
Returns:: a widget type
Return type:: GObject.GType

Returns the object GObject.GType that is at position pos in the widget hierarchy defined in self.

New in version 3.0.

iter_get_sibling_index(pos)[source]¶

Parameters:: pos (int) – 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.
Return type:: int

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

iter_get_siblings(pos)[source]¶

Parameters:: pos (int) – position to get the siblings for, -1 for the path head
Returns:: None or the list of siblings for the element at pos.
Return type:: Gtk.WidgetPath

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

iter_get_state(pos)[source]¶

Parameters:: pos (int) – position to get the state for, -1 for the path head
Returns:: The state flags
Return type:: Gtk.StateFlags

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

New in version 3.14.

iter_has_class(pos, name)[source]¶

Parameters:

pos (int) – position to query, -1 for the path head
name (str) – class name

Returns:

True if the class name is defined for the widget at pos

Return type:

bool

Returns True if the widget at position pos has the class name defined, False otherwise.

New in version 3.0.

iter_has_name(pos, name)[source]¶

Parameters:

pos (int) – position to query, -1 for the path head
name (str) – a widget name

Returns:

True if the widget at pos has this name

Return type:

bool

Returns True if the widget at position pos has the name name, False otherwise.

New in version 3.0.

iter_has_qclass(pos, qname)[source]¶

Parameters:

pos (int) – position to query, -1 for the path head
qname (int) – class name as a #GQuark

Returns:

True if the widget at pos has the class defined.

Return type:

bool

See Gtk.WidgetPath.iter_has_class(). This is a version that operates with GQuarks.

New in version 3.0.

iter_has_qname(pos, qname)[source]¶

Parameters:

pos (int) – position to query, -1 for the path head
qname (int) – widget name as a #GQuark

Returns:

True if the widget at pos has this name

Return type:

bool

See Gtk.WidgetPath.iter_has_name(). This is a version that operates on #GQuarks.

New in version 3.0.

iter_has_qregion(pos, qname)[source]¶

Parameters:

pos (int) – position to query, -1 for the path head
qname (int) – region name as a #GQuark

Returns:

True if the widget at pos has the region defined.

flags:: return location for the region flags

Return type:

(bool, flags: Gtk.RegionFlags)

See Gtk.WidgetPath.iter_has_region(). This is a version that operates with GQuarks.

New in version 3.0.

Deprecated since version 3.14: The use of regions is deprecated.

iter_has_region(pos, name)[source]¶

Parameters:

pos (int) – position to query, -1 for the path head
name (str) – region name

Returns:

True if the class name is defined for the widget at pos

flags:: return location for the region flags

Return type:

(bool, flags: Gtk.RegionFlags)

Returns True if the widget at position pos has the class name defined, False otherwise.

New in version 3.0.

Deprecated since version 3.14: The use of regions is deprecated.

iter_list_classes(pos)[source]¶

Parameters:: pos (int) – position to query, -1 for the path head
Returns:: The list of classes, This is a list of strings, the GLib.SList contents are owned by GTK+, but you should use g_slist_free() to free the list itself.
Return type:: [str]

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

New in version 3.0.

iter_list_regions(pos)[source]¶

Parameters:: pos (int) – position to query, -1 for the path head
Returns:: The list of regions, This is a list of strings, the GLib.SList contents are owned by GTK+, but you should use g_slist_free() to free the list itself.
Return type:: [str]

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

New in version 3.0.

Deprecated since version 3.14: The use of regions is deprecated.

iter_remove_class(pos, name)[source]¶

Parameters:

pos (int) – position to modify, -1 for the path head
name (str) – class name

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

New in version 3.0.

iter_remove_region(pos, name)[source]¶

Parameters:

pos (int) – position to modify, -1 for the path head
name (str) – region name

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

New in version 3.0.

Deprecated since version 3.14: The use of regions is deprecated.

iter_set_name(pos, name)[source]¶

Parameters:

pos (int) – position to modify, -1 for the path head
name (str) – widget name

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

New in version 3.0.

iter_set_object_name(pos, name)[source]¶

Parameters:

pos (int) – position to modify, -1 for the path head
name (str or None) – object name to set or None to unset

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

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

New in version 3.20.

iter_set_object_type(pos, type)[source]¶

Parameters:

pos (int) – position to modify, -1 for the path head
type (GObject.GType) – object type to set

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

New in version 3.0.

iter_set_state(pos, state)[source]¶

Parameters:

pos (int) – position to modify, -1 for the path head
state (Gtk.StateFlags) – state flags

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

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

gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) | flag);

Unsetting a flag

gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) & ~flag);

New in version 3.14.

length()[source]¶

Returns:: the number of elements in the path
Return type:: int

Returns the number of Gtk.Widget GObject.GTypes between the represented widget and its topmost container.

New in version 3.0.

prepend_type(type)[source]¶

Parameters:: type (GObject.GType) – widget type to prepend

Prepends a widget type to the widget hierachy represented by self.

New in version 3.0.

ref()[source]¶

Returns:: self itself.
Return type:: Gtk.WidgetPath

Increments the reference count on self.

New in version 3.2.

to_string()[source]¶

Returns:: A new string describing self.
Return type:: str

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.

New in version 3.2.

unref()[source]¶: Decrements the reference count on self, freeing the structure if the reference count reaches 0.

New in version 3.2.