gtk/auto/

functions.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::{
    AccelGroup, Orientation, PageSetup, PositionType, PrintSettings, SelectionData, StyleContext,
    TextBuffer, TextDirection, TreeModel, TreePath, Widget, Window, ffi,
};
use glib::{prelude::*, translate::*};
use std::boxed::Box as Box_;

/// Finds the first accelerator in any [`AccelGroup`][crate::AccelGroup] attached
/// to `object` that matches `accel_key` and `accel_mods`, and
/// activates that accelerator.
/// ## `object`
/// the [`glib::Object`][crate::glib::Object], usually a [`Window`][crate::Window], on which
///  to activate the accelerator
/// ## `accel_key`
/// accelerator keyval from a key event
/// ## `accel_mods`
/// keyboard state mask from a key event
///
/// # Returns
///
/// [`true`] if an accelerator was activated and handled
///  this keypress
#[doc(alias = "gtk_accel_groups_activate")]
pub fn accel_groups_activate(
    object: &impl IsA<glib::Object>,
    accel_key: u32,
    accel_mods: gdk::ModifierType,
) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::gtk_accel_groups_activate(
            object.as_ref().to_glib_none().0,
            accel_key,
            accel_mods.into_glib(),
        ))
    }
}

/// Gets a list of all accel groups which are attached to `object`.
/// ## `object`
/// a [`glib::Object`][crate::glib::Object], usually a [`Window`][crate::Window]
///
/// # Returns
///
/// a list of
///  all accel groups which are attached to `object`
#[doc(alias = "gtk_accel_groups_from_object")]
pub fn accel_groups_from_object(object: &impl IsA<glib::Object>) -> Vec<AccelGroup> {
    assert_initialized_main_thread!();
    unsafe {
        FromGlibPtrContainer::from_glib_none(ffi::gtk_accel_groups_from_object(
            object.as_ref().to_glib_none().0,
        ))
    }
}

/// Gets the modifier mask.
///
/// The modifier mask determines which modifiers are considered significant
/// for keyboard accelerators. See [`accelerator_set_default_mod_mask()`][crate::accelerator_set_default_mod_mask()].
///
/// # Returns
///
/// the default accelerator modifier mask
#[doc(alias = "gtk_accelerator_get_default_mod_mask")]
pub fn accelerator_get_default_mod_mask() -> gdk::ModifierType {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::gtk_accelerator_get_default_mod_mask()) }
}

/// 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: u32,
    accelerator_mods: gdk::ModifierType,
) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_full(ffi::gtk_accelerator_get_label(
            accelerator_key,
            accelerator_mods.into_glib(),
        ))
    }
}

/// Converts an accelerator keyval and modifier mask
/// into a (possibly translated) string that can be displayed to
/// a user, similarly to [`accelerator_get_label()`][crate::accelerator_get_label()], but handling
/// keycodes.
///
/// This is only useful for system-level components, applications
/// should use [`accelerator_parse()`][crate::accelerator_parse()] 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<&gdk::Display>,
    accelerator_key: u32,
    keycode: u32,
    accelerator_mods: gdk::ModifierType,
) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_full(ffi::gtk_accelerator_get_label_with_keycode(
            display.to_glib_none().0,
            accelerator_key,
            keycode,
            accelerator_mods.into_glib(),
        ))
    }
}

/// 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: u32,
    accelerator_mods: gdk::ModifierType,
) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_full(ffi::gtk_accelerator_name(
            accelerator_key,
            accelerator_mods.into_glib(),
        ))
    }
}

/// Converts an accelerator keyval and modifier mask
/// into a string parseable by [`accelerator_parse_with_keycode()`][crate::accelerator_parse_with_keycode()],
/// similarly to [`accelerator_name()`][crate::accelerator_name()] but handling keycodes.
/// This is only useful for system-level components, applications
/// should use [`accelerator_parse()`][crate::accelerator_parse()] 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<&gdk::Display>,
    accelerator_key: u32,
    keycode: u32,
    accelerator_mods: gdk::ModifierType,
) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_full(ffi::gtk_accelerator_name_with_keycode(
            display.to_glib_none().0,
            accelerator_key,
            keycode,
            accelerator_mods.into_glib(),
        ))
    }
}

/// -`.
///
/// If the parse fails, `accelerator_key` and `accelerator_mods` will
/// be set to 0 (zero).
/// ## `accelerator`
/// string representing an accelerator
///
/// # Returns
///
///
/// ## `accelerator_key`
/// return location for accelerator
///  keyval, or [`None`]
///
/// ## `accelerator_mods`
/// return location for accelerator
///  modifier mask, [`None`]
#[doc(alias = "gtk_accelerator_parse")]
pub fn accelerator_parse(accelerator: &str) -> (u32, gdk::ModifierType) {
    assert_initialized_main_thread!();
    unsafe {
        let mut accelerator_key = std::mem::MaybeUninit::uninit();
        let mut accelerator_mods = std::mem::MaybeUninit::uninit();
        ffi::gtk_accelerator_parse(
            accelerator.to_glib_none().0,
            accelerator_key.as_mut_ptr(),
            accelerator_mods.as_mut_ptr(),
        );
        (
            accelerator_key.assume_init(),
            from_glib(accelerator_mods.assume_init()),
        )
    }
}

/// Sets the modifiers that will be considered significant for keyboard
/// accelerators. The default mod mask depends on the GDK backend in use,
/// but will typically include [`gdk::ModifierType::CONTROL_MASK`][crate::gdk::ModifierType::CONTROL_MASK] | [`gdk::ModifierType::SHIFT_MASK`][crate::gdk::ModifierType::SHIFT_MASK] |
/// [`gdk::ModifierType::MOD1_MASK`][crate::gdk::ModifierType::MOD1_MASK] | [`gdk::ModifierType::SUPER_MASK`][crate::gdk::ModifierType::SUPER_MASK] | [`gdk::ModifierType::HYPER_MASK`][crate::gdk::ModifierType::HYPER_MASK] | [`gdk::ModifierType::META_MASK`][crate::gdk::ModifierType::META_MASK].
/// In other words, Control, Shift, Alt, Super, Hyper and Meta. Other
/// modifiers will by default be ignored by [`AccelGroup`][crate::AccelGroup].
///
/// You must include at least the three modifiers Control, Shift
/// and Alt in any value you pass to this function.
///
/// The default mod mask should be changed on application startup,
/// before using any accelerator groups.
/// ## `default_mod_mask`
/// accelerator modifier mask
#[doc(alias = "gtk_accelerator_set_default_mod_mask")]
pub fn accelerator_set_default_mod_mask(default_mod_mask: gdk::ModifierType) {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gtk_accelerator_set_default_mod_mask(default_mod_mask.into_glib());
    }
}

/// 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] is valid - this is a “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: u32, modifiers: gdk::ModifierType) -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::gtk_accelerator_valid(keyval, modifiers.into_glib())) }
}

/// Find a key binding matching `keyval` and `modifiers` and activate the
/// binding on `object`.
/// ## `object`
/// object to activate when binding found
/// ## `keyval`
/// key value of the binding
/// ## `modifiers`
/// key modifier of the binding
///
/// # Returns
///
/// [`true`] if a binding was found and activated
#[doc(alias = "gtk_bindings_activate")]
pub fn bindings_activate(
    object: &impl IsA<glib::Object>,
    keyval: u32,
    modifiers: gdk::ModifierType,
) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::gtk_bindings_activate(
            object.as_ref().to_glib_none().0,
            keyval,
            modifiers.into_glib(),
        ))
    }
}

