gtk4/auto/

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

#[cfg(feature = "v4_14")]
#[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
use crate::AccessibleAnnouncementPriority;
use crate::{
    ATContext, AccessiblePlatformState, AccessibleProperty, AccessibleRelation, AccessibleRole,
    AccessibleState, ffi,
};
use glib::{
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// An interface for describing UI elements for Assistive Technologies.
    ///
    /// Every accessible implementation has:
    ///
    ///  - a “role”, represented by a value of the [`AccessibleRole`][crate::AccessibleRole] enumeration
    ///  - “attributes”, represented by a set of [`AccessibleState`][crate::AccessibleState],
    ///    [`AccessibleProperty`][crate::AccessibleProperty] and [`AccessibleRelation`][crate::AccessibleRelation] values
    ///
    /// The role cannot be changed after instantiating a [`Accessible`][crate::Accessible]
    /// implementation.
    ///
    /// The attributes are updated every time a UI element's state changes in
    /// a way that should be reflected by assistive technologies. For instance,
    /// if a [`Widget`][crate::Widget] visibility changes, the [`AccessibleState::Hidden`][crate::AccessibleState::Hidden]
    /// state will also change to reflect the [`visible`][struct@crate::Widget#visible] property.
    ///
    /// Every accessible implementation is part of a tree of accessible objects.
    /// Normally, this tree corresponds to the widget tree, but can be customized
    /// by reimplementing the `vfunc::Gtk::Accessible::get_accessible_parent`,
    /// `vfunc::Gtk::Accessible::get_first_accessible_child` and
    /// `vfunc::Gtk::Accessible::get_next_accessible_sibling` virtual functions.
    ///
    /// Note that you can not create a top-level accessible object as of now,
    /// which means that you must always have a parent accessible object.
    ///
    /// Also note that when an accessible object does not correspond to a widget,
    /// and it has children, whose implementation you don't control,
    /// it is necessary to ensure the correct shape of the a11y tree
    /// by calling [`AccessibleExt::set_accessible_parent()`][crate::prelude::AccessibleExt::set_accessible_parent()] and
    /// updating the sibling by [`AccessibleExt::update_next_accessible_sibling()`][crate::prelude::AccessibleExt::update_next_accessible_sibling()].
    ///
    /// ## Properties
    ///
    ///
    /// #### `accessible-role`
    ///  The accessible role of the given [`Accessible`][crate::Accessible] implementation.
    ///
    /// The accessible role cannot be changed once set.
    ///
    /// Readable | Writable
    ///
    /// # Implements
    ///
    /// [`AccessibleExt`][trait@crate::prelude::AccessibleExt], [`AccessibleExtManual`][trait@crate::prelude::AccessibleExtManual]
    #[doc(alias = "GtkAccessible")]
    pub struct Accessible(Interface<ffi::GtkAccessible, ffi::GtkAccessibleInterface>);

    match fn {
        type_ => || ffi::gtk_accessible_get_type(),
    }
}

impl Accessible {
    pub const NONE: Option<&'static Accessible> = None;
}

