gtk/auto/

widget_path.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{StateFlags, Widget, ffi};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// 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`][crate::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()`][crate::prelude::WidgetExt::path()], and the style
    /// context returned by [`WidgetExt::style_context()`][crate::prelude::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 ⚠️**
    ///
    /// ```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 ⚠️**
    ///
    /// ```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.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct WidgetPath(Shared<ffi::GtkWidgetPath>);

    match fn {
        ref => |ptr| ffi::gtk_widget_path_ref(ptr),
        unref => |ptr| ffi::gtk_widget_path_unref(ptr),
        type_ => || ffi::gtk_widget_path_get_type(),
    }
}

impl WidgetPath {
    /// Returns an empty widget path.
    ///
    /// # Returns
    ///
    /// A newly created, empty, [`WidgetPath`][crate::WidgetPath]
    #[doc(alias = "gtk_widget_path_new")]
    pub fn new() -> WidgetPath {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gtk_widget_path_new()) }
    }

    /// 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
    #[doc(alias = "gtk_widget_path_append_for_widget")]
    pub fn append_for_widget(&self, widget: &impl IsA<Widget>) -> i32 {
        unsafe {
            ffi::gtk_widget_path_append_for_widget(
                self.to_glib_none().0,
                widget.as_ref().to_glib_none().0,
            )
        }
    }

    /// Appends a widget type to the widget hierarchy represented by `self`.
    /// ## `type_`
    /// widget type to append
    ///
    /// # Returns
    ///
    /// the position where the element was inserted
    #[doc(alias = "gtk_widget_path_append_type")]
    pub fn append_type(&self, type_: glib::types::Type) -> i32 {
        unsafe { ffi::gtk_widget_path_append_type(self.to_glib_none().0, type_.into_glib()) }
    }

    /// Appends a widget type with all its siblings to the widget hierarchy
    /// represented by `self`. Using this function instead of
    /// [`append_type()`][Self::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()`][crate::prelude::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.
    #[doc(alias = "gtk_widget_path_append_with_siblings")]
    pub fn append_with_siblings(&self, siblings: &WidgetPath, sibling_index: u32) -> i32 {
        unsafe {
            ffi::gtk_widget_path_append_with_siblings(
                self.to_glib_none().0,
                siblings.to_glib_none().0,
                sibling_index,
            )
        }
    }

    #[doc(alias = "gtk_widget_path_copy")]
    #[must_use]
    pub fn copy(&self) -> Option<WidgetPath> {
        unsafe { from_glib_full(ffi::gtk_widget_path_copy(self.to_glib_none().0)) }
    }

    /// Returns the topmost object type, that is, the object type this path
    /// is representing.
    ///
    /// # Returns
    ///
    /// The object type
    #[doc(alias = "gtk_widget_path_get_object_type")]
    #[doc(alias = "get_object_type")]
    pub fn object_type(&self) -> glib::types::Type {
        unsafe { from_glib(ffi::gtk_widget_path_get_object_type(self.to_glib_none().0)) }
    }

    /// 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_`
    #[doc(alias = "gtk_widget_path_has_parent")]
    pub fn has_parent(&self, type_: glib::types::Type) -> bool {
        unsafe {
            from_glib(ffi::gtk_widget_path_has_parent(
                self.to_glib_none().0,
                type_.into_glib(),
            ))
        }
    }

    /// 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_`
    #[doc(alias = "gtk_widget_path_is_type")]
    pub fn is_type(&self, type_: glib::types::Type) -> bool {
        unsafe {
            from_glib(ffi::gtk_widget_path_is_type(
                self.to_glib_none().0,
                type_.into_glib(),
            ))
        }
    }

    /// Adds the class `name` to the widget at position `pos` in
    /// the hierarchy defined in `self`. See
    /// [`StyleContextExt::add_class()`][crate::prelude::StyleContextExt::add_class()].
    /// ## `pos`
    /// position to modify, -1 for the path head
    /// ## `name`
    /// a class name
    #[doc(alias = "gtk_widget_path_iter_add_class")]
    pub fn iter_add_class(&self, pos: i32, name: &str) {
        unsafe {
            ffi::gtk_widget_path_iter_add_class(self.to_glib_none().0, pos, name.to_glib_none().0);
        }
    }

    /// Removes all classes from the widget at position `pos` in the
    /// hierarchy defined in `self`.
    /// ## `pos`
    /// position to modify, -1 for the path head
    #[doc(alias = "gtk_widget_path_iter_clear_classes")]
    pub fn iter_clear_classes(&self, pos: i32) {
        unsafe {
            ffi::gtk_widget_path_iter_clear_classes(self.to_glib_none().0, pos);
        }
    }

    /// 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.
    #[doc(alias = "gtk_widget_path_iter_get_name")]
    pub fn iter_get_name(&self, pos: i32) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::gtk_widget_path_iter_get_name(
                self.to_glib_none().0,
                pos,
            ))
        }
    }

    /// 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`]
    #[doc(alias = "gtk_widget_path_iter_get_object_name")]
    pub fn iter_get_object_name(&self, pos: i32) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::gtk_widget_path_iter_get_object_name(
                self.to_glib_none().0,
                pos,
            ))
        }
    }

    /// 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
    #[doc(alias = "gtk_widget_path_iter_get_object_type")]
    pub fn iter_get_object_type(&self, pos: i32) -> glib::types::Type {
        unsafe {
            from_glib(ffi::gtk_widget_path_iter_get_object_type(
                self.to_glib_none().0,
                pos,
            ))
        }
    }

    /// Returns the index into the list of siblings for the element at `pos` as
    /// returned by [`iter_get_siblings()`][Self::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`.
    #[doc(alias = "gtk_widget_path_iter_get_sibling_index")]
    pub fn iter_get_sibling_index(&self, pos: i32) -> u32 {
        unsafe { ffi::gtk_widget_path_iter_get_sibling_index(self.to_glib_none().0, pos) }
    }

    /// 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`.
    #[doc(alias = "gtk_widget_path_iter_get_siblings")]
    #[must_use]
    pub fn iter_get_siblings(&self, pos: i32) -> Option<WidgetPath> {
        unsafe {
            from_glib_none(ffi::gtk_widget_path_iter_get_siblings(
                self.to_glib_none().0,
                pos,
            ))
        }
    }

    /// 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
    #[doc(alias = "gtk_widget_path_iter_get_state")]
    pub fn iter_get_state(&self, pos: i32) -> StateFlags {
        unsafe {
            from_glib(ffi::gtk_widget_path_iter_get_state(
                self.to_glib_none().0,
                pos,
            ))
        }
    }

    /// 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`
    #[doc(alias = "gtk_widget_path_iter_has_class")]
    pub fn iter_has_class(&self, pos: i32, name: &str) -> bool {
        unsafe {
            from_glib(ffi::gtk_widget_path_iter_has_class(
                self.to_glib_none().0,
                pos,
                name.to_glib_none().0,
            ))
        }
    }

    /// 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
    #[doc(alias = "gtk_widget_path_iter_has_name")]
    pub fn iter_has_name(&self, pos: i32, name: &str) -> bool {
        unsafe {
            from_glib(ffi::gtk_widget_path_iter_has_name(
                self.to_glib_none().0,
                pos,
                name.to_glib_none().0,
            ))
        }
    }

    /// See [`iter_has_class()`][Self::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.
    #[doc(alias = "gtk_widget_path_iter_has_qclass")]
    pub fn iter_has_qclass(&self, pos: i32, qname: glib::Quark) -> bool {
        unsafe {
            from_glib(ffi::gtk_widget_path_iter_has_qclass(
                self.to_glib_none().0,
                pos,
                qname.into_glib(),
            ))
        }
    }

    /// See [`iter_has_name()`][Self::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
    #[doc(alias = "gtk_widget_path_iter_has_qname")]
    pub fn iter_has_qname(&self, pos: i32, qname: glib::Quark) -> bool {
        unsafe {
            from_glib(ffi::gtk_widget_path_iter_has_qname(
                self.to_glib_none().0,
                pos,
                qname.into_glib(),
            ))
        }
    }

    /// 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.
    #[doc(alias = "gtk_widget_path_iter_list_classes")]
    pub fn iter_list_classes(&self, pos: i32) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_container(ffi::gtk_widget_path_iter_list_classes(
                self.to_glib_none().0,
                pos,
            ))
        }
    }

    /// 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
    #[doc(alias = "gtk_widget_path_iter_remove_class")]
    pub fn iter_remove_class(&self, pos: i32, name: &str) {
        unsafe {
            ffi::gtk_widget_path_iter_remove_class(
                self.to_glib_none().0,
                pos,
                name.to_glib_none().0,
            );
        }
    }

    /// 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
    #[doc(alias = "gtk_widget_path_iter_set_name")]
    pub fn iter_set_name(&self, pos: i32, name: &str) {
        unsafe {
            ffi::gtk_widget_path_iter_set_name(self.to_glib_none().0, pos, name.to_glib_none().0);
        }
    }

    /// 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
    #[doc(alias = "gtk_widget_path_iter_set_object_name")]
    pub fn iter_set_object_name(&self, pos: i32, name: Option<&str>) {
        unsafe {
            ffi::gtk_widget_path_iter_set_object_name(
                self.to_glib_none().0,
                pos,
                name.to_glib_none().0,
            );
        }
    }

    /// 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
    #[doc(alias = "gtk_widget_path_iter_set_object_type")]
    pub fn iter_set_object_type(&self, pos: i32, type_: glib::types::Type) {
        unsafe {
            ffi::gtk_widget_path_iter_set_object_type(
                self.to_glib_none().0,
                pos,
                type_.into_glib(),
            );
        }
    }

    /// 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 ⚠️**
    ///
    /// ```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 ⚠️**
    ///
    /// ```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
    #[doc(alias = "gtk_widget_path_iter_set_state")]
    pub fn iter_set_state(&self, pos: i32, state: StateFlags) {
        unsafe {
            ffi::gtk_widget_path_iter_set_state(self.to_glib_none().0, pos, state.into_glib());
        }
    }

    /// Returns the number of [`Widget`][crate::Widget] `GTypes` between the represented
    /// widget and its topmost container.
    ///
    /// # Returns
    ///
    /// the number of elements in the path
    #[doc(alias = "gtk_widget_path_length")]
    pub fn length(&self) -> i32 {
        unsafe { ffi::gtk_widget_path_length(self.to_glib_none().0) }
    }

    /// Prepends a widget type to the widget hierachy represented by `self`.
    /// ## `type_`
    /// widget type to prepend
    #[doc(alias = "gtk_widget_path_prepend_type")]
    pub fn prepend_type(&self, type_: glib::types::Type) {
        unsafe {
            ffi::gtk_widget_path_prepend_type(self.to_glib_none().0, type_.into_glib());
        }
    }

    /// 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`.
    #[doc(alias = "gtk_widget_path_to_string")]
    #[doc(alias = "to_string")]
    pub fn to_str(&self) -> glib::GString {
        unsafe { from_glib_full(ffi::gtk_widget_path_to_string(self.to_glib_none().0)) }
    }
}

impl Default for WidgetPath {
    fn default() -> Self {
        Self::new()
    }
}

impl std::fmt::Display for WidgetPath {
    #[inline]
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        f.write_str(&self.to_str())
    }
}