/// Looks up key bindings for `object` to find one matching
/// `event`, and if one was found, activate it.
/// ## `object`
/// a [`glib::Object`][crate::glib::Object] (generally must be a widget)
/// ## `event`
/// a [`gdk::EventKey`][crate::gdk::EventKey]
///
/// # Returns
///
/// [`true`] if a matching key binding was found
#[doc(alias = "gtk_bindings_activate_event")]
pub fn bindings_activate_event(object: &impl IsA<glib::Object>, event: &mut gdk::EventKey) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::gtk_bindings_activate_event(
            object.as_ref().to_glib_none().0,
            event.to_glib_none_mut().0,
        ))
    }
}

/// This function is supposed to be called in [`draw`][struct@crate::Widget#draw]
/// implementations for widgets that support multiple windows.
/// `cr` must be untransformed from invoking of the draw function.
/// This function will return [`true`] if the contents of the given
/// `window` are supposed to be drawn and [`false`] otherwise. Note
/// that when the drawing was not initiated by the windowing
/// system this function will return [`true`] for all windows, so
/// you need to draw the bottommost window first. Also, do not
/// use “else if” statements to check which window should be drawn.
/// ## `cr`
/// a cairo context
/// ## `window`
/// the window to check. `window` may not be an input-only
///  window.
///
/// # Returns
///
/// [`true`] if `window` should be drawn
#[doc(alias = "gtk_cairo_should_draw_window")]
pub fn cairo_should_draw_window(cr: &cairo::Context, window: &gdk::Window) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::gtk_cairo_should_draw_window(
            mut_override(cr.to_glib_none().0),
            window.to_glib_none().0,
        ))
    }
}

/// Transforms the given cairo context `cr` that from `widget`-relative
/// coordinates to `window`-relative coordinates.
/// If the `widget`’s window is not an ancestor of `window`, no
/// modification will be applied.
///
/// This is the inverse to the transformation GTK applies when
/// preparing an expose event to be emitted with the [`draw`][struct@crate::Widget#draw]
/// signal. It is intended to help porting multiwindow widgets from
/// GTK+ 2 to the rendering architecture of GTK+ 3.
/// ## `cr`
/// the cairo context to transform
/// ## `widget`
/// the widget the context is currently centered for
/// ## `window`
/// the window to transform the context to
#[doc(alias = "gtk_cairo_transform_to_window")]
pub fn cairo_transform_to_window(
    cr: &cairo::Context,
    widget: &impl IsA<Widget>,
    window: &gdk::Window,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_cairo_transform_to_window(
            mut_override(cr.to_glib_none().0),
            widget.as_ref().to_glib_none().0,
            window.to_glib_none().0,
        );
    }
}

/// Checks that the GTK+ library in use is compatible with the
/// given version. Generally you would pass in the constants
/// `GTK_MAJOR_VERSION`, `GTK_MINOR_VERSION`, `GTK_MICRO_VERSION`
/// as the three arguments to this function; that produces
/// a check that the library in use is compatible with
/// the version of GTK+ the application or module was compiled
/// against.
///
/// Compatibility is defined by two things: first the version
/// of the running library is newer than the version
/// `required_major`.`required_micro`. Second
/// the running library must be binary compatible with the
/// version `required_major`.`required_micro`
/// (same major version.)
///
/// This function is primarily for GTK+ modules; the module
/// can call this function to check that it wasn’t loaded
/// into an incompatible version of GTK+. However, such a
/// check isn’t completely reliable, since the module may be
/// linked against an old version of GTK+ and calling the
/// old version of [`check_version()`][crate::check_version()], but still get loaded
/// into an application using a newer version of GTK+.
/// ## `required_major`
/// the required major version
/// ## `required_minor`
/// the required minor version
/// ## `required_micro`
/// the required micro version
///
/// # Returns
///
/// [`None`] if the GTK+ library is compatible with the
///  given version, or a string describing the version mismatch.
///  The returned string is owned by GTK+ and should not be modified
///  or freed.
#[doc(alias = "gtk_check_version")]
pub fn check_version(
    required_major: u32,
    required_minor: u32,
    required_micro: u32,
) -> Option<glib::GString> {
    skip_assert_initialized!();
    unsafe {
        from_glib_none(ffi::gtk_check_version(
            required_major,
            required_minor,
            required_micro,
        ))
    }
}

/// Adds a GTK+ grab on `device`, so all the events on `device` and its
/// associated pointer or keyboard (if any) are delivered to `widget`.
/// If the `block_others` parameter is [`true`], any other devices will be
/// unable to interact with `widget` during the grab.
/// ## `widget`
/// a [`Widget`][crate::Widget]
/// ## `device`
/// a [`gdk::Device`][crate::gdk::Device] to grab on.
/// ## `block_others`
/// [`true`] to prevent other devices to interact with `widget`.
#[doc(alias = "gtk_device_grab_add")]
pub fn device_grab_add(widget: &impl IsA<Widget>, device: &gdk::Device, block_others: bool) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_device_grab_add(
            widget.as_ref().to_glib_none().0,
            device.to_glib_none().0,
            block_others.into_glib(),
        );
    }
}

/// Removes a device grab from the given widget.
///
/// You have to pair calls to [`device_grab_add()`][crate::device_grab_add()] and
/// [`device_grab_remove()`][crate::device_grab_remove()].
/// ## `widget`
/// a [`Widget`][crate::Widget]
/// ## `device`
/// a [`gdk::Device`][crate::gdk::Device]
#[doc(alias = "gtk_device_grab_remove")]
pub fn device_grab_remove(widget: &impl IsA<Widget>, device: &gdk::Device) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_device_grab_remove(widget.as_ref().to_glib_none().0, device.to_glib_none().0);
    }
}

/// Prevents `gtk_init()`, `gtk_init_check()`, `gtk_init_with_args()` and
/// `gtk_parse_args()` from automatically
/// calling `setlocale (LC_ALL, "")`. You would
/// want to use this function if you wanted to set the locale for
/// your program to something other than the user’s locale, or if
/// you wanted to set different values for different locale categories.
///
/// Most programs should not need to call this function.
#[doc(alias = "gtk_disable_setlocale")]
pub fn disable_setlocale() {
    assert_not_initialized!();
    unsafe {
        ffi::gtk_disable_setlocale();
    }
}

//#[doc(alias = "gtk_distribute_natural_allocation")]
//pub fn distribute_natural_allocation(extra_space: i32, n_requested_sizes: u32, sizes: /*Ignored*/&mut RequestedSize) -> i32 {
//    unsafe { TODO: call ffi:gtk_distribute_natural_allocation() }
//}

///
///  // computation going on...
///
///  while (gtk_events_pending ())
///  gtk_main_iteration ();
///
///  // ...computation continued
/// ]|
///
/// # Returns
///
/// [`true`] if any events are pending, [`false`] otherwise
#[doc(alias = "gtk_events_pending")]
pub fn events_pending() -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::gtk_events_pending()) }
}

/// Analogical to [`true_()`][crate::true_()], this function does nothing
/// but always returns [`false`].
///
/// # Returns
///
/// [`false`]
#[doc(alias = "gtk_false")]
#[doc(alias = "false")]
pub fn false_() -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::gtk_false()) }
}

/// Returns the binary age as passed to `libtool`
/// when building the GTK+ library the process is running against.
/// If `libtool` means nothing to you, don't
/// worry about it.
///
/// # Returns
///
/// the binary age of the GTK+ library
#[doc(alias = "gtk_get_binary_age")]
#[doc(alias = "get_binary_age")]
pub fn binary_age() -> u32 {
    skip_assert_initialized!();
    unsafe { ffi::gtk_get_binary_age() }
}

