gtk4/

functions.rs

// Take a look at the license at the top of the repository in the LICENSE file.

use std::{boxed::Box as Box_, pin::Pin, sync::OnceLock};

use glib::{translate::*, Quark, Slice};

pub use crate::auto::functions::*;
use crate::{ffi, prelude::*, AboutDialog, StyleProvider, Window};

/// Determines whether a given keyval and modifier mask constitute
/// a valid keyboard accelerator.
///
/// For example, the `GDK_KEY_a` keyval plus [`gdk::ModifierType::CONTROL_MASK`][crate::gdk::ModifierType::CONTROL_MASK] mark is valid,
/// and matches the “Ctrl+a” accelerator. But, you can't, for instance, use
/// the `GDK_KEY_Control_L` keyval as an accelerator.
/// ## `keyval`
/// a GDK keyval
/// ## `modifiers`
/// modifier mask
///
/// # Returns
///
/// [`true`] if the accelerator is valid
#[doc(alias = "gtk_accelerator_valid")]
pub fn accelerator_valid(keyval: gdk::Key, modifiers: gdk::ModifierType) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::gtk_accelerator_valid(
            keyval.into_glib(),
            modifiers.into_glib(),
        ))
    }
}

/// Converts an accelerator keyval and modifier mask into a string
/// which can be used to represent the accelerator to the user.
/// ## `accelerator_key`
/// accelerator keyval
/// ## `accelerator_mods`
/// accelerator modifier mask
///
/// # Returns
///
/// a newly-allocated string representing the accelerator
#[doc(alias = "gtk_accelerator_get_label")]
pub fn accelerator_get_label(
    accelerator_key: gdk::Key,
    accelerator_mods: gdk::ModifierType,
) -> glib::GString {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_full(ffi::gtk_accelerator_get_label(
            accelerator_key.into_glib(),
            accelerator_mods.into_glib(),
        ))
    }
}

/// Converts an accelerator keyval and modifier mask
/// into a string that can be displayed to the user.
///
/// The string may be translated.
///
/// This function is similar to [`accelerator_get_label()`][crate::accelerator_get_label()],
/// but handling keycodes. This is only useful for system-level
/// components, applications should use [`accelerator_get_label()`][crate::accelerator_get_label()]
/// instead.
/// ## `display`
/// a [`gdk::Display`][crate::gdk::Display] or [`None`] to use the default display
/// ## `accelerator_key`
/// accelerator keyval
/// ## `keycode`
/// accelerator keycode
/// ## `accelerator_mods`
/// accelerator modifier mask
///
/// # Returns
///
/// a newly-allocated string representing the accelerator
#[doc(alias = "gtk_accelerator_get_label_with_keycode")]
pub fn accelerator_get_label_with_keycode(
    display: Option<&impl IsA<gdk::Display>>,
    accelerator_key: gdk::Key,
    keycode: u32,
    accelerator_mods: gdk::ModifierType,
) -> glib::GString {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_full(ffi::gtk_accelerator_get_label_with_keycode(
            display.map(|p| p.as_ref()).to_glib_none().0,
            accelerator_key.into_glib(),
            keycode,
            accelerator_mods.into_glib(),
        ))
    }
}

/// Converts an accelerator keyval and modifier mask into a string
/// parseable by gtk_accelerator_parse().
///
/// For example, if you pass in `GDK_KEY_q` and [`gdk::ModifierType::CONTROL_MASK`][crate::gdk::ModifierType::CONTROL_MASK],
/// this function returns `<Control>q`.
///
/// If you need to display accelerators in the user interface,
/// see [`accelerator_get_label()`][crate::accelerator_get_label()].
/// ## `accelerator_key`
/// accelerator keyval
/// ## `accelerator_mods`
/// accelerator modifier mask
///
/// # Returns
///
/// a newly-allocated accelerator name
#[doc(alias = "gtk_accelerator_name")]
pub fn accelerator_name(
    accelerator_key: gdk::Key,
    accelerator_mods: gdk::ModifierType,
) -> glib::GString {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_full(ffi::gtk_accelerator_name(
            accelerator_key.into_glib(),
            accelerator_mods.into_glib(),
        ))
    }
}

