gtk/auto/

icon_info.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::{IconTheme, StyleContext};
use glib::{prelude::*, translate::*};
use std::{boxed::Box as Box_, fmt, mem, pin::Pin, ptr};

glib::wrapper! {
    /// Contains information found when looking up an icon in
    /// an icon theme.
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`]
    #[doc(alias = "GtkIconInfo")]
    pub struct IconInfo(Object<ffi::GtkIconInfo, ffi::GtkIconInfoClass>);

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

impl IconInfo {
    /// Creates a [`IconInfo`][crate::IconInfo] for a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf].
    /// ## `icon_theme`
    /// a [`IconTheme`][crate::IconTheme]
    /// ## `pixbuf`
    /// the pixbuf to wrap in a [`IconInfo`][crate::IconInfo]
    ///
    /// # Returns
    ///
    /// a [`IconInfo`][crate::IconInfo]
    #[doc(alias = "gtk_icon_info_new_for_pixbuf")]
    #[doc(alias = "new_for_pixbuf")]
    pub fn for_pixbuf(icon_theme: &impl IsA<IconTheme>, pixbuf: &gdk_pixbuf::Pixbuf) -> IconInfo {
        skip_assert_initialized!();
        unsafe {
            from_glib_full(ffi::gtk_icon_info_new_for_pixbuf(
                icon_theme.as_ref().to_glib_none().0,
                pixbuf.to_glib_none().0,
            ))
        }
    }

    /// Gets the base scale for the icon. The base scale is a scale
    /// for the icon that was specified by the icon theme creator.
    /// For instance an icon drawn for a high-dpi screen with window
    /// scale 2 for a base size of 32 will be 64 pixels tall and have
    /// a base scale of 2.
    ///
    /// # Returns
    ///
    /// the base scale
    #[doc(alias = "gtk_icon_info_get_base_scale")]
    #[doc(alias = "get_base_scale")]
    pub fn base_scale(&self) -> i32 {
        unsafe { ffi::gtk_icon_info_get_base_scale(self.to_glib_none().0) }
    }

    /// Gets the base size for the icon. The base size
    /// is a size for the icon that was specified by
    /// the icon theme creator. This may be different
    /// than the actual size of image; an example of
    /// this is small emblem icons that can be attached
    /// to a larger icon. These icons will be given
    /// the same base size as the larger icons to which
    /// they are attached.
    ///
    /// Note that for scaled icons the base size does
    /// not include the base scale.
    ///
    /// # Returns
    ///
    /// the base size, or 0, if no base
    ///  size is known for the icon.
    #[doc(alias = "gtk_icon_info_get_base_size")]
    #[doc(alias = "get_base_size")]
    pub fn base_size(&self) -> i32 {
        unsafe { ffi::gtk_icon_info_get_base_size(self.to_glib_none().0) }
    }

    /// Gets the filename for the icon. If the [`IconLookupFlags::USE_BUILTIN`][crate::IconLookupFlags::USE_BUILTIN]
    /// flag was passed to [`IconThemeExt::lookup_icon()`][crate::prelude::IconThemeExt::lookup_icon()], there may be no
    /// filename if a builtin icon is returned; in this case, you should
    /// use `gtk_icon_info_get_builtin_pixbuf()`.
    ///
    /// # Returns
    ///
    /// the filename for the icon, or [`None`]
    ///  if `gtk_icon_info_get_builtin_pixbuf()` should be used instead.
    ///  The return value is owned by GTK+ and should not be modified
    ///  or freed.
    #[doc(alias = "gtk_icon_info_get_filename")]
    #[doc(alias = "get_filename")]
    pub fn filename(&self) -> Option<std::path::PathBuf> {
        unsafe { from_glib_none(ffi::gtk_icon_info_get_filename(self.to_glib_none().0)) }
    }

    /// Checks if the icon is symbolic or not. This currently uses only
    /// the file name and not the file contents for determining this.
    /// This behaviour may change in the future.
    ///
    /// # Returns
    ///
    /// [`true`] if the icon is symbolic, [`false`] otherwise
    #[doc(alias = "gtk_icon_info_is_symbolic")]
    pub fn is_symbolic(&self) -> bool {
        unsafe { from_glib(ffi::gtk_icon_info_is_symbolic(self.to_glib_none().0)) }
    }

    /// Renders an icon previously looked up in an icon theme using
    /// [`IconThemeExt::lookup_icon()`][crate::prelude::IconThemeExt::lookup_icon()]; the size will be based on the size
    /// passed to [`IconThemeExt::lookup_icon()`][crate::prelude::IconThemeExt::lookup_icon()]. Note that the resulting
    /// pixbuf may not be exactly this size; an icon theme may have icons
    /// that differ slightly from their nominal sizes, and in addition GTK+
    /// will avoid scaling icons that it considers sufficiently close to the
    /// requested size or for which the source image would have to be scaled
    /// up too far. (This maintains sharpness.). This behaviour can be changed
    /// by passing the [`IconLookupFlags::FORCE_SIZE`][crate::IconLookupFlags::FORCE_SIZE] flag when obtaining
    /// the [`IconInfo`][crate::IconInfo]. If this flag has been specified, the pixbuf
    /// returned by this function will be scaled to the exact size.
    ///
    /// # Returns
    ///
    /// the rendered icon; this may be a newly
    ///  created icon or a new reference to an internal icon, so you must
    ///  not modify the icon. Use `g_object_unref()` to release your reference
    ///  to the icon.
    #[doc(alias = "gtk_icon_info_load_icon")]
    pub fn load_icon(&self) -> Result<gdk_pixbuf::Pixbuf, glib::Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let ret = ffi::gtk_icon_info_load_icon(self.to_glib_none().0, &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Asynchronously load, render and scale an icon previously looked up
    /// from the icon theme using [`IconThemeExt::lookup_icon()`][crate::prelude::IconThemeExt::lookup_icon()].
    ///
    /// For more details, see [`load_icon()`][Self::load_icon()] which is the synchronous
    /// version of this call.
    /// ## `cancellable`
    /// optional [`gio::Cancellable`][crate::gio::Cancellable] object, [`None`] to ignore
    /// ## `callback`
    /// a `GAsyncReadyCallback` to call when the
    ///  request is satisfied
    #[doc(alias = "gtk_icon_info_load_icon_async")]
    pub fn load_icon_async<P: FnOnce(Result<gdk_pixbuf::Pixbuf, glib::Error>) + 'static>(
        &self,
        cancellable: Option<&impl IsA<gio::Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn load_icon_async_trampoline<
            P: FnOnce(Result<gdk_pixbuf::Pixbuf, glib::Error>) + 'static,
        >(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut gio::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            let mut error = ptr::null_mut();
            let ret =
                ffi::gtk_icon_info_load_icon_finish(_source_object as *mut _, res, &mut error);
            let result = if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            };
            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                Box_::from_raw(user_data as *mut _);
            let callback: P = callback.into_inner();
            callback(result);
        }
        let callback = load_icon_async_trampoline::<P>;
        unsafe {
            ffi::gtk_icon_info_load_icon_async(
                self.to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    pub fn load_icon_future(
        &self,
    ) -> Pin<
        Box_<dyn std::future::Future<Output = Result<gdk_pixbuf::Pixbuf, glib::Error>> + 'static>,
    > {
        Box_::pin(gio::GioFuture::new(self, move |obj, cancellable, send| {
            obj.load_icon_async(Some(cancellable), move |res| {
                send.resolve(res);
            });
        }))
    }

    /// Renders an icon previously looked up in an icon theme using
    /// [`IconThemeExt::lookup_icon()`][crate::prelude::IconThemeExt::lookup_icon()]; the size will be based on the size
    /// passed to [`IconThemeExt::lookup_icon()`][crate::prelude::IconThemeExt::lookup_icon()]. Note that the resulting
    /// surface may not be exactly this size; an icon theme may have icons
    /// that differ slightly from their nominal sizes, and in addition GTK+
    /// will avoid scaling icons that it considers sufficiently close to the
    /// requested size or for which the source image would have to be scaled
    /// up too far. (This maintains sharpness.). This behaviour can be changed
    /// by passing the [`IconLookupFlags::FORCE_SIZE`][crate::IconLookupFlags::FORCE_SIZE] flag when obtaining
    /// the [`IconInfo`][crate::IconInfo]. If this flag has been specified, the pixbuf
    /// returned by this function will be scaled to the exact size.
    /// ## `for_window`
    /// [`gdk::Window`][crate::gdk::Window] to optimize drawing for, or [`None`]
    ///
    /// # Returns
    ///
    /// the rendered icon; this may be a newly
    ///  created icon or a new reference to an internal icon, so you must
    ///  not modify the icon. Use `cairo_surface_destroy()` to release your
    ///  reference to the icon.
    #[doc(alias = "gtk_icon_info_load_surface")]
    pub fn load_surface(
        &self,
        for_window: Option<&gdk::Window>,
    ) -> Result<cairo::Surface, glib::Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let ret = ffi::gtk_icon_info_load_surface(
                self.to_glib_none().0,
                for_window.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Loads an icon, modifying it to match the system colours for the foreground,
    /// success, warning and error colors provided. If the icon is not a symbolic
    /// one, the function will return the result from [`load_icon()`][Self::load_icon()].
    ///
    /// This allows loading symbolic icons that will match the system theme.
    ///
    /// Unless you are implementing a widget, you will want to use
    /// `g_themed_icon_new_with_default_fallbacks()` to load the icon.
    ///
    /// As implementation details, the icon loaded needs to be of SVG type,
    /// contain the “symbolic” term as the last component of the icon name,
    /// and use the “fg”, “success”, “warning” and “error” CSS styles in the
    /// SVG file itself.
    ///
    /// See the [Symbolic Icons Specification](http://www.freedesktop.org/wiki/SymbolicIcons)
    /// for more information about symbolic icons.
    /// ## `fg`
    /// a [`gdk::RGBA`][crate::gdk::RGBA] representing the foreground color of the icon
    /// ## `success_color`
    /// a [`gdk::RGBA`][crate::gdk::RGBA] representing the warning color
    ///  of the icon or [`None`] to use the default color
    /// ## `warning_color`
    /// a [`gdk::RGBA`][crate::gdk::RGBA] representing the warning color
    ///  of the icon or [`None`] to use the default color
    /// ## `error_color`
    /// a [`gdk::RGBA`][crate::gdk::RGBA] representing the error color
    ///  of the icon or [`None`] to use the default color (allow-none)
    ///
    /// # Returns
    ///
    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf] representing the loaded icon
    ///
    /// ## `was_symbolic`
    /// a `gboolean`, returns whether the
    ///  loaded icon was a symbolic one and whether the `fg` color was
    ///  applied to it.
    #[doc(alias = "gtk_icon_info_load_symbolic")]
    pub fn load_symbolic(
        &self,
        fg: &gdk::RGBA,
        success_color: Option<&gdk::RGBA>,
        warning_color: Option<&gdk::RGBA>,
        error_color: Option<&gdk::RGBA>,
    ) -> Result<(gdk_pixbuf::Pixbuf, bool), glib::Error> {
        unsafe {
            let mut was_symbolic = mem::MaybeUninit::uninit();
            let mut error = ptr::null_mut();
            let ret = ffi::gtk_icon_info_load_symbolic(
                self.to_glib_none().0,
                fg.to_glib_none().0,
                success_color.to_glib_none().0,
                warning_color.to_glib_none().0,
                error_color.to_glib_none().0,
                was_symbolic.as_mut_ptr(),
                &mut error,
            );
            if error.is_null() {
                Ok((from_glib_full(ret), from_glib(was_symbolic.assume_init())))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Asynchronously load, render and scale a symbolic icon previously looked up
    /// from the icon theme using [`IconThemeExt::lookup_icon()`][crate::prelude::IconThemeExt::lookup_icon()].
    ///
    /// For more details, see [`load_symbolic()`][Self::load_symbolic()] which is the synchronous
    /// version of this call.
    /// ## `fg`
    /// a [`gdk::RGBA`][crate::gdk::RGBA] representing the foreground color of the icon
    /// ## `success_color`
    /// a [`gdk::RGBA`][crate::gdk::RGBA] representing the warning color
    ///  of the icon or [`None`] to use the default color
    /// ## `warning_color`
    /// a [`gdk::RGBA`][crate::gdk::RGBA] representing the warning color
    ///  of the icon or [`None`] to use the default color
    /// ## `error_color`
    /// a [`gdk::RGBA`][crate::gdk::RGBA] representing the error color
    ///  of the icon or [`None`] to use the default color (allow-none)
    /// ## `cancellable`
    /// optional [`gio::Cancellable`][crate::gio::Cancellable] object,
    ///  [`None`] to ignore
    /// ## `callback`
    /// a `GAsyncReadyCallback` to call when the
    ///  request is satisfied
    #[doc(alias = "gtk_icon_info_load_symbolic_async")]
    pub fn load_symbolic_async<
        P: FnOnce(Result<(gdk_pixbuf::Pixbuf, bool), glib::Error>) + 'static,
    >(
        &self,
        fg: &gdk::RGBA,
        success_color: Option<&gdk::RGBA>,
        warning_color: Option<&gdk::RGBA>,
        error_color: Option<&gdk::RGBA>,
        cancellable: Option<&impl IsA<gio::Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn load_symbolic_async_trampoline<
            P: FnOnce(Result<(gdk_pixbuf::Pixbuf, bool), glib::Error>) + 'static,
        >(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut gio::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            let mut error = ptr::null_mut();
            let mut was_symbolic = mem::MaybeUninit::uninit();
            let ret = ffi::gtk_icon_info_load_symbolic_finish(
                _source_object as *mut _,
                res,
                was_symbolic.as_mut_ptr(),
                &mut error,
            );
            let result = if error.is_null() {
                Ok((from_glib_full(ret), from_glib(was_symbolic.assume_init())))
            } else {
                Err(from_glib_full(error))
            };
            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                Box_::from_raw(user_data as *mut _);
            let callback: P = callback.into_inner();
            callback(result);
        }
        let callback = load_symbolic_async_trampoline::<P>;
        unsafe {
            ffi::gtk_icon_info_load_symbolic_async(
                self.to_glib_none().0,
                fg.to_glib_none().0,
                success_color.to_glib_none().0,
                warning_color.to_glib_none().0,
                error_color.to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    pub fn load_symbolic_future(
        &self,
        fg: &gdk::RGBA,
        success_color: Option<&gdk::RGBA>,
        warning_color: Option<&gdk::RGBA>,
        error_color: Option<&gdk::RGBA>,
    ) -> Pin<
        Box_<
            dyn std::future::Future<Output = Result<(gdk_pixbuf::Pixbuf, bool), glib::Error>>
                + 'static,
        >,
    > {
        let fg = fg.clone();
        let success_color = success_color.map(ToOwned::to_owned);
        let warning_color = warning_color.map(ToOwned::to_owned);
        let error_color = error_color.map(ToOwned::to_owned);
        Box_::pin(gio::GioFuture::new(self, move |obj, cancellable, send| {
            obj.load_symbolic_async(
                &fg,
                success_color.as_ref().map(::std::borrow::Borrow::borrow),
                warning_color.as_ref().map(::std::borrow::Borrow::borrow),
                error_color.as_ref().map(::std::borrow::Borrow::borrow),
                Some(cancellable),
                move |res| {
                    send.resolve(res);
                },
            );
        }))
    }

    /// Loads an icon, modifying it to match the system colors for the foreground,
    /// success, warning and error colors provided. If the icon is not a symbolic
    /// one, the function will return the result from [`load_icon()`][Self::load_icon()].
    /// This function uses the regular foreground color and the symbolic colors
    /// with the names “success_color”, “warning_color” and “error_color” from
    /// the context.
    ///
    /// This allows loading symbolic icons that will match the system theme.
    ///
    /// See [`load_symbolic()`][Self::load_symbolic()] for more details.
    /// ## `context`
    /// a [`StyleContext`][crate::StyleContext]
    ///
    /// # Returns
    ///
    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf] representing the loaded icon
    ///
    /// ## `was_symbolic`
    /// a `gboolean`, returns whether the
    ///  loaded icon was a symbolic one and whether the `fg` color was
    ///  applied to it.
    #[doc(alias = "gtk_icon_info_load_symbolic_for_context")]
    pub fn load_symbolic_for_context(
        &self,
        context: &impl IsA<StyleContext>,
    ) -> Result<(gdk_pixbuf::Pixbuf, bool), glib::Error> {
        unsafe {
            let mut was_symbolic = mem::MaybeUninit::uninit();
            let mut error = ptr::null_mut();
            let ret = ffi::gtk_icon_info_load_symbolic_for_context(
                self.to_glib_none().0,
                context.as_ref().to_glib_none().0,
                was_symbolic.as_mut_ptr(),
                &mut error,
            );
            if error.is_null() {
                Ok((from_glib_full(ret), from_glib(was_symbolic.assume_init())))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Asynchronously load, render and scale a symbolic icon previously
    /// looked up from the icon theme using [`IconThemeExt::lookup_icon()`][crate::prelude::IconThemeExt::lookup_icon()].
    ///
    /// For more details, see [`load_symbolic_for_context()`][Self::load_symbolic_for_context()]
    /// which is the synchronous version of this call.
    /// ## `context`
    /// a [`StyleContext`][crate::StyleContext]
    /// ## `cancellable`
    /// optional [`gio::Cancellable`][crate::gio::Cancellable] object,
    ///  [`None`] to ignore
    /// ## `callback`
    /// a `GAsyncReadyCallback` to call when the
    ///  request is satisfied
    #[doc(alias = "gtk_icon_info_load_symbolic_for_context_async")]
    pub fn load_symbolic_for_context_async<
        P: FnOnce(Result<(gdk_pixbuf::Pixbuf, bool), glib::Error>) + 'static,
    >(
        &self,
        context: &impl IsA<StyleContext>,
        cancellable: Option<&impl IsA<gio::Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn load_symbolic_for_context_async_trampoline<
            P: FnOnce(Result<(gdk_pixbuf::Pixbuf, bool), glib::Error>) + 'static,
        >(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut gio::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            let mut error = ptr::null_mut();
            let mut was_symbolic = mem::MaybeUninit::uninit();
            let ret = ffi::gtk_icon_info_load_symbolic_for_context_finish(
                _source_object as *mut _,
                res,
                was_symbolic.as_mut_ptr(),
                &mut error,
            );
            let result = if error.is_null() {
                Ok((from_glib_full(ret), from_glib(was_symbolic.assume_init())))
            } else {
                Err(from_glib_full(error))
            };
            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                Box_::from_raw(user_data as *mut _);
            let callback: P = callback.into_inner();
            callback(result);
        }
        let callback = load_symbolic_for_context_async_trampoline::<P>;
        unsafe {
            ffi::gtk_icon_info_load_symbolic_for_context_async(
                self.to_glib_none().0,
                context.as_ref().to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    pub fn load_symbolic_for_context_future(
        &self,
        context: &(impl IsA<StyleContext> + Clone + 'static),
    ) -> Pin<
        Box_<
            dyn std::future::Future<Output = Result<(gdk_pixbuf::Pixbuf, bool), glib::Error>>
                + 'static,
        >,
    > {
        let context = context.clone();
        Box_::pin(gio::GioFuture::new(self, move |obj, cancellable, send| {
            obj.load_symbolic_for_context_async(&context, Some(cancellable), move |res| {
                send.resolve(res);
            });
        }))
    }
}

impl fmt::Display for IconInfo {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("IconInfo")
    }
}