/// Obtains a copy of the event currently being processed by GTK+.
///
/// For example, if you are handling a [`clicked`][struct@crate::Button#clicked] signal,
/// the current event will be the [`gdk::EventButton`][crate::gdk::EventButton] that triggered
/// the ::clicked signal.
///
/// # Returns
///
/// a copy of the current event, or
///  [`None`] if there is no current event. The returned event must be
///  freed with `gdk_event_free()`.
#[doc(alias = "gtk_get_current_event")]
#[doc(alias = "get_current_event")]
pub fn current_event() -> Option<gdk::Event> {
    assert_initialized_main_thread!();
    unsafe { from_glib_full(ffi::gtk_get_current_event()) }
}

/// If there is a current event and it has a device, return that
/// device, otherwise return [`None`].
///
/// # Returns
///
/// a [`gdk::Device`][crate::gdk::Device], or [`None`]
#[doc(alias = "gtk_get_current_event_device")]
#[doc(alias = "get_current_event_device")]
pub fn current_event_device() -> Option<gdk::Device> {
    assert_initialized_main_thread!();
    unsafe { from_glib_none(ffi::gtk_get_current_event_device()) }
}

/// If there is a current event and it has a state field, place
/// that state field in `state` and return [`true`], otherwise return
/// [`false`].
///
/// # Returns
///
/// [`true`] if there was a current event and it
///  had a state field
///
/// ## `state`
/// a location to store the state of the current event
#[doc(alias = "gtk_get_current_event_state")]
#[doc(alias = "get_current_event_state")]
pub fn current_event_state() -> Option<gdk::ModifierType> {
    assert_initialized_main_thread!();
    unsafe {
        let mut state = std::mem::MaybeUninit::uninit();
        let ret = from_glib(ffi::gtk_get_current_event_state(state.as_mut_ptr()));
        if ret {
            Some(from_glib(state.assume_init()))
        } else {
            None
        }
    }
}

/// If there is a current event and it has a timestamp,
/// return that timestamp, otherwise return `GDK_CURRENT_TIME`.
///
/// # Returns
///
/// the timestamp from the current event,
///  or `GDK_CURRENT_TIME`.
#[doc(alias = "gtk_get_current_event_time")]
#[doc(alias = "get_current_event_time")]
pub fn current_event_time() -> u32 {
    assert_initialized_main_thread!();
    unsafe { ffi::gtk_get_current_event_time() }
}

/// Returns the GTK+ debug flags.
///
/// This function is intended for GTK+ modules that want
/// to adjust their debug output based on GTK+ debug flags.
///
/// # Returns
///
/// the GTK+ debug flags.
#[doc(alias = "gtk_get_debug_flags")]
#[doc(alias = "get_debug_flags")]
pub fn debug_flags() -> u32 {
    assert_initialized_main_thread!();
    unsafe { ffi::gtk_get_debug_flags() }
}

/// Returns the [`pango::Language`][crate::pango::Language] for the default language currently in
/// effect. (Note that this can change over the life of an
/// application.) The default language is derived from the current
/// locale. It determines, for example, whether GTK+ uses the
/// right-to-left or left-to-right text direction.
///
/// This function is equivalent to [`pango::Language::default()`][crate::pango::Language::default()].
/// See that function for details.
///
/// # Returns
///
/// the default language as a [`pango::Language`][crate::pango::Language],
///  must not be freed
#[doc(alias = "gtk_get_default_language")]
#[doc(alias = "get_default_language")]
pub fn default_language() -> Option<pango::Language> {
    assert_initialized_main_thread!();
    unsafe { from_glib_none(ffi::gtk_get_default_language()) }
}

/// If `event` is [`None`] or the event was not associated with any widget,
/// returns [`None`], otherwise returns the widget that received the event
/// originally.
/// ## `event`
/// a `GdkEvent`
///
/// # Returns
///
/// the widget that originally
///  received `event`, or [`None`]
#[doc(alias = "gtk_get_event_widget")]
#[doc(alias = "get_event_widget")]
pub fn event_widget(event: &mut gdk::Event) -> Option<Widget> {
    assert_initialized_main_thread!();
    unsafe { from_glib_none(ffi::gtk_get_event_widget(event.to_glib_none_mut().0)) }
}

/// Returns the interface age as passed to `libtool`
/// when building the GTK+ library the process is running against.
/// If `libtool` means nothing to you, don't
/// worry about it.
///
/// # Returns
///
/// the interface age of the GTK+ library
#[doc(alias = "gtk_get_interface_age")]
#[doc(alias = "get_interface_age")]
pub fn interface_age() -> u32 {
    skip_assert_initialized!();
    unsafe { ffi::gtk_get_interface_age() }
}

///
/// setlocale (LC_ALL, new_locale);
/// direction = gtk_get_locale_direction ();
/// gtk_widget_set_default_direction (direction);
/// ]|
///
/// # Returns
///
/// the [`TextDirection`][crate::TextDirection] of the current locale
#[doc(alias = "gtk_get_locale_direction")]
#[doc(alias = "get_locale_direction")]
pub fn locale_direction() -> TextDirection {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::gtk_get_locale_direction()) }
}

/// Returns the major version number of the GTK+ library.
/// (e.g. in GTK+ version 3.1.5 this is 3.)
///
/// This function is in the library, so it represents the GTK+ library
/// your code is running against. Contrast with the `GTK_MAJOR_VERSION`
/// macro, which represents the major version of the GTK+ headers you
/// have included when compiling your code.
///
/// # Returns
///
/// the major version number of the GTK+ library
#[doc(alias = "gtk_get_major_version")]
#[doc(alias = "get_major_version")]
pub fn major_version() -> u32 {
    skip_assert_initialized!();
    unsafe { ffi::gtk_get_major_version() }
}

/// Returns the micro version number of the GTK+ library.
/// (e.g. in GTK+ version 3.1.5 this is 5.)
///
/// This function is in the library, so it represents the GTK+ library
/// your code is are running against. Contrast with the
/// `GTK_MICRO_VERSION` macro, which represents the micro version of the
/// GTK+ headers you have included when compiling your code.
///
/// # Returns
///
/// the micro version number of the GTK+ library
#[doc(alias = "gtk_get_micro_version")]
#[doc(alias = "get_micro_version")]
pub fn micro_version() -> u32 {
    skip_assert_initialized!();
    unsafe { ffi::gtk_get_micro_version() }
}

/// Returns the minor version number of the GTK+ library.
/// (e.g. in GTK+ version 3.1.5 this is 1.)
///
/// This function is in the library, so it represents the GTK+ library
/// your code is are running against. Contrast with the
/// `GTK_MINOR_VERSION` macro, which represents the minor version of the
/// GTK+ headers you have included when compiling your code.
///
/// # Returns
///
/// the minor version number of the GTK+ library
#[doc(alias = "gtk_get_minor_version")]
#[doc(alias = "get_minor_version")]
pub fn minor_version() -> u32 {
    skip_assert_initialized!();
    unsafe { ffi::gtk_get_minor_version() }
}

//#[doc(alias = "gtk_get_option_group")]
//#[doc(alias = "get_option_group")]
//pub fn option_group(open_default_display: bool) -> /*Ignored*/Option<glib::OptionGroup> {
//    unsafe { TODO: call ffi:gtk_get_option_group() }
//}