/// Converts an accelerator keyval and modifier mask
/// into a string parseable by gtk_accelerator_parse_with_keycode().
///
/// This is similar to [`accelerator_name()`][crate::accelerator_name()] but handling keycodes.
/// This is only useful for system-level components, applications
/// should use [`accelerator_name()`][crate::accelerator_name()] instead.
/// ## `display`
/// a [`gdk::Display`][crate::gdk::Display] or [`None`] to use the default display
/// ## `accelerator_key`
/// accelerator keyval
/// ## `keycode`
/// accelerator keycode
/// ## `accelerator_mods`
/// accelerator modifier mask
///
/// # Returns
///
/// a newly allocated accelerator name.
#[doc(alias = "gtk_accelerator_name_with_keycode")]
pub fn accelerator_name_with_keycode(
    display: Option<&impl IsA<gdk::Display>>,
    accelerator_key: gdk::Key,
    keycode: u32,
    accelerator_mods: gdk::ModifierType,
) -> glib::GString {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_full(ffi::gtk_accelerator_name_with_keycode(
            display.map(|p| p.as_ref()).to_glib_none().0,
            accelerator_key.into_glib(),
            keycode,
            accelerator_mods.into_glib(),
        ))
    }
}

/// Parses a string representing an accelerator.
///
/// The format looks like “`<Control>a`” or “`<Shift><Alt>F1`”.
///
/// The parser is fairly liberal and allows lower or upper case, and also
/// abbreviations such as “`<Ctl>`” and “`<Ctrl>`”.
///
/// Key names are parsed using `keyval_from_name()`. For character keys
/// the name is not the symbol, but the lowercase name, e.g. one would use
/// “`<Ctrl>minus`” instead of “`<Ctrl>-`”.
///
/// Modifiers are enclosed in angular brackets `<>`, and match the
/// [`gdk::ModifierType`][crate::gdk::ModifierType] mask:
///
/// - `<Shift>` for `GDK_SHIFT_MASK`
/// - `<Ctrl>` for `GDK_CONTROL_MASK`
/// - `<Alt>` for `GDK_ALT_MASK`
/// - `<Meta>` for `GDK_META_MASK`
/// - `<Super>` for `GDK_SUPER_MASK`
/// - `<Hyper>` for `GDK_HYPER_MASK`
///
/// If the parse operation fails, @accelerator_key and @accelerator_mods will
/// be set to 0 (zero).
/// ## `accelerator`
/// string representing an accelerator
///
/// # Returns
///
/// whether parsing succeeded
///
/// ## `accelerator_key`
/// return location for accelerator keyval
///
/// ## `accelerator_mods`
/// return location for accelerator
///   modifier mask
#[doc(alias = "gtk_accelerator_parse")]
pub fn accelerator_parse(accelerator: impl IntoGStr) -> Option<(gdk::Key, gdk::ModifierType)> {
    assert_initialized_main_thread!();
    unsafe {
        accelerator.run_with_gstr(|accelerator| {
            let mut accelerator_key = std::mem::MaybeUninit::uninit();
            let mut accelerator_mods = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gtk_accelerator_parse(
                accelerator.as_ptr(),
                accelerator_key.as_mut_ptr(),
                accelerator_mods.as_mut_ptr(),
            ));
            if ret {
                Some((
                    gdk::Key::from_glib(accelerator_key.assume_init()),
                    from_glib(accelerator_mods.assume_init()),
                ))
            } else {
                None
            }
        })
    }
}

