Struct gtk::WidgetPath

#[repr(transparent)]
pub struct WidgetPath { /* private fields */ }

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 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 WidgetExt::path(), and the style context returned by WidgetExt::style_context() will be automatically updated on widget hierarchy changes.

The widget path generation is generally simple:

Defining a button within a window

⚠️ The following code is in C ⚠️

{
  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

⚠️ The following code is in C ⚠️

{
  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.

Implementations

impl WidgetPath

pub fn new() -> WidgetPath

Returns an empty widget path.

Returns

A newly created, empty, WidgetPath

pub fn append_for_widget(&self, widget: &impl IsA<Widget>) -> i32

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.

widget

the widget to append to the widget path

Returns

the position where the data was inserted

pub fn append_type(&self, type_: Type) -> i32

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

type_

widget type to append

Returns

the position where the element was inserted

pub fn append_with_siblings(
    &self,
    siblings: &WidgetPath,
    sibling_index: u32
) -> i32

Appends a widget type with all its siblings to the widget hierarchy represented by self. Using this function instead of 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 WidgetExt::reset_style() on all involved widgets when the siblings path changes.

siblings

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

index into siblings for where the added element is positioned.

Returns

the position where the element was inserted.

pub fn copy(&self) -> Option<WidgetPath>

pub fn object_type(&self) -> Type

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

Returns

The object type

pub fn has_parent(&self, type_: Type) -> bool

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

type_

widget type to check in parents

Returns

true if any parent is of type type_

pub fn is_type(&self, type_: Type) -> bool

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

type_

widget type to match

Returns

true if the widget represented by self is of type type_

pub fn iter_add_class(&self, pos: i32, name: &str)

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

pos

position to modify, -1 for the path head

name

a class name

pub fn iter_clear_classes(&self, pos: i32)

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

pos

position to modify, -1 for the path head

pub fn iter_get_name(&self, pos: i32) -> Option<GString>

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

pos

position to get the widget name for, -1 for the path head

Returns

The widget name, or None if none was set.

pub fn iter_get_object_name(&self, pos: i32) -> Option<GString>

Available on crate feature v3_20 only.

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

pos

position to get the object name for, -1 for the path head

Returns

the name or None

pub fn iter_get_object_type(&self, pos: i32) -> Type

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

pos

position to get the object type for, -1 for the path head

Returns

a widget type

pub fn iter_get_sibling_index(&self, pos: i32) -> u32

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

pos

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.

pub fn iter_get_siblings(&self, pos: i32) -> Option<WidgetPath>

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

pos

position to get the siblings for, -1 for the path head

Returns

None or the list of siblings for the element at pos.

pub fn iter_get_state(&self, pos: i32) -> StateFlags

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

pos

position to get the state for, -1 for the path head

Returns

The state flags

pub fn iter_has_class(&self, pos: i32, name: &str) -> bool

Returns true if the widget at position pos has the class name defined, false otherwise.

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

pub fn iter_has_name(&self, pos: i32, name: &str) -> bool

Returns true if the widget at position pos has the name name, false otherwise.

pos

position to query, -1 for the path head

name

a widget name

Returns

true if the widget at pos has this name

pub fn iter_has_qclass(&self, pos: i32, qname: Quark) -> bool

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

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.

pub fn iter_has_qname(&self, pos: i32, qname: Quark) -> bool

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

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

pub fn iter_list_classes(&self, pos: i32) -> Vec<GString>

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

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.

pub fn iter_remove_class(&self, pos: i32, name: &str)

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

pos

position to modify, -1 for the path head

name

class name

pub fn iter_set_name(&self, pos: i32, name: &str)

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

pos

position to modify, -1 for the path head

name

widget name

pub fn iter_set_object_name(&self, pos: i32, name: Option<&str>)

Available on crate feature v3_20 only.

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.

pos

position to modify, -1 for the path head

name

object name to set or None to unset

pub fn iter_set_object_type(&self, pos: i32, type_: Type)

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

pos

position to modify, -1 for the path head

type_

object type to set

pub fn iter_set_state(&self, pos: i32, state: StateFlags)

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

⚠️ The following code is in C ⚠️

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

Unsetting a flag

⚠️ The following code is in C ⚠️

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

pos

position to modify, -1 for the path head

state

state flags

pub fn length(&self) -> i32

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

Returns

the number of elements in the path

pub fn prepend_type(&self, type_: Type)

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

type_

widget type to prepend

pub fn to_str(&self) -> GString

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.

Returns

A new string describing self.

Trait Implementations

impl Clone for WidgetPath

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WidgetPath

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for WidgetPath

fn default() -> Self

Returns the “default value” for a type.

impl Display for WidgetPath

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for WidgetPath

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for WidgetPath

fn cmp(&self, other: &WidgetPath) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<WidgetPath> for WidgetPath

fn eq(&self, other: &WidgetPath) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &WidgetPath) -> bool

This method tests for !=.

impl PartialOrd<WidgetPath> for WidgetPath

fn partial_cmp(&self, other: &WidgetPath) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for WidgetPath

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for WidgetPath

impl StructuralEq for WidgetPath

impl StructuralPartialEq for WidgetPath