/// Queries the current grab of the default window group.
///
/// # Returns
///
/// The widget which currently
///  has the grab or [`None`] if no grab is active
#[doc(alias = "gtk_grab_get_current")]
pub fn grab_get_current() -> Option<Widget> {
    assert_initialized_main_thread!();
    unsafe { from_glib_none(ffi::gtk_grab_get_current()) }
}

/// Runs the main loop until `gtk_main_quit()` is called.
///
/// You can nest calls to [`main()`][crate::main()]. In that case `gtk_main_quit()`
/// will make the innermost invocation of the main loop return.
#[doc(alias = "gtk_main")]
pub fn main() {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gtk_main();
    }
}

/// Processes a single GDK event.
///
/// This is public only to allow filtering of events between GDK and GTK+.
/// You will not usually need to call this function directly.
///
/// While you should not call this function directly, you might want to
/// know how exactly events are handled. So here is what this function
/// does with the event:
///
/// 1. Compress enter/leave notify events. If the event passed build an
///  enter/leave pair together with the next event (peeked from GDK), both
///  events are thrown away. This is to avoid a backlog of (de-)highlighting
///  widgets crossed by the pointer.
///
/// 2. Find the widget which got the event. If the widget can’t be determined
///  the event is thrown away unless it belongs to a INCR transaction.
///
/// 3. Then the event is pushed onto a stack so you can query the currently
///  handled event with [`current_event()`][crate::current_event()].
///
/// 4. The event is sent to a widget. If a grab is active all events for widgets
///  that are not in the contained in the grab widget are sent to the latter
///  with a few exceptions:
///  - Deletion and destruction events are still sent to the event widget for
///  obvious reasons.
///  - Events which directly relate to the visual representation of the event
///  widget.
///  - Leave events are delivered to the event widget if there was an enter
///  event delivered to it before without the paired leave event.
///  - Drag events are not redirected because it is unclear what the semantics
///  of that would be.
///  Another point of interest might be that all key events are first passed
///  through the key snooper functions if there are any. Read the description
///  of `gtk_key_snooper_install()` if you need this feature.
///
/// 5. After finishing the delivery the event is popped from the event stack.
/// ## `event`
/// An event to process (normally passed by GDK)
#[doc(alias = "gtk_main_do_event")]
pub fn main_do_event(event: &mut gdk::Event) {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gtk_main_do_event(event.to_glib_none_mut().0);
    }
}

/// Runs a single iteration of the mainloop.
///
/// If no events are waiting to be processed GTK+ will block
/// until the next event is noticed. If you don’t want to block
/// look at [`main_iteration_do()`][crate::main_iteration_do()] or check if any events are
/// pending with [`events_pending()`][crate::events_pending()] first.
///
/// # Returns
///
/// [`true`] if `gtk_main_quit()` has been called for the
///  innermost mainloop
#[doc(alias = "gtk_main_iteration")]
pub fn main_iteration() -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::gtk_main_iteration()) }
}

/// Runs a single iteration of the mainloop.
/// If no events are available either return or block depending on
/// the value of `blocking`.
/// ## `blocking`
/// [`true`] if you want GTK+ to block if no events are pending
///
/// # Returns
///
/// [`true`] if `gtk_main_quit()` has been called for the
///  innermost mainloop
#[doc(alias = "gtk_main_iteration_do")]
pub fn main_iteration_do(blocking: bool) -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::gtk_main_iteration_do(blocking.into_glib())) }
}

/// Asks for the current nesting level of the main loop.
///
/// # Returns
///
/// the nesting level of the current invocation
///  of the main loop
#[doc(alias = "gtk_main_level")]
pub fn main_level() -> u32 {
    assert_initialized_main_thread!();
    unsafe { ffi::gtk_main_level() }
}

/// Runs a page setup dialog, letting the user modify the values from
/// `page_setup`. If the user cancels the dialog, the returned [`PageSetup`][crate::PageSetup]
/// is identical to the passed in `page_setup`, otherwise it contains the
/// modifications done in the dialog.
///
/// Note that this function may use a recursive mainloop to show the page
/// setup dialog. See [`print_run_page_setup_dialog_async()`][crate::print_run_page_setup_dialog_async()] if this is
/// a problem.
/// ## `parent`
/// transient parent
/// ## `page_setup`
/// an existing [`PageSetup`][crate::PageSetup]
/// ## `settings`
/// a [`PrintSettings`][crate::PrintSettings]
///
/// # Returns
///
/// a new [`PageSetup`][crate::PageSetup]
#[doc(alias = "gtk_print_run_page_setup_dialog")]
pub fn print_run_page_setup_dialog(
    parent: Option<&impl IsA<Window>>,
    page_setup: Option<&PageSetup>,
    settings: &PrintSettings,
) -> Option<PageSetup> {
    skip_assert_initialized!();
    unsafe {
        from_glib_full(ffi::gtk_print_run_page_setup_dialog(
            parent.map(|p| p.as_ref()).to_glib_none().0,
            page_setup.to_glib_none().0,
            settings.to_glib_none().0,
        ))
    }
}

/// Runs a page setup dialog, letting the user modify the values from `page_setup`.
///
/// In contrast to [`print_run_page_setup_dialog()`][crate::print_run_page_setup_dialog()], this function returns after
/// showing the page setup dialog on platforms that support this, and calls `done_cb`
/// from a signal handler for the ::response signal of the dialog.
/// ## `parent`
/// transient parent, or [`None`]
/// ## `page_setup`
/// an existing [`PageSetup`][crate::PageSetup], or [`None`]
/// ## `settings`
/// a [`PrintSettings`][crate::PrintSettings]
/// ## `done_cb`
/// a function to call when the user saves
///  the modified page setup
#[doc(alias = "gtk_print_run_page_setup_dialog_async")]
pub fn print_run_page_setup_dialog_async<P: FnOnce(&PageSetup) + Send + Sync + 'static>(
    parent: Option<&impl IsA<Window>>,
    page_setup: Option<&PageSetup>,
    settings: &PrintSettings,
    done_cb: P,
) {
    skip_assert_initialized!();
    let done_cb_data: Box_<P> = Box_::new(done_cb);
    unsafe extern "C" fn done_cb_func<P: FnOnce(&PageSetup) + Send + Sync + 'static>(
        page_setup: *mut ffi::GtkPageSetup,
        data: glib::ffi::gpointer,
    ) {
        unsafe {
            let page_setup = from_glib_borrow(page_setup);
            let callback = Box_::from_raw(data as *mut P);
            (*callback)(&page_setup)
        }
    }
    let done_cb = Some(done_cb_func::<P> as _);
    let super_callback0: Box_<P> = done_cb_data;
    unsafe {
        ffi::gtk_print_run_page_setup_dialog_async(
            parent.map(|p| p.as_ref()).to_glib_none().0,
            page_setup.to_glib_none().0,
            settings.to_glib_none().0,
            done_cb,
            Box_::into_raw(super_callback0) as *mut _,
        );
    }
}