/// Parses a string representing an accelerator.
///
/// This is similar to [`accelerator_parse()`][crate::accelerator_parse()] but handles keycodes as
/// well. This is only useful for system-level components, applications should
/// use [`accelerator_parse()`][crate::accelerator_parse()] instead.
///
/// If @accelerator_codes is given and the result stored in it is non-[`None`],
/// the result must be freed with g_free().
///
/// If a keycode is present in the accelerator and no @accelerator_codes
/// is given, the parse will fail.
///
/// If the parse fails, @accelerator_key, @accelerator_mods and
/// @accelerator_codes will be set to 0 (zero).
/// ## `accelerator`
/// string representing an accelerator
/// ## `display`
/// the [`gdk::Display`][crate::gdk::Display] to look up @accelerator_codes in
///
/// # Returns
///
/// [`true`] if parsing succeeded
///
/// ## `accelerator_key`
/// return location for accelerator keyval
///
/// ## `accelerator_codes`
///
///   return location for accelerator keycodes
///
/// ## `accelerator_mods`
/// return location for accelerator
///   modifier mask
#[doc(alias = "gtk_accelerator_parse_with_keycode")]
pub fn accelerator_parse_with_keycode(
    accelerator: impl IntoGStr,
    display: Option<&impl IsA<gdk::Display>>,
) -> Option<(gdk::Key, Slice<u32>, gdk::ModifierType)> {
    assert_initialized_main_thread!();
    unsafe {
        accelerator.run_with_gstr(|accelerator| {
            let mut accelerator_key = std::mem::MaybeUninit::uninit();
            let mut accelerator_codes_ptr = std::ptr::null_mut();
            let mut accelerator_mods = std::mem::MaybeUninit::uninit();
            let success = from_glib(ffi::gtk_accelerator_parse_with_keycode(
                accelerator.as_ptr(),
                display.map(|p| p.as_ref()).to_glib_none().0,
                accelerator_key.as_mut_ptr(),
                &mut accelerator_codes_ptr,
                accelerator_mods.as_mut_ptr(),
            ));
            if success {
                let mut len = 0;
                if !accelerator_codes_ptr.is_null() {
                    while std::ptr::read(accelerator_codes_ptr.add(len)) != 0 {
                        len += 1;
                    }
                }
                let accelerator_codes = Slice::from_glib_full_num(accelerator_codes_ptr, len);
                Some((
                    gdk::Key::from_glib(accelerator_key.assume_init()),
                    accelerator_codes,
                    from_glib(accelerator_mods.assume_init()),
                ))
            } else {
                None
            }
        })
    }
}

/// This function launches the default application for showing
/// a given uri.
///
/// The @callback will be called when the launch is completed.
///
/// This is the recommended call to be used as it passes information
/// necessary for sandbox helpers to parent their dialogs properly.
///
/// # Deprecated since 4.10
///
/// Use [`FileLauncher::launch()`][crate::FileLauncher::launch()] or
///   [`UriLauncher::launch()`][crate::UriLauncher::launch()] instead
/// ## `parent`
/// parent window
/// ## `uri`
/// the uri to show
/// ## `timestamp`
/// timestamp from the event that triggered this call, or `GDK_CURRENT_TIME`
/// ## `cancellable`
/// a `GCancellable` to cancel the launch
/// ## `callback`
/// a callback to call when the action is complete
#[doc(alias = "gtk_show_uri_full")]
#[doc(alias = "gtk_show_uri_full_finish")]
#[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
#[allow(deprecated)]
pub fn show_uri_full<P: FnOnce(Result<(), glib::Error>) + 'static>(
    parent: Option<&impl IsA<Window>>,
    uri: &str,
    timestamp: u32,
    cancellable: Option<&impl IsA<gio::Cancellable>>,
    callback: P,
) {
    assert_initialized_main_thread!();
    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 show_uri_full_trampoline<P: FnOnce(Result<(), glib::Error>) + 'static>(
        parent_ptr: *mut glib::gobject_ffi::GObject,
        res: *mut gio::ffi::GAsyncResult,
        user_data: glib::ffi::gpointer,
    ) {
        let mut error = std::ptr::null_mut();
        let _ = ffi::gtk_show_uri_full_finish(parent_ptr as *mut ffi::GtkWindow, res, &mut error);
        let result = if error.is_null() {
            Ok(())
        } else {
            Err(from_glib_full(error))
        };
        let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::from_raw(user_data as *mut _);
        let callback = callback.into_inner();
        callback(result);
    }
    let callback = show_uri_full_trampoline::<P>;
    unsafe {
        ffi::gtk_show_uri_full(
            parent.map(|p| p.as_ref()).to_glib_none().0,
            uri.to_glib_none().0,
            timestamp,
            cancellable.map(|p| p.as_ref()).to_glib_none().0,
            Some(callback),
            Box_::into_raw(user_data) as *mut _,
        );
    }
}

