atk/auto/

component.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 = "v2_30")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_30")))]
use crate::ScrollType;
use crate::{CoordType, Layer, Object, Rectangle, ffi};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// The ATK interface provided by UI components
    /// which occupy a physical area on the screen.
    /// which the user can activate/interact with.
    ///
    /// [`Component`][crate::Component] should be implemented by most if not all UI elements
    /// with an actual on-screen presence, i.e. components which can be
    /// said to have a screen-coordinate bounding box. Virtually all
    /// widgets will need to have [`Component`][crate::Component] implementations provided
    /// for their corresponding [`Object`][crate::Object] class. In short, only UI
    /// elements which are *not* GUI elements will omit this ATK interface.
    ///
    /// A possible exception might be textual information with a
    /// transparent background, in which case text glyph bounding box
    /// information is provided by [`Text`][crate::Text].
    ///
    /// ## Signals
    ///
    ///
    /// #### `bounds-changed`
    ///  The 'bounds-changed" signal is emitted when the position or
    /// size of the component changes.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`ComponentExt`][trait@crate::prelude::ComponentExt]
    #[doc(alias = "AtkComponent")]
    pub struct Component(Interface<ffi::AtkComponent, ffi::AtkComponentIface>);

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

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

/// Trait containing all [`struct@Component`] methods.
///
/// # Implementors
///
/// [`Component`][struct@crate::Component], [`NoOpObject`][struct@crate::NoOpObject], [`Plug`][struct@crate::Plug], [`Socket`][struct@crate::Socket]
pub trait ComponentExt: IsA<Component> + 'static {
    /// Checks whether the specified point is within the extent of the `self`.
    ///
    /// Toolkit implementor note: ATK provides a default implementation for
    /// this virtual method. In general there are little reason to
    /// re-implement it.
    /// ## `x`
    /// x coordinate
    /// ## `y`
    /// y coordinate
    /// ## `coord_type`
    /// specifies whether the coordinates are relative to the screen
    /// or to the components top level window
    ///
    /// # Returns
    ///
    /// [`true`] or [`false`] indicating whether the specified point is within
    /// the extent of the `self` or not
    #[doc(alias = "atk_component_contains")]
    fn contains(&self, x: i32, y: i32, coord_type: CoordType) -> bool {
        unsafe {
            from_glib(ffi::atk_component_contains(
                self.as_ref().to_glib_none().0,
                x,
                y,
                coord_type.into_glib(),
            ))
        }
    }

    /// Returns the alpha value (i.e. the opacity) for this
    /// `self`, on a scale from 0 (fully transparent) to 1.0
    /// (fully opaque).
    ///
    /// # Returns
    ///
    /// An alpha value from 0 to 1.0, inclusive.
    #[doc(alias = "atk_component_get_alpha")]
    #[doc(alias = "get_alpha")]
    fn alpha(&self) -> f64 {
        unsafe { ffi::atk_component_get_alpha(self.as_ref().to_glib_none().0) }
    }

    /// Gets the rectangle which gives the extent of the `self`.
    ///
    /// If the extent can not be obtained (e.g. a non-embedded plug or missing
    /// support), all of x, y, width, height are set to -1.
    /// ## `coord_type`
    /// specifies whether the coordinates are relative to the screen
    /// or to the components top level window
    ///
    /// # Returns
    ///
    ///
    /// ## `x`
    /// address of `gint` to put x coordinate
    ///
    /// ## `y`
    /// address of `gint` to put y coordinate
    ///
    /// ## `width`
    /// address of `gint` to put width
    ///
    /// ## `height`
    /// address of `gint` to put height
    #[doc(alias = "atk_component_get_extents")]
    #[doc(alias = "get_extents")]
    fn extents(&self, coord_type: CoordType) -> (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();
            ffi::atk_component_get_extents(
                self.as_ref().to_glib_none().0,
                x.as_mut_ptr(),
                y.as_mut_ptr(),
                width.as_mut_ptr(),
                height.as_mut_ptr(),
                coord_type.into_glib(),
            );
            (
                x.assume_init(),
                y.assume_init(),
                width.assume_init(),
                height.assume_init(),
            )
        }
    }

    /// Gets the layer of the component.
    ///
    /// # Returns
    ///
    /// an [`Layer`][crate::Layer] which is the layer of the component
    #[doc(alias = "atk_component_get_layer")]
    #[doc(alias = "get_layer")]
    fn layer(&self) -> Layer {
        unsafe { from_glib(ffi::atk_component_get_layer(self.as_ref().to_glib_none().0)) }
    }

    /// Gets the zorder of the component. The value G_MININT will be returned
    /// if the layer of the component is not ATK_LAYER_MDI or ATK_LAYER_WINDOW.
    ///
    /// # Returns
    ///
    /// a gint which is the zorder of the component, i.e. the depth at
    /// which the component is shown in relation to other components in the same
    /// container.
    #[doc(alias = "atk_component_get_mdi_zorder")]
    #[doc(alias = "get_mdi_zorder")]
    fn mdi_zorder(&self) -> i32 {
        unsafe { ffi::atk_component_get_mdi_zorder(self.as_ref().to_glib_none().0) }
    }

    /// Gets the position of `self` in the form of
    /// a point specifying `self`'s top-left corner.
    ///
    /// If the position can not be obtained (e.g. a non-embedded plug or missing
    /// support), x and y are set to -1.
    ///
    /// # Deprecated
    ///
    /// Since 2.12. Use [`extents()`][Self::extents()] instead.
    /// ## `coord_type`
    /// specifies whether the coordinates are relative to the screen
    /// or to the components top level window
    ///
    /// # Returns
    ///
    ///
    /// ## `x`
    /// address of `gint` to put x coordinate position
    ///
    /// ## `y`
    /// address of `gint` to put y coordinate position
    #[doc(alias = "atk_component_get_position")]
    #[doc(alias = "get_position")]
    fn position(&self, coord_type: CoordType) -> (i32, i32) {
        unsafe {
            let mut x = std::mem::MaybeUninit::uninit();
            let mut y = std::mem::MaybeUninit::uninit();
            ffi::atk_component_get_position(
                self.as_ref().to_glib_none().0,
                x.as_mut_ptr(),
                y.as_mut_ptr(),
                coord_type.into_glib(),
            );
            (x.assume_init(), y.assume_init())
        }
    }

    /// Gets the size of the `self` in terms of width and height.
    ///
    /// If the size can not be obtained (e.g. a non-embedded plug or missing
    /// support), width and height are set to -1.
    ///
    /// # Deprecated
    ///
    /// Since 2.12. Use [`extents()`][Self::extents()] instead.
    ///
    /// # Returns
    ///
    ///
    /// ## `width`
    /// address of `gint` to put width of `self`
    ///
    /// ## `height`
    /// address of `gint` to put height of `self`
    #[doc(alias = "atk_component_get_size")]
    #[doc(alias = "get_size")]
    fn size(&self) -> (i32, i32) {
        unsafe {
            let mut width = std::mem::MaybeUninit::uninit();
            let mut height = std::mem::MaybeUninit::uninit();
            ffi::atk_component_get_size(
                self.as_ref().to_glib_none().0,
                width.as_mut_ptr(),
                height.as_mut_ptr(),
            );
            (width.assume_init(), height.assume_init())
        }
    }

    /// Grabs focus for this `self`.
    ///
    /// # Returns
    ///
    /// [`true`] if successful, [`false`] otherwise.
    #[doc(alias = "atk_component_grab_focus")]
    fn grab_focus(&self) -> bool {
        unsafe {
            from_glib(ffi::atk_component_grab_focus(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets a reference to the accessible child, if one exists, at the
    /// coordinate point specified by `x` and `y`.
    /// ## `x`
    /// x coordinate
    /// ## `y`
    /// y coordinate
    /// ## `coord_type`
    /// specifies whether the coordinates are relative to the screen
    /// or to the components top level window
    ///
    /// # Returns
    ///
    /// a reference to the accessible
    /// child, if one exists
    #[doc(alias = "atk_component_ref_accessible_at_point")]
    fn ref_accessible_at_point(&self, x: i32, y: i32, coord_type: CoordType) -> Option<Object> {
        unsafe {
            from_glib_full(ffi::atk_component_ref_accessible_at_point(
                self.as_ref().to_glib_none().0,
                x,
                y,
                coord_type.into_glib(),
            ))
        }
    }

    /// Makes `self` visible on the screen by scrolling all necessary parents.
    ///
    /// Contrary to atk_component_set_position, this does not actually move
    /// `self` in its parent, this only makes the parents scroll so that the
    /// object shows up on the screen, given its current position within the parents.
    /// ## `type_`
    /// specify where the object should be made visible.
    ///
    /// # Returns
    ///
    /// whether scrolling was successful.
    #[cfg(feature = "v2_30")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_30")))]
    #[doc(alias = "atk_component_scroll_to")]
    fn scroll_to(&self, type_: ScrollType) -> bool {
        unsafe {
            from_glib(ffi::atk_component_scroll_to(
                self.as_ref().to_glib_none().0,
                type_.into_glib(),
            ))
        }
    }

    /// Move the top-left of `self` to a given position of the screen by
    /// scrolling all necessary parents.
    /// ## `coords`
    /// specify whether coordinates are relative to the screen or to the
    /// parent object.
    /// ## `x`
    /// x-position where to scroll to
    /// ## `y`
    /// y-position where to scroll to
    ///
    /// # Returns
    ///
    /// whether scrolling was successful.
    #[cfg(feature = "v2_30")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_30")))]
    #[doc(alias = "atk_component_scroll_to_point")]
    fn scroll_to_point(&self, coords: CoordType, x: i32, y: i32) -> bool {
        unsafe {
            from_glib(ffi::atk_component_scroll_to_point(
                self.as_ref().to_glib_none().0,
                coords.into_glib(),
                x,
                y,
            ))
        }
    }

    /// Sets the extents of `self`.
    /// ## `x`
    /// x coordinate
    /// ## `y`
    /// y coordinate
    /// ## `width`
    /// width to set for `self`
    /// ## `height`
    /// height to set for `self`
    /// ## `coord_type`
    /// specifies whether the coordinates are relative to the screen
    /// or to the components top level window
    ///
    /// # Returns
    ///
    /// [`true`] or [`false`] whether the extents were set or not
    #[doc(alias = "atk_component_set_extents")]
    fn set_extents(&self, x: i32, y: i32, width: i32, height: i32, coord_type: CoordType) -> bool {
        unsafe {
            from_glib(ffi::atk_component_set_extents(
                self.as_ref().to_glib_none().0,
                x,
                y,
                width,
                height,
                coord_type.into_glib(),
            ))
        }
    }

    /// Sets the position of `self`.
    ///
    /// Contrary to atk_component_scroll_to, this does not trigger any scrolling,
    /// this just moves `self` in its parent.
    /// ## `x`
    /// x coordinate
    /// ## `y`
    /// y coordinate
    /// ## `coord_type`
    /// specifies whether the coordinates are relative to the screen
    /// or to the component's top level window
    ///
    /// # Returns
    ///
    /// [`true`] or [`false`] whether or not the position was set or not
    #[doc(alias = "atk_component_set_position")]
    fn set_position(&self, x: i32, y: i32, coord_type: CoordType) -> bool {
        unsafe {
            from_glib(ffi::atk_component_set_position(
                self.as_ref().to_glib_none().0,
                x,
                y,
                coord_type.into_glib(),
            ))
        }
    }

    /// Set the size of the `self` in terms of width and height.
    /// ## `width`
    /// width to set for `self`
    /// ## `height`
    /// height to set for `self`
    ///
    /// # Returns
    ///
    /// [`true`] or [`false`] whether the size was set or not
    #[doc(alias = "atk_component_set_size")]
    fn set_size(&self, width: i32, height: i32) -> bool {
        unsafe {
            from_glib(ffi::atk_component_set_size(
                self.as_ref().to_glib_none().0,
                width,
                height,
            ))
        }
    }

    /// The 'bounds-changed" signal is emitted when the position or
    /// size of the component changes.
    /// ## `arg1`
    /// The AtkRectangle giving the new position and size.
    #[doc(alias = "bounds-changed")]
    fn connect_bounds_changed<F: Fn(&Self, &Rectangle) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn bounds_changed_trampoline<
            P: IsA<Component>,
            F: Fn(&P, &Rectangle) + 'static,
        >(
            this: *mut ffi::AtkComponent,
            arg1: *mut ffi::AtkRectangle,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    Component::from_glib_borrow(this).unsafe_cast_ref(),
                    &from_glib_borrow(arg1),
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"bounds-changed".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    bounds_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Component>> ComponentExt for O {}