/// Sends an event to a widget, propagating the event to parent widgets
/// if the event remains unhandled.
///
/// Events received by GTK+ from GDK normally begin in [`main_do_event()`][crate::main_do_event()].
/// Depending on the type of event, existence of modal dialogs, grabs, etc.,
/// the event may be propagated; if so, this function is used.
///
/// [`propagate_event()`][crate::propagate_event()] calls [`WidgetExt::event()`][crate::prelude::WidgetExt::event()] on each widget it
/// decides to send the event to. So [`WidgetExt::event()`][crate::prelude::WidgetExt::event()] is the lowest-level
/// function; it simply emits the [`event`][struct@crate::Widget#event] and possibly an
/// event-specific signal on a widget. [`propagate_event()`][crate::propagate_event()] is a bit
/// higher-level, and [`main_do_event()`][crate::main_do_event()] is the highest level.
///
/// All that said, you most likely don’t want to use any of these
/// functions; synthesizing events is rarely needed. There are almost
/// certainly better ways to achieve your goals. For example, use
/// [`Window::invalidate_rect()`][crate::gdk::Window::invalidate_rect()] or [`WidgetExt::queue_draw()`][crate::prelude::WidgetExt::queue_draw()] instead
/// of making up expose events.
/// ## `widget`
/// a [`Widget`][crate::Widget]
/// ## `event`
/// an event
#[doc(alias = "gtk_propagate_event")]
pub fn propagate_event(widget: &impl IsA<Widget>, event: &mut gdk::Event) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_propagate_event(widget.as_ref().to_glib_none().0, event.to_glib_none_mut().0);
    }
}

/// Renders an activity indicator (such as in [`Spinner`][crate::Spinner]).
/// The state [`StateFlags::CHECKED`][crate::StateFlags::CHECKED] determines whether there is
/// activity going on.
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
#[doc(alias = "gtk_render_activity")]
pub fn render_activity(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_activity(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            width,
            height,
        );
    }
}

/// Renders an arrow pointing to `angle`.
///
/// Typical arrow rendering at 0, 1⁄2 π;, π; and 3⁄2 π:
///
/// ![](arrows.png)
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `angle`
/// arrow angle from 0 to 2 * `G_PI`, being 0 the arrow pointing to the north
/// ## `x`
/// X origin of the render area
/// ## `y`
/// Y origin of the render area
/// ## `size`
/// square side for render area
#[doc(alias = "gtk_render_arrow")]
pub fn render_arrow(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    angle: f64,
    x: f64,
    y: f64,
    size: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_arrow(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            angle,
            x,
            y,
            size,
        );
    }
}

/// Renders the background of an element.
///
/// Typical background rendering, showing the effect of
/// `background-image`, `border-width` and `border-radius`:
///
/// ![](background.png)
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
#[doc(alias = "gtk_render_background")]
pub fn render_background(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_background(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            width,
            height,
        );
    }
}

/// Returns the area that will be affected (i.e. drawn to) when
/// calling [`render_background()`][crate::render_background()] for the given `context` and
/// rectangle.
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
///
/// # Returns
///
///
/// ## `out_clip`
/// return location for the clip
#[doc(alias = "gtk_render_background_get_clip")]
pub fn render_background_get_clip(
    context: &impl IsA<StyleContext>,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
) -> gdk::Rectangle {
    skip_assert_initialized!();
    unsafe {
        let mut out_clip = gdk::Rectangle::uninitialized();
        ffi::gtk_render_background_get_clip(
            context.as_ref().to_glib_none().0,
            x,
            y,
            width,
            height,
            out_clip.to_glib_none_mut().0,
        );
        out_clip
    }
}

/// Renders a checkmark (as in a [`CheckButton`][crate::CheckButton]).
///
/// The [`StateFlags::CHECKED`][crate::StateFlags::CHECKED] state determines whether the check is
/// on or off, and [`StateFlags::INCONSISTENT`][crate::StateFlags::INCONSISTENT] determines whether it
/// should be marked as undefined.
///
/// Typical checkmark rendering:
///
/// ![](checks.png)
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
#[doc(alias = "gtk_render_check")]
pub fn render_check(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_check(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            width,
            height,
        );
    }
}

/// Renders an expander (as used in [`TreeView`][crate::TreeView] and [`Expander`][crate::Expander]) in the area
/// defined by `x`, `y`, `width`, `height`. The state [`StateFlags::CHECKED`][crate::StateFlags::CHECKED]
/// determines whether the expander is collapsed or expanded.
///
/// Typical expander rendering:
///
/// ![](expanders.png)
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
#[doc(alias = "gtk_render_expander")]
pub fn render_expander(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_expander(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            width,
            height,
        );
    }
}

/// Renders a extension (as in a [`Notebook`][crate::Notebook] tab) in the rectangle
/// defined by `x`, `y`, `width`, `height`. The side where the extension
/// connects to is defined by `gap_side`.
///
/// Typical extension rendering:
///
/// ![](extensions.png)
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
/// ## `gap_side`
/// side where the gap is
#[doc(alias = "gtk_render_extension")]
pub fn render_extension(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
    gap_side: PositionType,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_extension(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            width,
            height,
            gap_side.into_glib(),
        );
    }
}

/// Renders a focus indicator on the rectangle determined by `x`, `y`, `width`, `height`.
///
/// Typical focus rendering:
///
/// ![](focus.png)
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
#[doc(alias = "gtk_render_focus")]
pub fn render_focus(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_focus(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            width,
            height,
        );
    }
}

/// Renders a frame around the rectangle defined by `x`, `y`, `width`, `height`.
///
/// Examples of frame rendering, showing the effect of `border-image`,
/// `border-color`, `border-width`, `border-radius` and junctions:
///
/// ![](frames.png)
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
#[doc(alias = "gtk_render_frame")]
pub fn render_frame(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_frame(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            width,
            height,
        );
    }
}

/// Renders a frame around the rectangle defined by (`x`, `y`, `width`, `height`),
/// leaving a gap on one side. `xy0_gap` and `xy1_gap` will mean X coordinates
/// for [`PositionType::Top`][crate::PositionType::Top] and [`PositionType::Bottom`][crate::PositionType::Bottom] gap sides, and Y coordinates for
/// [`PositionType::Left`][crate::PositionType::Left] and [`PositionType::Right`][crate::PositionType::Right].
///
/// Typical rendering of a frame with a gap:
///
/// ![](frame-gap.png)
///
/// # Deprecated since 3.24
///
/// Use [`render_frame()`][crate::render_frame()] instead. Themes can create gaps
///  by omitting borders via CSS.
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
/// ## `gap_side`
/// side where the gap is
/// ## `xy0_gap`
/// initial coordinate (X or Y depending on `gap_side`) for the gap
/// ## `xy1_gap`
/// end coordinate (X or Y depending on `gap_side`) for the gap
#[cfg_attr(feature = "v3_24", deprecated = "Since 3.24")]
#[allow(deprecated)]
#[doc(alias = "gtk_render_frame_gap")]
pub fn render_frame_gap(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
    gap_side: PositionType,
    xy0_gap: f64,
    xy1_gap: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_frame_gap(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            width,
            height,
            gap_side.into_glib(),
            xy0_gap,
            xy1_gap,
        );
    }
}

/// Renders a handle (as in `GtkHandleBox`, [`Paned`][crate::Paned] and
/// [`Window`][crate::Window]’s resize grip), in the rectangle
/// determined by `x`, `y`, `width`, `height`.
///
/// Handles rendered for the paned and grip classes:
///
/// ![](handles.png)
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
#[doc(alias = "gtk_render_handle")]
pub fn render_handle(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_handle(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            width,
            height,
        );
    }
}

/// Renders the icon in `pixbuf` at the specified `x` and `y` coordinates.
///
/// This function will render the icon in `pixbuf` at exactly its size,
/// regardless of scaling factors, which may not be appropriate when
/// drawing on displays with high pixel densities.
///
/// You probably want to use [`render_icon_surface()`][crate::render_icon_surface()] instead, if you
/// already have a Cairo surface.
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `pixbuf`
/// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf] containing the icon to draw
/// ## `x`
/// X position for the `pixbuf`
/// ## `y`
/// Y position for the `pixbuf`
#[doc(alias = "gtk_render_icon")]
pub fn render_icon(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    pixbuf: &gdk_pixbuf::Pixbuf,
    x: f64,
    y: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_icon(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            pixbuf.to_glib_none().0,
            x,
            y,
        );
    }
}