#[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
#[allow(deprecated)]
pub fn show_uri_full_future(
    parent: Option<&(impl IsA<Window> + Clone + 'static)>,
    uri: &str,
    timestamp: u32,
) -> Pin<Box_<dyn std::future::Future<Output = Result<(), glib::Error>> + 'static>> {
    skip_assert_initialized!();
    let parent = parent.map(ToOwned::to_owned);
    let uri = String::from(uri);
    Box_::pin(gio::GioFuture::new(&(), move |_obj, cancellable, send| {
        show_uri_full(
            parent.as_ref().map(::std::borrow::Borrow::borrow),
            &uri,
            timestamp,
            Some(cancellable),
            move |res| {
                send.resolve(res);
            },
        );
    }))
}

/// A convenience function for showing an application’s about dialog.
///
/// The constructed dialog is associated with the parent window and
/// reused for future invocations of this function.
/// ## `parent`
/// the parent top-level window
/// ## `first_property_name`
/// the name of the first property
#[doc(alias = "gtk_show_about_dialog")]
pub fn show_about_dialog<P: IsA<Window>>(parent: Option<&P>, properties: &[(&str, &dyn ToValue)]) {
    assert_initialized_main_thread!();
    static QUARK: OnceLock<Quark> = OnceLock::new();
    let quark = *QUARK.get_or_init(|| Quark::from_str("gtk-rs-about-dialog"));

    unsafe {
        if let Some(d) = parent.and_then(|p| p.qdata::<AboutDialog>(quark)) {
            d.as_ref().show();
        } else {
            let mut builder = glib::Object::builder::<AboutDialog>();
            for (key, value) in properties {
                builder = builder.property(key, *value);
            }
            let about_dialog = builder.build();
            about_dialog.set_hide_on_close(true);

            // cache the dialog if a parent is set
            if let Some(dialog_parent) = parent {
                about_dialog.set_modal(true);
                about_dialog.set_transient_for(parent);
                about_dialog.set_destroy_with_parent(true);
                dialog_parent.set_qdata(quark, about_dialog.clone());
            }

            about_dialog.show();
        };
    }
}

/// Return the type ids that have been registered after
/// calling gtk_test_register_all_types().
///
/// # Returns
///
///
///    0-terminated array of type ids
#[doc(alias = "gtk_test_list_all_types")]
pub fn test_list_all_types() -> Slice<glib::Type> {
    unsafe {
        let mut n_types = std::mem::MaybeUninit::uninit();
        let types = ffi::gtk_test_list_all_types(n_types.as_mut_ptr());
        Slice::from_glib_container_num(types as *mut _, n_types.assume_init() as usize)
    }
}

#[doc(alias = "gtk_style_context_add_provider_for_display")]
#[doc(alias = "add_provider_for_display")]
pub fn style_context_add_provider_for_display(
    display: &impl IsA<gdk::Display>,
    provider: &impl IsA<StyleProvider>,
    priority: u32,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_style_context_add_provider_for_display(
            display.as_ref().to_glib_none().0,
            provider.as_ref().to_glib_none().0,
            priority,
        );
    }
}

#[doc(alias = "gtk_style_context_remove_provider_for_display")]
#[doc(alias = "remove_provider_for_display")]
pub fn style_context_remove_provider_for_display(
    display: &impl IsA<gdk::Display>,
    provider: &impl IsA<StyleProvider>,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_style_context_remove_provider_for_display(
            display.as_ref().to_glib_none().0,
            provider.as_ref().to_glib_none().0,
        );
    }
}