/// Trait containing all [`struct@Accessible`] methods.
///
/// # Implementors
///
/// [`AboutDialog`][struct@crate::AboutDialog], [`AccessibleHyperlink`][struct@crate::AccessibleHyperlink], [`AccessibleHypertext`][struct@crate::AccessibleHypertext], [`AccessibleRange`][struct@crate::AccessibleRange], [`AccessibleText`][struct@crate::AccessibleText], [`Accessible`][struct@crate::Accessible], [`ActionBar`][struct@crate::ActionBar], [`AppChooserButton`][struct@crate::AppChooserButton], [`AppChooserDialog`][struct@crate::AppChooserDialog], [`AppChooserWidget`][struct@crate::AppChooserWidget], [`ApplicationWindow`][struct@crate::ApplicationWindow], [`AspectFrame`][struct@crate::AspectFrame], [`Assistant`][struct@crate::Assistant], [`Box`][struct@crate::Box], [`Button`][struct@crate::Button], [`Calendar`][struct@crate::Calendar], [`CellView`][struct@crate::CellView], [`CenterBox`][struct@crate::CenterBox], [`CheckButton`][struct@crate::CheckButton], [`ColorButton`][struct@crate::ColorButton], [`ColorChooserDialog`][struct@crate::ColorChooserDialog], [`ColorChooserWidget`][struct@crate::ColorChooserWidget], [`ColorDialogButton`][struct@crate::ColorDialogButton], [`ColumnView`][struct@crate::ColumnView], [`ComboBoxText`][struct@crate::ComboBoxText], [`ComboBox`][struct@crate::ComboBox], [`Dialog`][struct@crate::Dialog], [`DragIcon`][struct@crate::DragIcon], [`DrawingArea`][struct@crate::DrawingArea], [`DropDown`][struct@crate::DropDown], [`EditableLabel`][struct@crate::EditableLabel], [`EmojiChooser`][struct@crate::EmojiChooser], [`Entry`][struct@crate::Entry], [`Expander`][struct@crate::Expander], [`FileChooserDialog`][struct@crate::FileChooserDialog], [`FileChooserWidget`][struct@crate::FileChooserWidget], [`Fixed`][struct@crate::Fixed], [`FlowBoxChild`][struct@crate::FlowBoxChild], [`FlowBox`][struct@crate::FlowBox], [`FontButton`][struct@crate::FontButton], [`FontChooserDialog`][struct@crate::FontChooserDialog], [`FontChooserWidget`][struct@crate::FontChooserWidget], [`FontDialogButton`][struct@crate::FontDialogButton], [`Frame`][struct@crate::Frame], [`GLArea`][struct@crate::GLArea], [`GraphicsOffload`][struct@crate::GraphicsOffload], [`GridView`][struct@crate::GridView], [`Grid`][struct@crate::Grid], [`HeaderBar`][struct@crate::HeaderBar], [`IconView`][struct@crate::IconView], [`Image`][struct@crate::Image], [`InfoBar`][struct@crate::InfoBar], [`Inscription`][struct@crate::Inscription], [`Label`][struct@crate::Label], [`LevelBar`][struct@crate::LevelBar], [`LinkButton`][struct@crate::LinkButton], [`ListBase`][struct@crate::ListBase], [`ListBoxRow`][struct@crate::ListBoxRow], [`ListBox`][struct@crate::ListBox], [`ListView`][struct@crate::ListView], [`LockButton`][struct@crate::LockButton], [`MediaControls`][struct@crate::MediaControls], [`MenuButton`][struct@crate::MenuButton], [`MessageDialog`][struct@crate::MessageDialog], [`Notebook`][struct@crate::Notebook], [`Overlay`][struct@crate::Overlay], [`PageSetupUnixDialog`][struct@crate::PageSetupUnixDialog], [`Paned`][struct@crate::Paned], [`PasswordEntry`][struct@crate::PasswordEntry], [`Picture`][struct@crate::Picture], [`PopoverBin`][struct@crate::PopoverBin], [`PopoverMenuBar`][struct@crate::PopoverMenuBar], [`PopoverMenu`][struct@crate::PopoverMenu], [`Popover`][struct@crate::Popover], [`PrintUnixDialog`][struct@crate::PrintUnixDialog], [`ProgressBar`][struct@crate::ProgressBar], [`Range`][struct@crate::Range], [`Revealer`][struct@crate::Revealer], [`ScaleButton`][struct@crate::ScaleButton], [`Scale`][struct@crate::Scale], [`Scrollbar`][struct@crate::Scrollbar], [`ScrolledWindow`][struct@crate::ScrolledWindow], [`SearchBar`][struct@crate::SearchBar], [`SearchEntry`][struct@crate::SearchEntry], [`Separator`][struct@crate::Separator], [`ShortcutLabel`][struct@crate::ShortcutLabel], [`ShortcutsGroup`][struct@crate::ShortcutsGroup], [`ShortcutsSection`][struct@crate::ShortcutsSection], [`ShortcutsShortcut`][struct@crate::ShortcutsShortcut], [`ShortcutsWindow`][struct@crate::ShortcutsWindow], [`SpinButton`][struct@crate::SpinButton], [`Spinner`][struct@crate::Spinner], [`StackPage`][struct@crate::StackPage], [`StackSidebar`][struct@crate::StackSidebar], [`StackSwitcher`][struct@crate::StackSwitcher], [`Stack`][struct@crate::Stack], [`Statusbar`][struct@crate::Statusbar], [`Switch`][struct@crate::Switch], [`TextView`][struct@crate::TextView], [`Text`][struct@crate::Text], [`ToggleButton`][struct@crate::ToggleButton], [`TreeExpander`][struct@crate::TreeExpander], [`TreeView`][struct@crate::TreeView], [`Video`][struct@crate::Video], [`Viewport`][struct@crate::Viewport], [`VolumeButton`][struct@crate::VolumeButton], [`Widget`][struct@crate::Widget], [`WindowControls`][struct@crate::WindowControls], [`WindowHandle`][struct@crate::WindowHandle], [`Window`][struct@crate::Window]
pub trait AccessibleExt: IsA<Accessible> + 'static {
    /// Requests the user's screen reader to announce the given message.
    ///
    /// This kind of notification is useful for messages that
    /// either have only a visual representation or that are not
    /// exposed visually at all, e.g. a notification about a
    /// successful operation.
    ///
    /// Also, by using this API, you can ensure that the message
    /// does not interrupts the user's current screen reader output.
    /// ## `message`
    /// the string to announce
    /// ## `priority`
    /// the priority of the announcement
    #[cfg(feature = "v4_14")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
    #[doc(alias = "gtk_accessible_announce")]
    fn announce(&self, message: &str, priority: AccessibleAnnouncementPriority) {
        unsafe {
            ffi::gtk_accessible_announce(
                self.as_ref().to_glib_none().0,
                message.to_glib_none().0,
                priority.into_glib(),
            );
        }
    }

    /// Retrieves the accessible identifier for the accessible object.
    ///
    /// This functionality can be overridden by [`Accessible`][crate::Accessible]
    /// implementations.
    ///
    /// It is left to the accessible implementation to define the scope
    /// and uniqueness of the identifier.
    ///
    /// # Returns
    ///
    /// the accessible identifier
    #[cfg(feature = "v4_22")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_22")))]
    #[doc(alias = "gtk_accessible_get_accessible_id")]
    #[doc(alias = "get_accessible_id")]
    fn accessible_id(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_full(ffi::gtk_accessible_get_accessible_id(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Retrieves the accessible parent for an accessible object.
    ///
    /// This function returns `NULL` for top level widgets.
    ///
    /// # Returns
    ///
    /// the accessible parent
    #[doc(alias = "gtk_accessible_get_accessible_parent")]
    #[doc(alias = "get_accessible_parent")]
    #[must_use]
    fn accessible_parent(&self) -> Option<Accessible> {
        unsafe {
            from_glib_full(ffi::gtk_accessible_get_accessible_parent(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Retrieves the accessible role of an accessible object.
    ///
    /// # Returns
    ///
    /// the accessible role
    #[doc(alias = "gtk_accessible_get_accessible_role")]
    #[doc(alias = "get_accessible_role")]
    #[doc(alias = "accessible-role")]
    fn accessible_role(&self) -> AccessibleRole {
        unsafe {
            from_glib(ffi::gtk_accessible_get_accessible_role(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Retrieves the implementation for the given accessible object.
    ///
    /// # Returns
    ///
    /// the accessible implementation object
    #[doc(alias = "gtk_accessible_get_at_context")]
    #[doc(alias = "get_at_context")]
    fn at_context(&self) -> ATContext {
        unsafe {
            from_glib_full(ffi::gtk_accessible_get_at_context(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Queries the coordinates and dimensions of this accessible
    ///
    /// This functionality can be overridden by [`Accessible`][crate::Accessible]
    /// implementations, e.g. to get the bounds from an ignored
    /// child widget.
    ///
    /// # Returns
    ///
    /// true if the bounds are valid, and false otherwise
    ///
    /// ## `x`
    /// the x coordinate of the top left corner of the accessible
    ///
    /// ## `y`
    /// the y coordinate of the top left corner of the widget
    ///
    /// ## `width`
    /// the width of the accessible object
    ///
    /// ## `height`
    /// the height of the accessible object
    #[doc(alias = "gtk_accessible_get_bounds")]
    #[doc(alias = "get_bounds")]
    fn bounds(&self) -> Option<(i32, i32, i32, i32)> {
        unsafe {
            let mut x = std::mem::MaybeUninit::uninit();
            let mut y = std::mem::MaybeUninit::uninit();
            let mut width = std::mem::MaybeUninit::uninit();
            let mut height = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gtk_accessible_get_bounds(
                self.as_ref().to_glib_none().0,
                x.as_mut_ptr(),
                y.as_mut_ptr(),
                width.as_mut_ptr(),
                height.as_mut_ptr(),
            ));
            if ret {
                Some((
                    x.assume_init(),
                    y.assume_init(),
                    width.assume_init(),
                    height.assume_init(),
                ))
            } else {
                None
            }
        }
    }

    /// Retrieves the first accessible child of an accessible object.
    ///
    /// # Returns
    ///
    /// the first accessible child
    #[doc(alias = "gtk_accessible_get_first_accessible_child")]
    #[doc(alias = "get_first_accessible_child")]
    #[must_use]
    fn first_accessible_child(&self) -> Option<Accessible> {
        unsafe {
            from_glib_full(ffi::gtk_accessible_get_first_accessible_child(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Retrieves the next accessible sibling of an accessible object
    ///
    /// # Returns
    ///
    /// the next accessible sibling
    #[doc(alias = "gtk_accessible_get_next_accessible_sibling")]
    #[doc(alias = "get_next_accessible_sibling")]
    #[must_use]
    fn next_accessible_sibling(&self) -> Option<Accessible> {
        unsafe {
            from_glib_full(ffi::gtk_accessible_get_next_accessible_sibling(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Queries a platform state, such as focus.
    ///
    /// This functionality can be overridden by [`Accessible`][crate::Accessible]
    /// implementations, e.g. to get platform state from an ignored
    /// child widget, as is the case for [`Text`][crate::Text] wrappers.
    /// ## `state`
    /// platform state to query
    ///
    /// # Returns
    ///
    /// the value of state for the accessible
    #[doc(alias = "gtk_accessible_get_platform_state")]
    #[doc(alias = "get_platform_state")]
    fn platform_state(&self, state: AccessiblePlatformState) -> bool {
        unsafe {
            from_glib(ffi::gtk_accessible_get_platform_state(
                self.as_ref().to_glib_none().0,
                state.into_glib(),
            ))
        }
    }

    /// Resets the accessible property to its default value.
    /// ## `property`
    /// the accessible property
    #[doc(alias = "gtk_accessible_reset_property")]
    fn reset_property(&self, property: AccessibleProperty) {
        unsafe {
            ffi::gtk_accessible_reset_property(
                self.as_ref().to_glib_none().0,
                property.into_glib(),
            );
        }
    }

    /// Resets the accessible relation to its default value.
    /// ## `relation`
    /// the accessible relation
    #[doc(alias = "gtk_accessible_reset_relation")]
    fn reset_relation(&self, relation: AccessibleRelation) {
        unsafe {
            ffi::gtk_accessible_reset_relation(
                self.as_ref().to_glib_none().0,
                relation.into_glib(),
            );
        }
    }

    /// Resets the accessible state to its default value.
    /// ## `state`
    /// the accessible state
    #[doc(alias = "gtk_accessible_reset_state")]
    fn reset_state(&self, state: AccessibleState) {
        unsafe {
            ffi::gtk_accessible_reset_state(self.as_ref().to_glib_none().0, state.into_glib());
        }
    }

    /// Sets the parent and sibling of an accessible object.
    ///
    /// This function is meant to be used by accessible implementations that are
    /// not part of the widget hierarchy, and but act as a logical bridge between
    /// widgets. For instance, if a widget creates an object that holds metadata
    /// for each child, and you want that object to implement the [`Accessible`][crate::Accessible]
    /// interface, you will use this function to ensure that the parent of each
    /// child widget is the metadata object, and the parent of each metadata
    /// object is the container widget.
    /// ## `parent`
    /// the parent accessible object
    /// ## `next_sibling`
    /// the sibling accessible object
    #[doc(alias = "gtk_accessible_set_accessible_parent")]
    fn set_accessible_parent(
        &self,
        parent: Option<&impl IsA<Accessible>>,
        next_sibling: Option<&impl IsA<Accessible>>,
    ) {
        unsafe {
            ffi::gtk_accessible_set_accessible_parent(
                self.as_ref().to_glib_none().0,
                parent.map(|p| p.as_ref()).to_glib_none().0,
                next_sibling.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Updates the next accessible sibling.
    ///
    /// That might be useful when a new child of a custom accessible
    /// is created, and it needs to be linked to a previous child.
    /// ## `new_sibling`
    /// the new next accessible sibling to set
    #[doc(alias = "gtk_accessible_update_next_accessible_sibling")]
    fn update_next_accessible_sibling(&self, new_sibling: Option<&impl IsA<Accessible>>) {
        unsafe {
            ffi::gtk_accessible_update_next_accessible_sibling(
                self.as_ref().to_glib_none().0,
                new_sibling.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Informs ATs that the platform state has changed.
    ///
    /// This function should be used by [`Accessible`][crate::Accessible] implementations that
    /// have a platform state but are not widgets. Widgets handle platform
    /// states automatically.
    /// ## `state`
    /// the platform state to update
    #[cfg(feature = "v4_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_18")))]
    #[doc(alias = "gtk_accessible_update_platform_state")]
    fn update_platform_state(&self, state: AccessiblePlatformState) {
        unsafe {
            ffi::gtk_accessible_update_platform_state(
                self.as_ref().to_glib_none().0,
                state.into_glib(),
            );
        }
    }

    #[cfg(not(feature = "v4_10"))]
    #[cfg_attr(docsrs, doc(cfg(not(feature = "v4_10"))))]
    #[doc(alias = "accessible-role")]
    fn accessible_role(&self) -> AccessibleRole {
        ObjectExt::property(self.as_ref(), "accessible-role")
    }

    /// The accessible role of the given [`Accessible`][crate::Accessible] implementation.
    ///
    /// The accessible role cannot be changed once set.
    #[doc(alias = "accessible-role")]
    fn set_accessible_role(&self, accessible_role: AccessibleRole) {
        ObjectExt::set_property(self.as_ref(), "accessible-role", accessible_role)
    }

    #[doc(alias = "accessible-role")]
    fn connect_accessible_role_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_accessible_role_trampoline<
            P: IsA<Accessible>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GtkAccessible,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(Accessible::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::accessible-role".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_accessible_role_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Accessible>> AccessibleExt for O {}