/// Renders the icon in `surface` at the specified `x` and `y` coordinates.
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `surface`
/// a [`cairo::Surface`][crate::cairo::Surface] containing the icon to draw
/// ## `x`
/// X position for the `icon`
/// ## `y`
/// Y position for the `incon`
#[doc(alias = "gtk_render_icon_surface")]
pub fn render_icon_surface(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    surface: &cairo::Surface,
    x: f64,
    y: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_icon_surface(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            mut_override(surface.to_glib_none().0),
            x,
            y,
        );
    }
}

/// Draws a text caret on `cr` at the specified index of `layout`.
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin
/// ## `y`
/// Y origin
/// ## `layout`
/// the [`pango::Layout`][crate::pango::Layout] of the text
/// ## `index`
/// the index in the [`pango::Layout`][crate::pango::Layout]
/// ## `direction`
/// the [`pango::Direction`][crate::pango::Direction] of the text
#[doc(alias = "gtk_render_insertion_cursor")]
pub fn render_insertion_cursor(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    layout: &pango::Layout,
    index: i32,
    direction: pango::Direction,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_insertion_cursor(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            layout.to_glib_none().0,
            index,
            direction.into_glib(),
        );
    }
}

/// Renders `layout` on the coordinates `x`, `y`
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin
/// ## `y`
/// Y origin
/// ## `layout`
/// the [`pango::Layout`][crate::pango::Layout] to render
#[doc(alias = "gtk_render_layout")]
pub fn render_layout(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    layout: &pango::Layout,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_layout(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            layout.to_glib_none().0,
        );
    }
}

