gtk4/auto/
accessible.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5#[cfg(feature = "v4_14")]
6#[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
7use crate::AccessibleAnnouncementPriority;
8use crate::{ffi, AccessibleProperty, AccessibleRelation, AccessibleRole, AccessibleState};
9#[cfg(feature = "v4_10")]
10#[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
11use crate::{ATContext, AccessiblePlatformState};
12use glib::{
13    prelude::*,
14    signal::{connect_raw, SignalHandlerId},
15    translate::*,
16};
17use std::boxed::Box as Box_;
18
19glib::wrapper! {
20    /// An interface for describing UI elements for Assistive Technologies.
21    ///
22    /// Every accessible implementation has:
23    ///
24    ///  - a “role”, represented by a value of the [`AccessibleRole`][crate::AccessibleRole] enumeration
25    ///  - an “attribute”, represented by a set of [`AccessibleState`][crate::AccessibleState],
26    ///    [`AccessibleProperty`][crate::AccessibleProperty] and [`AccessibleRelation`][crate::AccessibleRelation] values
27    ///
28    /// The role cannot be changed after instantiating a [`Accessible`][crate::Accessible]
29    /// implementation.
30    ///
31    /// The attributes are updated every time a UI element's state changes in
32    /// a way that should be reflected by assistive technologies. For instance,
33    /// if a [`Widget`][crate::Widget] visibility changes, the [`AccessibleState::Hidden`][crate::AccessibleState::Hidden]
34    /// state will also change to reflect the [`visible`][struct@crate::Widget#visible] property.
35    ///
36    /// Every accessible implementation is part of a tree of accessible objects.
37    /// Normally, this tree corresponds to the widget tree, but can be customized
38    /// by reimplementing the `vfunc::Gtk::Accessible::get_accessible_parent`,
39    /// `vfunc::Gtk::Accessible::get_first_accessible_child` and
40    /// `vfunc::Gtk::Accessible::get_next_accessible_sibling` virtual functions.
41    /// Note that you can not create a top-level accessible object as of now,
42    /// which means that you must always have a parent accessible object.
43    /// Also note that when an accessible object does not correspond to a widget,
44    /// and it has children, whose implementation you don't control,
45    /// it is necessary to ensure the correct shape of the a11y tree
46    /// by calling [`AccessibleExt::set_accessible_parent()`][crate::prelude::AccessibleExt::set_accessible_parent()] and
47    /// updating the sibling by [`AccessibleExt::update_next_accessible_sibling()`][crate::prelude::AccessibleExt::update_next_accessible_sibling()].
48    ///
49    /// ## Properties
50    ///
51    ///
52    /// #### `accessible-role`
53    ///  The accessible role of the given [`Accessible`][crate::Accessible] implementation.
54    ///
55    /// The accessible role cannot be changed once set.
56    ///
57    /// Readable | Writeable
58    ///
59    /// # Implements
60    ///
61    /// [`AccessibleExt`][trait@crate::prelude::AccessibleExt], [`AccessibleExtManual`][trait@crate::prelude::AccessibleExtManual]
62    #[doc(alias = "GtkAccessible")]
63    pub struct Accessible(Interface<ffi::GtkAccessible, ffi::GtkAccessibleInterface>);
64
65    match fn {
66        type_ => || ffi::gtk_accessible_get_type(),
67    }
68}
69
70impl Accessible {
71    pub const NONE: Option<&'static Accessible> = None;
72}
73
74/// Trait containing all [`struct@Accessible`] methods.
75///
76/// # Implementors
77///
78/// [`AboutDialog`][struct@crate::AboutDialog], [`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], [`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]
79pub trait AccessibleExt: IsA<Accessible> + 'static {
80    /// Requests the user's screen reader to announce the given message.
81    ///
82    /// This kind of notification is useful for messages that
83    /// either have only a visual representation or that are not
84    /// exposed visually at all, e.g. a notification about a
85    /// successful operation.
86    ///
87    /// Also, by using this API, you can ensure that the message
88    /// does not interrupts the user's current screen reader output.
89    /// ## `message`
90    /// the string to announce
91    /// ## `priority`
92    /// the priority of the announcement
93    #[cfg(feature = "v4_14")]
94    #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
95    #[doc(alias = "gtk_accessible_announce")]
96    fn announce(&self, message: &str, priority: AccessibleAnnouncementPriority) {
97        unsafe {
98            ffi::gtk_accessible_announce(
99                self.as_ref().to_glib_none().0,
100                message.to_glib_none().0,
101                priority.into_glib(),
102            );
103        }
104    }
105
106    /// Retrieves the accessible parent for an accessible object.
107    ///
108    /// This function returns `NULL` for top level widgets.
109    ///
110    /// # Returns
111    ///
112    /// the accessible parent
113    #[cfg(feature = "v4_10")]
114    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
115    #[doc(alias = "gtk_accessible_get_accessible_parent")]
116    #[doc(alias = "get_accessible_parent")]
117    #[must_use]
118    fn accessible_parent(&self) -> Option<Accessible> {
119        unsafe {
120            from_glib_full(ffi::gtk_accessible_get_accessible_parent(
121                self.as_ref().to_glib_none().0,
122            ))
123        }
124    }
125
126    /// Retrieves the accessible role of an accessible object.
127    ///
128    /// # Returns
129    ///
130    /// the accessible role
131    #[doc(alias = "gtk_accessible_get_accessible_role")]
132    #[doc(alias = "get_accessible_role")]
133    #[doc(alias = "accessible-role")]
134    fn accessible_role(&self) -> AccessibleRole {
135        unsafe {
136            from_glib(ffi::gtk_accessible_get_accessible_role(
137                self.as_ref().to_glib_none().0,
138            ))
139        }
140    }
141
142    /// Retrieves the implementation for the given accessible object.
143    ///
144    /// # Returns
145    ///
146    /// the accessible implementation object
147    #[cfg(feature = "v4_10")]
148    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
149    #[doc(alias = "gtk_accessible_get_at_context")]
150    #[doc(alias = "get_at_context")]
151    fn at_context(&self) -> ATContext {
152        unsafe {
153            from_glib_full(ffi::gtk_accessible_get_at_context(
154                self.as_ref().to_glib_none().0,
155            ))
156        }
157    }
158
159    /// Queries the coordinates and dimensions of this accessible
160    ///
161    /// This functionality can be overridden by [`Accessible`][crate::Accessible]
162    /// implementations, e.g. to get the bounds from an ignored
163    /// child widget.
164    ///
165    /// # Returns
166    ///
167    /// true if the bounds are valid, and false otherwise
168    ///
169    /// ## `x`
170    /// the x coordinate of the top left corner of the accessible
171    ///
172    /// ## `y`
173    /// the y coordinate of the top left corner of the widget
174    ///
175    /// ## `width`
176    /// the width of the accessible object
177    ///
178    /// ## `height`
179    /// the height of the accessible object
180    #[cfg(feature = "v4_10")]
181    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
182    #[doc(alias = "gtk_accessible_get_bounds")]
183    #[doc(alias = "get_bounds")]
184    fn bounds(&self) -> Option<(i32, i32, i32, i32)> {
185        unsafe {
186            let mut x = std::mem::MaybeUninit::uninit();
187            let mut y = std::mem::MaybeUninit::uninit();
188            let mut width = std::mem::MaybeUninit::uninit();
189            let mut height = std::mem::MaybeUninit::uninit();
190            let ret = from_glib(ffi::gtk_accessible_get_bounds(
191                self.as_ref().to_glib_none().0,
192                x.as_mut_ptr(),
193                y.as_mut_ptr(),
194                width.as_mut_ptr(),
195                height.as_mut_ptr(),
196            ));
197            if ret {
198                Some((
199                    x.assume_init(),
200                    y.assume_init(),
201                    width.assume_init(),
202                    height.assume_init(),
203                ))
204            } else {
205                None
206            }
207        }
208    }
209
210    /// Retrieves the first accessible child of an accessible object.
211    ///
212    /// # Returns
213    ///
214    /// the first accessible child
215    #[cfg(feature = "v4_10")]
216    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
217    #[doc(alias = "gtk_accessible_get_first_accessible_child")]
218    #[doc(alias = "get_first_accessible_child")]
219    #[must_use]
220    fn first_accessible_child(&self) -> Option<Accessible> {
221        unsafe {
222            from_glib_full(ffi::gtk_accessible_get_first_accessible_child(
223                self.as_ref().to_glib_none().0,
224            ))
225        }
226    }
227
228    /// Retrieves the next accessible sibling of an accessible object
229    ///
230    /// # Returns
231    ///
232    /// the next accessible sibling
233    #[cfg(feature = "v4_10")]
234    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
235    #[doc(alias = "gtk_accessible_get_next_accessible_sibling")]
236    #[doc(alias = "get_next_accessible_sibling")]
237    #[must_use]
238    fn next_accessible_sibling(&self) -> Option<Accessible> {
239        unsafe {
240            from_glib_full(ffi::gtk_accessible_get_next_accessible_sibling(
241                self.as_ref().to_glib_none().0,
242            ))
243        }
244    }
245
246    /// Queries a platform state, such as focus.
247    ///
248    /// This functionality can be overridden by [`Accessible`][crate::Accessible]
249    /// implementations, e.g. to get platform state from an ignored
250    /// child widget, as is the case for [`Text`][crate::Text] wrappers.
251    /// ## `state`
252    /// platform state to query
253    ///
254    /// # Returns
255    ///
256    /// the value of state for the accessible
257    #[cfg(feature = "v4_10")]
258    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
259    #[doc(alias = "gtk_accessible_get_platform_state")]
260    #[doc(alias = "get_platform_state")]
261    fn platform_state(&self, state: AccessiblePlatformState) -> bool {
262        unsafe {
263            from_glib(ffi::gtk_accessible_get_platform_state(
264                self.as_ref().to_glib_none().0,
265                state.into_glib(),
266            ))
267        }
268    }
269
270    /// Resets the accessible property to its default value.
271    /// ## `property`
272    /// the accessible property
273    #[doc(alias = "gtk_accessible_reset_property")]
274    fn reset_property(&self, property: AccessibleProperty) {
275        unsafe {
276            ffi::gtk_accessible_reset_property(
277                self.as_ref().to_glib_none().0,
278                property.into_glib(),
279            );
280        }
281    }
282
283    /// Resets the accessible relation to its default value.
284    /// ## `relation`
285    /// the accessible relation
286    #[doc(alias = "gtk_accessible_reset_relation")]
287    fn reset_relation(&self, relation: AccessibleRelation) {
288        unsafe {
289            ffi::gtk_accessible_reset_relation(
290                self.as_ref().to_glib_none().0,
291                relation.into_glib(),
292            );
293        }
294    }
295
296    /// Resets the accessible state to its default value.
297    /// ## `state`
298    /// the accessible state
299    #[doc(alias = "gtk_accessible_reset_state")]
300    fn reset_state(&self, state: AccessibleState) {
301        unsafe {
302            ffi::gtk_accessible_reset_state(self.as_ref().to_glib_none().0, state.into_glib());
303        }
304    }
305
306    /// Sets the parent and sibling of an accessible object.
307    ///
308    /// This function is meant to be used by accessible implementations that are
309    /// not part of the widget hierarchy, and but act as a logical bridge between
310    /// widgets. For instance, if a widget creates an object that holds metadata
311    /// for each child, and you want that object to implement the [`Accessible`][crate::Accessible]
312    /// interface, you will use this function to ensure that the parent of each
313    /// child widget is the metadata object, and the parent of each metadata
314    /// object is the container widget.
315    /// ## `parent`
316    /// the parent accessible object
317    /// ## `next_sibling`
318    /// the sibling accessible object
319    #[cfg(feature = "v4_10")]
320    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
321    #[doc(alias = "gtk_accessible_set_accessible_parent")]
322    fn set_accessible_parent(
323        &self,
324        parent: Option<&impl IsA<Accessible>>,
325        next_sibling: Option<&impl IsA<Accessible>>,
326    ) {
327        unsafe {
328            ffi::gtk_accessible_set_accessible_parent(
329                self.as_ref().to_glib_none().0,
330                parent.map(|p| p.as_ref()).to_glib_none().0,
331                next_sibling.map(|p| p.as_ref()).to_glib_none().0,
332            );
333        }
334    }
335
336    /// Updates the next accessible sibling.
337    ///
338    /// That might be useful when a new child of a custom accessible
339    /// is created, and it needs to be linked to a previous child.
340    /// ## `new_sibling`
341    /// the new next accessible sibling to set
342    #[cfg(feature = "v4_10")]
343    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
344    #[doc(alias = "gtk_accessible_update_next_accessible_sibling")]
345    fn update_next_accessible_sibling(&self, new_sibling: Option<&impl IsA<Accessible>>) {
346        unsafe {
347            ffi::gtk_accessible_update_next_accessible_sibling(
348                self.as_ref().to_glib_none().0,
349                new_sibling.map(|p| p.as_ref()).to_glib_none().0,
350            );
351        }
352    }
353
354    /// Informs ATs that the platform state has changed.
355    ///
356    /// This function should be used by [`Accessible`][crate::Accessible] implementations that
357    /// have a platform state but are not widgets. Widgets handle platform
358    /// states automatically.
359    /// ## `state`
360    /// the platform state to update
361    #[cfg(feature = "v4_18")]
362    #[cfg_attr(docsrs, doc(cfg(feature = "v4_18")))]
363    #[doc(alias = "gtk_accessible_update_platform_state")]
364    fn update_platform_state(&self, state: AccessiblePlatformState) {
365        unsafe {
366            ffi::gtk_accessible_update_platform_state(
367                self.as_ref().to_glib_none().0,
368                state.into_glib(),
369            );
370        }
371    }
372
373    /// The accessible role of the given [`Accessible`][crate::Accessible] implementation.
374    ///
375    /// The accessible role cannot be changed once set.
376    #[doc(alias = "accessible-role")]
377    fn set_accessible_role(&self, accessible_role: AccessibleRole) {
378        ObjectExt::set_property(self.as_ref(), "accessible-role", accessible_role)
379    }
380
381    #[doc(alias = "accessible-role")]
382    fn connect_accessible_role_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
383        unsafe extern "C" fn notify_accessible_role_trampoline<
384            P: IsA<Accessible>,
385            F: Fn(&P) + 'static,
386        >(
387            this: *mut ffi::GtkAccessible,
388            _param_spec: glib::ffi::gpointer,
389            f: glib::ffi::gpointer,
390        ) {
391            let f: &F = &*(f as *const F);
392            f(Accessible::from_glib_borrow(this).unsafe_cast_ref())
393        }
394        unsafe {
395            let f: Box_<F> = Box_::new(f);
396            connect_raw(
397                self.as_ptr() as *mut _,
398                c"notify::accessible-role".as_ptr() as *const _,
399                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
400                    notify_accessible_role_trampoline::<Self, F> as *const (),
401                )),
402                Box_::into_raw(f),
403            )
404        }
405    }
406}
407
408impl<O: IsA<Accessible>> AccessibleExt for O {}