/// Renders a line from (x0, y0) to (x1, y1).
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x0`
/// X coordinate for the origin of the line
/// ## `y0`
/// Y coordinate for the origin of the line
/// ## `x1`
/// X coordinate for the end of the line
/// ## `y1`
/// Y coordinate for the end of the line
#[doc(alias = "gtk_render_line")]
pub fn render_line(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x0: f64,
    y0: f64,
    x1: f64,
    y1: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_line(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x0,
            y0,
            x1,
            y1,
        );
    }
}

/// Renders an option mark (as in a [`RadioButton`][crate::RadioButton]), the [`StateFlags::CHECKED`][crate::StateFlags::CHECKED]
/// state will determine whether the option is on or off, and
/// [`StateFlags::INCONSISTENT`][crate::StateFlags::INCONSISTENT] whether it should be marked as undefined.
///
/// Typical option mark rendering:
///
/// ![](options.png)
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
#[doc(alias = "gtk_render_option")]
pub fn render_option(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_option(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            width,
            height,
        );
    }
}

/// Renders a slider (as in [`Scale`][crate::Scale]) in the rectangle defined by `x`, `y`,
/// `width`, `height`. `orientation` defines whether the slider is vertical
/// or horizontal.
///
/// Typical slider rendering:
///
/// ![](sliders.png)
/// ## `context`
/// a [`StyleContext`][crate::StyleContext]
/// ## `cr`
/// a [`cairo::Context`][crate::cairo::Context]
/// ## `x`
/// X origin of the rectangle
/// ## `y`
/// Y origin of the rectangle
/// ## `width`
/// rectangle width
/// ## `height`
/// rectangle height
/// ## `orientation`
/// orientation of the slider
#[doc(alias = "gtk_render_slider")]
pub fn render_slider(
    context: &impl IsA<StyleContext>,
    cr: &cairo::Context,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
    orientation: Orientation,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_render_slider(
            context.as_ref().to_glib_none().0,
            mut_override(cr.to_glib_none().0),
            x,
            y,
            width,
            height,
            orientation.into_glib(),
        );
    }
}

/// Converts a color from RGB space to HSV.
///
/// Input values must be in the [0.0, 1.0] range;
/// output values will be in the same range.
/// ## `r`
/// Red
/// ## `g`
/// Green
/// ## `b`
/// Blue
///
/// # Returns
///
///
/// ## `h`
/// Return value for the hue component
///
/// ## `s`
/// Return value for the saturation component
///
/// ## `v`
/// Return value for the value component
#[doc(alias = "gtk_rgb_to_hsv")]
pub fn rgb_to_hsv(r: f64, g: f64, b: f64) -> (f64, f64, f64) {
    assert_initialized_main_thread!();
    unsafe {
        let mut h = std::mem::MaybeUninit::uninit();
        let mut s = std::mem::MaybeUninit::uninit();
        let mut v = std::mem::MaybeUninit::uninit();
        ffi::gtk_rgb_to_hsv(r, g, b, h.as_mut_ptr(), s.as_mut_ptr(), v.as_mut_ptr());
        (h.assume_init(), s.assume_init(), v.assume_init())
    }
}

/// Appends a specified target to the list of supported targets for a
/// given widget and selection.
/// ## `widget`
/// a [`Widget`][crate::Widget]
/// ## `selection`
/// the selection
/// ## `target`
/// target to add.
/// ## `info`
/// A unsigned integer which will be passed back to the application.
#[doc(alias = "gtk_selection_add_target")]
pub fn selection_add_target(
    widget: &impl IsA<Widget>,
    selection: &gdk::Atom,
    target: &gdk::Atom,
    info: u32,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_selection_add_target(
            widget.as_ref().to_glib_none().0,
            selection.to_glib_none().0,
            target.to_glib_none().0,
            info,
        );
    }
}

/// Remove all targets registered for the given selection for the
/// widget.
/// ## `widget`
/// a [`Widget`][crate::Widget]
/// ## `selection`
/// an atom representing a selection
#[doc(alias = "gtk_selection_clear_targets")]
pub fn selection_clear_targets(widget: &impl IsA<Widget>, selection: &gdk::Atom) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_selection_clear_targets(
            widget.as_ref().to_glib_none().0,
            selection.to_glib_none().0,
        );
    }
}

/// Requests the contents of a selection. When received,
/// a “selection-received” signal will be generated.
/// ## `widget`
/// The widget which acts as requestor
/// ## `selection`
/// Which selection to get
/// ## `target`
/// Form of information desired (e.g., STRING)
/// ## `time_`
/// Time of request (usually of triggering event)
///  In emergency, you could use `GDK_CURRENT_TIME`
///
/// # Returns
///
/// [`true`] if requested succeeded. [`false`] if we could not process
///  request. (e.g., there was already a request in process for
///  this widget).
#[doc(alias = "gtk_selection_convert")]
pub fn selection_convert(
    widget: &impl IsA<Widget>,
    selection: &gdk::Atom,
    target: &gdk::Atom,
    time_: u32,
) -> bool {
    skip_assert_initialized!();
    unsafe {
        from_glib(ffi::gtk_selection_convert(
            widget.as_ref().to_glib_none().0,
            selection.to_glib_none().0,
            target.to_glib_none().0,
            time_,
        ))
    }
}

/// Claims ownership of a given selection for a particular widget,
/// or, if `widget` is [`None`], release ownership of the selection.
/// ## `widget`
/// a [`Widget`][crate::Widget], or [`None`].
/// ## `selection`
/// an interned atom representing the selection to claim
/// ## `time_`
/// timestamp with which to claim the selection
///
/// # Returns
///
/// [`true`] if the operation succeeded
#[doc(alias = "gtk_selection_owner_set")]
pub fn selection_owner_set(
    widget: Option<&impl IsA<Widget>>,
    selection: &gdk::Atom,
    time_: u32,
) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::gtk_selection_owner_set(
            widget.map(|p| p.as_ref()).to_glib_none().0,
            selection.to_glib_none().0,
            time_,
        ))
    }
}

/// Claim ownership of a given selection for a particular widget, or,
/// if `widget` is [`None`], release ownership of the selection.
/// ## `display`
/// the [`gdk::Display`][crate::gdk::Display] where the selection is set
/// ## `widget`
/// new selection owner (a [`Widget`][crate::Widget]), or [`None`].
/// ## `selection`
/// an interned atom representing the selection to claim.
/// ## `time_`
/// timestamp with which to claim the selection
///
/// # Returns
///
/// TRUE if the operation succeeded
#[doc(alias = "gtk_selection_owner_set_for_display")]
pub fn selection_owner_set_for_display(
    display: &gdk::Display,
    widget: Option<&impl IsA<Widget>>,
    selection: &gdk::Atom,
    time_: u32,
) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::gtk_selection_owner_set_for_display(
            display.to_glib_none().0,
            widget.map(|p| p.as_ref()).to_glib_none().0,
            selection.to_glib_none().0,
            time_,
        ))
    }
}

/// Removes all handlers and unsets ownership of all
/// selections for a widget. Called when widget is being
/// destroyed. This function will not generally be
/// called by applications.
/// ## `widget`
/// a [`Widget`][crate::Widget]
#[doc(alias = "gtk_selection_remove_all")]
pub fn selection_remove_all(widget: &impl IsA<Widget>) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_selection_remove_all(widget.as_ref().to_glib_none().0);
    }
}

/// Sets the GTK+ debug flags.
#[doc(alias = "gtk_set_debug_flags")]
pub fn set_debug_flags(flags: u32) {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gtk_set_debug_flags(flags);
    }
}

//#[doc(alias = "gtk_show_about_dialog")]
//pub fn show_about_dialog(parent: Option<&impl IsA<Window>>, first_property_name: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
//    unsafe { TODO: call ffi:gtk_show_about_dialog() }
//}

/// This is a convenience function for launching the default application
/// to show the uri. The uri must be of a form understood by GIO (i.e. you
/// need to install gvfs to get support for uri schemes such as http://
/// or ftp://, as only local files are handled by GIO itself).
/// Typical examples are
/// - `file:///home/gnome/pict.jpg`
/// - `http://www.gnome.org`
/// - `mailto:me`gnome``
///
/// Ideally the timestamp is taken from the event triggering
/// the `gtk_show_uri()` call. If timestamp is not known you can take
/// `GDK_CURRENT_TIME`.
///
/// This is the recommended call to be used as it passes information
/// necessary for sandbox helpers to parent their dialogs properly.
/// ## `parent`
/// parent window
/// ## `uri`
/// the uri to show
/// ## `timestamp`
/// a timestamp to prevent focus stealing
///
/// # Returns
///
/// [`true`] on success, [`false`] on error
#[doc(alias = "gtk_show_uri_on_window")]
pub fn show_uri_on_window(
    parent: Option<&impl IsA<Window>>,
    uri: &str,
    timestamp: u32,
) -> Result<(), glib::Error> {
    assert_initialized_main_thread!();
    unsafe {
        let mut error = std::ptr::null_mut();
        let is_ok = ffi::gtk_show_uri_on_window(
            parent.map(|p| p.as_ref()).to_glib_none().0,
            uri.to_glib_none().0,
            timestamp,
            &mut error,
        );
        debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
        if error.is_null() {
            Ok(())
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Determines if any of the targets in `targets` can be used to
/// provide a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf].
/// ## `targets`
/// an array of `GdkAtoms`
/// ## `writable`
/// whether to accept only targets for which GTK+ knows
///  how to convert a pixbuf into the format
///
/// # Returns
///
/// [`true`] if `targets` include a suitable target for images,
///  otherwise [`false`].
#[doc(alias = "gtk_targets_include_image")]
pub fn targets_include_image(targets: &[gdk::Atom], writable: bool) -> bool {
    assert_initialized_main_thread!();
    let n_targets = targets.len() as _;
    unsafe {
        from_glib(ffi::gtk_targets_include_image(
            targets.to_glib_none().0,
            n_targets,
            writable.into_glib(),
        ))
    }
}

/// Determines if any of the targets in `targets` can be used to
/// provide rich text.
/// ## `targets`
/// an array of `GdkAtoms`
/// ## `buffer`
/// a [`TextBuffer`][crate::TextBuffer]
///
/// # Returns
///
/// [`true`] if `targets` include a suitable target for rich text,
///  otherwise [`false`].
#[doc(alias = "gtk_targets_include_rich_text")]
pub fn targets_include_rich_text(targets: &[gdk::Atom], buffer: &impl IsA<TextBuffer>) -> bool {
    skip_assert_initialized!();
    let n_targets = targets.len() as _;
    unsafe {
        from_glib(ffi::gtk_targets_include_rich_text(
            targets.to_glib_none().0,
            n_targets,
            buffer.as_ref().to_glib_none().0,
        ))
    }
}

/// Determines if any of the targets in `targets` can be used to
/// provide text.
/// ## `targets`
/// an array of `GdkAtoms`
///
/// # Returns
///
/// [`true`] if `targets` include a suitable target for text,
///  otherwise [`false`].
#[doc(alias = "gtk_targets_include_text")]
pub fn targets_include_text(targets: &[gdk::Atom]) -> bool {
    assert_initialized_main_thread!();
    let n_targets = targets.len() as _;
    unsafe {
        from_glib(ffi::gtk_targets_include_text(
            targets.to_glib_none().0,
            n_targets,
        ))
    }
}

/// Determines if any of the targets in `targets` can be used to
/// provide an uri list.
/// ## `targets`
/// an array of `GdkAtoms`
///
/// # Returns
///
/// [`true`] if `targets` include a suitable target for uri lists,
///  otherwise [`false`].
#[doc(alias = "gtk_targets_include_uri")]
pub fn targets_include_uri(targets: &[gdk::Atom]) -> bool {
    assert_initialized_main_thread!();
    let n_targets = targets.len() as _;
    unsafe {
        from_glib(ffi::gtk_targets_include_uri(
            targets.to_glib_none().0,
            n_targets,
        ))
    }
}

/// This function will search `widget` and all its descendants for a GtkLabel
/// widget with a text string matching `label_pattern`.
/// The `label_pattern` may contain asterisks “*” and question marks “?” as
/// placeholders, `g_pattern_match()` is used for the matching.
/// Note that locales other than "C“ tend to alter (translate” label strings,
/// so this function is genrally only useful in test programs with
/// predetermined locales, see `gtk_test_init()` for more details.
/// ## `widget`
/// Valid label or container widget.
/// ## `label_pattern`
/// Shell-glob pattern to match a label string.
///
/// # Returns
///
/// a GtkLabel widget if any is found.
#[doc(alias = "gtk_test_find_label")]
pub fn test_find_label(widget: &impl IsA<Widget>, label_pattern: &str) -> Option<Widget> {
    skip_assert_initialized!();
    unsafe {
        from_glib_none(ffi::gtk_test_find_label(
            widget.as_ref().to_glib_none().0,
            label_pattern.to_glib_none().0,
        ))
    }
}

/// This function will search siblings of `base_widget` and siblings of its
/// ancestors for all widgets matching `widget_type`.
/// Of the matching widgets, the one that is geometrically closest to
/// `base_widget` will be returned.
/// The general purpose of this function is to find the most likely “action”
/// widget, relative to another labeling widget. Such as finding a
/// button or text entry widget, given its corresponding label widget.
/// ## `base_widget`
/// Valid widget, part of a widget hierarchy
/// ## `widget_type`
/// Type of a aearched for sibling widget
///
/// # Returns
///
/// a widget of type `widget_type` if any is found.
#[doc(alias = "gtk_test_find_sibling")]
pub fn test_find_sibling(
    base_widget: &impl IsA<Widget>,
    widget_type: glib::types::Type,
) -> Option<Widget> {
    skip_assert_initialized!();
    unsafe {
        from_glib_none(ffi::gtk_test_find_sibling(
            base_widget.as_ref().to_glib_none().0,
            widget_type.into_glib(),
        ))
    }
}

/// This function will search the descendants of `widget` for a widget
/// of type `widget_type` that has a label matching `label_pattern` next
/// to it. This is most useful for automated GUI testing, e.g. to find
/// the “OK” button in a dialog and synthesize clicks on it.
/// However see [`test_find_label()`][crate::test_find_label()], [`test_find_sibling()`][crate::test_find_sibling()] and
/// `gtk_test_widget_click()` for possible caveats involving the search of
/// such widgets and synthesizing widget events.
/// ## `widget`
/// Container widget, usually a GtkWindow.
/// ## `label_pattern`
/// Shell-glob pattern to match a label string.
/// ## `widget_type`
/// Type of a aearched for label sibling widget.
///
/// # Returns
///
/// a valid widget if any is found or [`None`].
#[doc(alias = "gtk_test_find_widget")]
pub fn test_find_widget(
    widget: &impl IsA<Widget>,
    label_pattern: &str,
    widget_type: glib::types::Type,
) -> Option<Widget> {
    skip_assert_initialized!();
    unsafe {
        from_glib_none(ffi::gtk_test_find_widget(
            widget.as_ref().to_glib_none().0,
            label_pattern.to_glib_none().0,
            widget_type.into_glib(),
        ))
    }
}

//#[doc(alias = "gtk_test_list_all_types")]
//pub fn test_list_all_types() -> /*Unimplemented*/CArray TypeId { ns_id: 0, id: 30 } {
//    unsafe { TODO: call ffi:gtk_test_list_all_types() }
//}

/// Force registration of all core Gtk+ and Gdk object types.
/// This allowes to refer to any of those object types via
/// `g_type_from_name()` after calling this function.
#[doc(alias = "gtk_test_register_all_types")]
pub fn test_register_all_types() {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gtk_test_register_all_types();
    }
}

/// window.
/// Certain caveats should be considered when using this function, in
/// particular because the mouse pointer is warped to the key press
/// location, see `gdk_test_simulate_key()` for details.
/// ## `widget`
/// Widget to generate a key press and release on.
/// ## `keyval`
/// A Gdk keyboard value.
/// ## `modifiers`
/// Keyboard modifiers the event is setup with.
///
/// # Returns
///
/// whether all actions neccessary for the key event simulation were carried out successfully.
#[doc(alias = "gtk_test_widget_send_key")]
pub fn test_widget_send_key(
    widget: &impl IsA<Widget>,
    keyval: u32,
    modifiers: gdk::ModifierType,
) -> bool {
    skip_assert_initialized!();
    unsafe {
        from_glib(ffi::gtk_test_widget_send_key(
            widget.as_ref().to_glib_none().0,
            keyval,
            modifiers.into_glib(),
        ))
    }
}

/// Enters the main loop and waits for `widget` to be “drawn”. In this
/// context that means it waits for the frame clock of `widget` to have
/// run a full styling, layout and drawing cycle.
///
/// This function is intended to be used for syncing with actions that
/// depend on `widget` relayouting or on interaction with the display
/// server.
/// ## `widget`
/// the widget to wait for
#[doc(alias = "gtk_test_widget_wait_for_draw")]
pub fn test_widget_wait_for_draw(widget: &impl IsA<Widget>) {
    skip_assert_initialized!();
    unsafe {
        ffi::gtk_test_widget_wait_for_draw(widget.as_ref().to_glib_none().0);
    }
}

/// Obtains a `tree_model` and `path` from selection data of target type
/// `GTK_TREE_MODEL_ROW`. Normally called from a drag_data_received handler.
/// This function can only be used if `selection_data` originates from the same
/// process that’s calling this function, because a pointer to the tree model
/// is being passed around. If you aren’t in the same process, then you'll
/// get memory corruption. In the [`TreeDragDest`][crate::TreeDragDest] drag_data_received handler,
/// you can assume that selection data of type `GTK_TREE_MODEL_ROW` is
/// in from the current process. The returned path must be freed with
/// `gtk_tree_path_free()`.
/// ## `selection_data`
/// a [`SelectionData`][crate::SelectionData]
///
/// # Returns
///
/// [`true`] if `selection_data` had target type `GTK_TREE_MODEL_ROW` and
///  is otherwise valid
///
/// ## `tree_model`
/// a [`TreeModel`][crate::TreeModel]
///
/// ## `path`
/// row in `tree_model`
#[doc(alias = "gtk_tree_get_row_drag_data")]
pub fn tree_get_row_drag_data(
    selection_data: &SelectionData,
) -> Option<(Option<TreeModel>, Option<TreePath>)> {
    assert_initialized_main_thread!();
    unsafe {
        let mut tree_model = std::ptr::null_mut();
        let mut path = std::ptr::null_mut();
        let ret = from_glib(ffi::gtk_tree_get_row_drag_data(
            mut_override(selection_data.to_glib_none().0),
            &mut tree_model,
            &mut path,
        ));
        if ret {
            Some((from_glib_none(tree_model), from_glib_full(path)))
        } else {
            None
        }
    }
}

/// Sets selection data of target type `GTK_TREE_MODEL_ROW`. Normally used
/// in a drag_data_get handler.
/// ## `selection_data`
/// some [`SelectionData`][crate::SelectionData]
/// ## `tree_model`
/// a [`TreeModel`][crate::TreeModel]
/// ## `path`
/// a row in `tree_model`
///
/// # Returns
///
/// [`true`] if the [`SelectionData`][crate::SelectionData] had the proper target type to allow us to set a tree row
#[doc(alias = "gtk_tree_set_row_drag_data")]
pub fn tree_set_row_drag_data(
    selection_data: &SelectionData,
    tree_model: &impl IsA<TreeModel>,
    path: &mut TreePath,
) -> bool {
    skip_assert_initialized!();
    unsafe {
        from_glib(ffi::gtk_tree_set_row_drag_data(
            mut_override(selection_data.to_glib_none().0),
            tree_model.as_ref().to_glib_none().0,
            path.to_glib_none_mut().0,
        ))
    }
}

/// argv);
///
///  win = gtk_window_new (GTK_WINDOW_TOPLEVEL);
///  g_signal_connect (win,
///  "delete-event",
///  G_CALLBACK (gtk_true),
///  NULL);
///  g_signal_connect (win, "destroy",
///  G_CALLBACK (gtk_main_quit),
///  NULL);
///
///  but = gtk_button_new_with_label (text);
///  g_signal_connect_swapped (but, "clicked",
///  G_CALLBACK (gtk_object_destroy),
///  win);
///  gtk_container_add (GTK_CONTAINER (win), but);
///
///  gtk_widget_show_all (win);
///
///  gtk_main ();
///
///  return 0;
/// }
/// ]|
///
/// # Returns
///
/// [`true`]
#[doc(alias = "gtk_true")]
#[doc(alias = "true")]
pub fn true_() -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::gtk_true()) }
}