gdk/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::{Atom, Display, Event, EventType, ModifierType, Screen, Window, WindowState};
use glib::translate::*;
use std::{mem, ptr};

/// Emits a short beep on the default display.
#[doc(alias = "gdk_beep")]
pub fn beep() {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gdk_beep();
    }
}

/// Removes an error trap pushed with [`error_trap_push()`][crate::error_trap_push()].
/// May block until an error has been definitively received
/// or not received from the X server. [`error_trap_pop_ignored()`][crate::error_trap_pop_ignored()]
/// is preferred if you don’t need to know whether an error
/// occurred, because it never has to block. If you don't
/// need the return value of [`error_trap_pop()`][crate::error_trap_pop()], use
/// [`error_trap_pop_ignored()`][crate::error_trap_pop_ignored()].
///
/// Prior to GDK 3.0, this function would not automatically
/// sync for you, so you had to [`flush()`][crate::flush()] if your last
/// call to Xlib was not a blocking round trip.
///
/// # Returns
///
/// X error code or 0 on success
#[doc(alias = "gdk_error_trap_pop")]
pub fn error_trap_pop() -> i32 {
    assert_initialized_main_thread!();
    unsafe { ffi::gdk_error_trap_pop() }
}

/// Removes an error trap pushed with [`error_trap_push()`][crate::error_trap_push()], but
/// without bothering to wait and see whether an error occurred. If an
/// error arrives later asynchronously that was triggered while the
/// trap was pushed, that error will be ignored.
#[doc(alias = "gdk_error_trap_pop_ignored")]
pub fn error_trap_pop_ignored() {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gdk_error_trap_pop_ignored();
    }
}

/// This function allows X errors to be trapped instead of the normal
/// behavior of exiting the application. It should only be used if it
/// is not possible to avoid the X error in any other way. Errors are
/// ignored on all [`Display`][crate::Display] currently known to the
/// [`DisplayManager`][crate::DisplayManager]. If you don’t care which error happens and just
/// want to ignore everything, pop with [`error_trap_pop_ignored()`][crate::error_trap_pop_ignored()].
/// If you need the error code, use [`error_trap_pop()`][crate::error_trap_pop()] which may have
/// to block and wait for the error to arrive from the X server.
///
/// This API exists on all platforms but only does anything on X.
///
/// You can use `gdk_x11_display_error_trap_push()` to ignore errors
/// on only a single display.
///
/// ## Trapping an X error
///
///
///
/// **⚠️ The following code is in C ⚠️**
///
/// ```C
/// gdk_error_trap_push ();
///
///  // ... Call the X function which may cause an error here ...
///
///
/// if (gdk_error_trap_pop ())
///  {
///    // ... Handle the error here ...
///  }
/// ```
#[doc(alias = "gdk_error_trap_push")]
pub fn error_trap_push() {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gdk_error_trap_push();
    }
}

/// If both events contain X/Y information, this function will return [`true`]
/// and return in `angle` the relative angle from `event1` to `event2`. The rotation
/// direction for positive angles is from the positive X axis towards the positive
/// Y axis.
/// ## `event1`
/// first `GdkEvent`
/// ## `event2`
/// second `GdkEvent`
///
/// # Returns
///
/// [`true`] if the angle could be calculated.
///
/// ## `angle`
/// return location for the relative angle between both events
#[doc(alias = "gdk_events_get_angle")]
pub fn events_get_angle(event1: &mut Event, event2: &mut Event) -> Option<f64> {
    assert_initialized_main_thread!();
    unsafe {
        let mut angle = mem::MaybeUninit::uninit();
        let ret = from_glib(ffi::gdk_events_get_angle(
            event1.to_glib_none_mut().0,
            event2.to_glib_none_mut().0,
            angle.as_mut_ptr(),
        ));
        if ret {
            Some(angle.assume_init())
        } else {
            None
        }
    }
}

/// If both events contain X/Y information, the center of both coordinates
/// will be returned in `x` and `y`.
/// ## `event1`
/// first `GdkEvent`
/// ## `event2`
/// second `GdkEvent`
///
/// # Returns
///
/// [`true`] if the center could be calculated.
///
/// ## `x`
/// return location for the X coordinate of the center
///
/// ## `y`
/// return location for the Y coordinate of the center
#[doc(alias = "gdk_events_get_center")]
pub fn events_get_center(event1: &mut Event, event2: &mut Event) -> Option<(f64, f64)> {
    assert_initialized_main_thread!();
    unsafe {
        let mut x = mem::MaybeUninit::uninit();
        let mut y = mem::MaybeUninit::uninit();
        let ret = from_glib(ffi::gdk_events_get_center(
            event1.to_glib_none_mut().0,
            event2.to_glib_none_mut().0,
            x.as_mut_ptr(),
            y.as_mut_ptr(),
        ));
        if ret {
            Some((x.assume_init(), y.assume_init()))
        } else {
            None
        }
    }
}

/// If both events have X/Y information, the distance between both coordinates
/// (as in a straight line going from `event1` to `event2`) will be returned.
/// ## `event1`
/// first `GdkEvent`
/// ## `event2`
/// second `GdkEvent`
///
/// # Returns
///
/// [`true`] if the distance could be calculated.
///
/// ## `distance`
/// return location for the distance
#[doc(alias = "gdk_events_get_distance")]
pub fn events_get_distance(event1: &mut Event, event2: &mut Event) -> Option<f64> {
    assert_initialized_main_thread!();
    unsafe {
        let mut distance = mem::MaybeUninit::uninit();
        let ret = from_glib(ffi::gdk_events_get_distance(
            event1.to_glib_none_mut().0,
            event2.to_glib_none_mut().0,
            distance.as_mut_ptr(),
        ));
        if ret {
            Some(distance.assume_init())
        } else {
            None
        }
    }
}

/// Checks if any events are ready to be processed for any display.
///
/// # Returns
///
/// [`true`] if any events are pending.
#[doc(alias = "gdk_events_pending")]
pub fn events_pending() -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::gdk_events_pending()) }
}

/// Flushes the output buffers of all display connections and waits
/// until all requests have been processed.
/// This is rarely needed by applications.
#[doc(alias = "gdk_flush")]
pub fn flush() {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gdk_flush();
    }
}

/// Gets the display name specified in the command line arguments passed
/// to `gdk_init()` or `gdk_parse_args()`, if any.
///
/// # Returns
///
/// the display name, if specified explicitly,
///  otherwise [`None`] this string is owned by GTK+ and must not be
///  modified or freed.
#[doc(alias = "gdk_get_display_arg_name")]
#[doc(alias = "get_display_arg_name")]
pub fn display_arg_name() -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe { from_glib_none(ffi::gdk_get_display_arg_name()) }
}

/// Gets the program class. Unless the program class has explicitly
/// been set with [`set_program_class()`][crate::set_program_class()] or with the `--class`
/// commandline option, the default value is the program name (determined
/// with `g_get_prgname()`) with the first character converted to uppercase.
///
/// # Returns
///
/// the program class.
#[doc(alias = "gdk_get_program_class")]
#[doc(alias = "get_program_class")]
pub fn program_class() -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe { from_glib_none(ffi::gdk_get_program_class()) }
}

/// Gets whether event debugging output is enabled.
///
/// # Returns
///
/// [`true`] if event debugging output is enabled.
#[doc(alias = "gdk_get_show_events")]
#[doc(alias = "get_show_events")]
pub fn shows_events() -> bool {
    assert_initialized_main_thread!();
    unsafe { from_glib(ffi::gdk_get_show_events()) }
}

/// Indicates to the GUI environment that the application has finished
/// loading. If the applications opens windows, this function is
/// normally called after opening the application’s initial set of
/// windows.
///
/// GTK+ will call this function automatically after opening the first
/// `GtkWindow` unless `gtk_window_set_auto_startup_notification()` is called
/// to disable that feature.
#[doc(alias = "gdk_notify_startup_complete")]
pub fn notify_startup_complete() {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gdk_notify_startup_complete();
    }
}

/// Indicates to the GUI environment that the application has
/// finished loading, using a given identifier.
///
/// GTK+ will call this function automatically for `GtkWindow`
/// with custom startup-notification identifier unless
/// `gtk_window_set_auto_startup_notification()` is called to
/// disable that feature.
/// ## `startup_id`
/// a startup-notification identifier, for which
///  notification process should be completed
#[doc(alias = "gdk_notify_startup_complete_with_id")]
pub fn notify_startup_complete_with_id(startup_id: &str) {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gdk_notify_startup_complete_with_id(startup_id.to_glib_none().0);
    }
}

/// Creates a [`pango::Context`][crate::pango::Context] for the default GDK screen.
///
/// The context must be freed when you’re finished with it.
///
/// When using GTK+, normally you should use `gtk_widget_get_pango_context()`
/// instead of this function, to get the appropriate context for
/// the widget you intend to render text onto.
///
/// The newly created context will have the default font options (see
/// [`cairo::FontOptions`][crate::cairo::FontOptions]) for the default screen; if these options
/// change it will not be updated. Using `gtk_widget_get_pango_context()`
/// is more convenient if you want to keep a context around and track
/// changes to the screen’s font rendering settings.
///
/// # Returns
///
/// a new [`pango::Context`][crate::pango::Context] for the default display
#[doc(alias = "gdk_pango_context_get")]
pub fn pango_context_get() -> Option<pango::Context> {
    assert_initialized_main_thread!();
    unsafe { from_glib_full(ffi::gdk_pango_context_get()) }
}

/// Creates a [`pango::Context`][crate::pango::Context] for `display`.
///
/// The context must be freed when you’re finished with it.
///
/// When using GTK+, normally you should use `gtk_widget_get_pango_context()`
/// instead of this function, to get the appropriate context for
/// the widget you intend to render text onto.
///
/// The newly created context will have the default font options
/// (see [`cairo::FontOptions`][crate::cairo::FontOptions]) for the display; if these options
/// change it will not be updated. Using `gtk_widget_get_pango_context()`
/// is more convenient if you want to keep a context around and track
/// changes to the font rendering settings.
/// ## `display`
/// the [`Display`][crate::Display] for which the context is to be created
///
/// # Returns
///
/// a new [`pango::Context`][crate::pango::Context] for `display`
#[doc(alias = "gdk_pango_context_get_for_display")]
pub fn pango_context_get_for_display(display: &Display) -> Option<pango::Context> {
    skip_assert_initialized!();
    unsafe {
        from_glib_full(ffi::gdk_pango_context_get_for_display(
            display.to_glib_none().0,
        ))
    }
}

/// Creates a [`pango::Context`][crate::pango::Context] for `screen`.
///
/// The context must be freed when you’re finished with it.
///
/// When using GTK+, normally you should use `gtk_widget_get_pango_context()`
/// instead of this function, to get the appropriate context for
/// the widget you intend to render text onto.
///
/// The newly created context will have the default font options
/// (see [`cairo::FontOptions`][crate::cairo::FontOptions]) for the screen; if these options
/// change it will not be updated. Using `gtk_widget_get_pango_context()`
/// is more convenient if you want to keep a context around and track
/// changes to the screen’s font rendering settings.
/// ## `screen`
/// the [`Screen`][crate::Screen] for which the context is to be created.
///
/// # Returns
///
/// a new [`pango::Context`][crate::pango::Context] for `screen`
#[doc(alias = "gdk_pango_context_get_for_screen")]
pub fn pango_context_get_for_screen(screen: &Screen) -> Option<pango::Context> {
    skip_assert_initialized!();
    unsafe {
        from_glib_full(ffi::gdk_pango_context_get_for_screen(
            screen.to_glib_none().0,
        ))
    }
}

//#[doc(alias = "gdk_pango_layout_line_get_clip_region")]
//pub fn pango_layout_line_get_clip_region(line: &pango::LayoutLine, x_origin: i32, y_origin: i32, index_ranges: &[i32], n_ranges: i32) -> Option<cairo::Region> {
//    unsafe { TODO: call ffi:gdk_pango_layout_line_get_clip_region() }
//}

/// Transfers image data from a [`cairo::Surface`][crate::cairo::Surface] and converts it to an RGB(A)
/// representation inside a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf]. This allows you to efficiently read
/// individual pixels from cairo surfaces. For `GdkWindows`, use
/// `gdk_pixbuf_get_from_window()` instead.
///
/// This function will create an RGB pixbuf with 8 bits per channel.
/// The pixbuf will contain an alpha channel if the `surface` contains one.
/// ## `surface`
/// surface to copy from
/// ## `src_x`
/// Source X coordinate within `surface`
/// ## `src_y`
/// Source Y coordinate within `surface`
/// ## `width`
/// Width in pixels of region to get
/// ## `height`
/// Height in pixels of region to get
///
/// # Returns
///
/// A newly-created pixbuf with a
///  reference count of 1, or [`None`] on error
#[doc(alias = "gdk_pixbuf_get_from_surface")]
pub fn pixbuf_get_from_surface(
    surface: &cairo::Surface,
    src_x: i32,
    src_y: i32,
    width: i32,
    height: i32,
) -> Option<gdk_pixbuf::Pixbuf> {
    assert_initialized_main_thread!();
    unsafe {
        from_glib_full(ffi::gdk_pixbuf_get_from_surface(
            mut_override(surface.to_glib_none().0),
            src_x,
            src_y,
            width,
            height,
        ))
    }
}

/// Deletes a property from a window.
/// ## `window`
/// a [`Window`][crate::Window]
/// ## `property`
/// the property to delete
#[doc(alias = "gdk_property_delete")]
pub fn property_delete(window: &Window, property: &Atom) {
    skip_assert_initialized!();
    unsafe {
        ffi::gdk_property_delete(window.to_glib_none().0, property.to_glib_none().0);
    }
}

/// Retrieves a portion of the contents of a property. If the
/// property does not exist, then the function returns [`false`],
/// and `GDK_NONE` will be stored in `actual_property_type`.
///
/// The XGetWindowProperty() function that [`property_get()`][crate::property_get()]
/// uses has a very confusing and complicated set of semantics.
/// Unfortunately, [`property_get()`][crate::property_get()] makes the situation
/// worse instead of better (the semantics should be considered
/// undefined), and also prints warnings to stderr in cases where it
/// should return a useful error to the program. You are advised to use
/// XGetWindowProperty() directly until a replacement function for
/// [`property_get()`][crate::property_get()] is provided.
/// ## `window`
/// a [`Window`][crate::Window]
/// ## `property`
/// the property to retrieve
/// ## `type_`
/// the desired property type, or `GDK_NONE`, if any type of data
///  is acceptable. If this does not match the actual
///  type, then `actual_format` and `actual_length` will
///  be filled in, a warning will be printed to stderr
///  and no data will be returned.
/// ## `offset`
/// the offset into the property at which to begin
///  retrieving data, in 4 byte units.
/// ## `length`
/// the length of the data to retrieve in bytes. Data is
///  considered to be retrieved in 4 byte chunks, so `length`
///  will be rounded up to the next highest 4 byte boundary
///  (so be careful not to pass a value that might overflow
///  when rounded up).
/// ## `pdelete`
/// if [`true`], delete the property after retrieving the
///  data.
///
/// # Returns
///
/// [`true`] if data was successfully received and stored
///  in `data`, otherwise [`false`].
///
/// ## `actual_property_type`
/// location to store the
///  actual type of the property.
///
/// ## `actual_format`
/// location to store the actual return format of the
///  data; either 8, 16 or 32 bits.
///
/// ## `data`
/// location
///  to store a pointer to the data. The retrieved data should be
///  freed with `g_free()` when you are finished using it.
#[doc(alias = "gdk_property_get")]
pub fn property_get(
    window: &Window,
    property: &Atom,
    type_: &Atom,
    offset: libc::c_ulong,
    length: libc::c_ulong,
    pdelete: i32,
) -> Option<(Atom, i32, Vec<u8>)> {
    skip_assert_initialized!();
    unsafe {
        let mut actual_property_type = Atom::uninitialized();
        let mut actual_format = mem::MaybeUninit::uninit();
        let mut actual_length = mem::MaybeUninit::uninit();
        let mut data = ptr::null_mut();
        let ret = from_glib(ffi::gdk_property_get(
            window.to_glib_none().0,
            property.to_glib_none().0,
            type_.to_glib_none().0,
            offset,
            length,
            pdelete,
            actual_property_type.to_glib_none_mut().0,
            actual_format.as_mut_ptr(),
            actual_length.as_mut_ptr(),
            &mut data,
        ));
        if ret {
            Some((
                actual_property_type,
                actual_format.assume_init(),
                FromGlibContainer::from_glib_full_num(data, actual_length.assume_init() as _),
            ))
        } else {
            None
        }
    }
}

/// Retrieves the contents of a selection in a given
/// form.
/// ## `requestor`
/// a [`Window`][crate::Window].
/// ## `selection`
/// an atom identifying the selection to get the
///  contents of.
/// ## `target`
/// the form in which to retrieve the selection.
/// ## `time_`
/// the timestamp to use when retrieving the
///  selection. The selection owner may refuse the
///  request if it did not own the selection at
///  the time indicated by the timestamp.
#[doc(alias = "gdk_selection_convert")]
pub fn selection_convert(requestor: &Window, selection: &Atom, target: &Atom, time_: u32) {
    skip_assert_initialized!();
    unsafe {
        ffi::gdk_selection_convert(
            requestor.to_glib_none().0,
            selection.to_glib_none().0,
            target.to_glib_none().0,
            time_,
        );
    }
}

/// Determines the owner of the given selection.
/// ## `selection`
/// an atom indentifying a selection.
///
/// # Returns
///
/// if there is a selection owner
///  for this window, and it is a window known to the current process,
///  the [`Window`][crate::Window] that owns the selection, otherwise [`None`]. Note
///  that the return value may be owned by a different process if a
///  foreign window was previously created for that window, but a new
///  foreign window will never be created by this call.
#[doc(alias = "gdk_selection_owner_get")]
pub fn selection_owner_get(selection: &Atom) -> Option<Window> {
    assert_initialized_main_thread!();
    unsafe { from_glib_none(ffi::gdk_selection_owner_get(selection.to_glib_none().0)) }
}

/// Determine the owner of the given selection.
///
/// Note that the return value may be owned by a different
/// process if a foreign window was previously created for that
/// window, but a new foreign window will never be created by this call.
/// ## `display`
/// a [`Display`][crate::Display]
/// ## `selection`
/// an atom indentifying a selection
///
/// # Returns
///
/// if there is a selection owner
///  for this window, and it is a window known to the current
///  process, the [`Window`][crate::Window] that owns the selection, otherwise
///  [`None`].
#[doc(alias = "gdk_selection_owner_get_for_display")]
pub fn selection_owner_get_for_display(display: &Display, selection: &Atom) -> Option<Window> {
    skip_assert_initialized!();
    unsafe {
        from_glib_none(ffi::gdk_selection_owner_get_for_display(
            display.to_glib_none().0,
            selection.to_glib_none().0,
        ))
    }
}

/// Sets the owner of the given selection.
/// ## `owner`
/// a [`Window`][crate::Window] or [`None`] to indicate that the
///  the owner for the given should be unset.
/// ## `selection`
/// an atom identifying a selection.
/// ## `time_`
/// timestamp to use when setting the selection.
///  If this is older than the timestamp given last
///  time the owner was set for the given selection, the
///  request will be ignored.
/// ## `send_event`
/// if [`true`], and the new owner is different
///  from the current owner, the current owner
///  will be sent a SelectionClear event.
///
/// # Returns
///
/// [`true`] if the selection owner was successfully
///  changed to `owner`, otherwise [`false`].
#[doc(alias = "gdk_selection_owner_set")]
pub fn selection_owner_set(
    owner: Option<&Window>,
    selection: &Atom,
    time_: u32,
    send_event: bool,
) -> bool {
    assert_initialized_main_thread!();
    unsafe {
        from_glib(ffi::gdk_selection_owner_set(
            owner.to_glib_none().0,
            selection.to_glib_none().0,
            time_,
            send_event.into_glib(),
        ))
    }
}

/// Sets the [`Window`][crate::Window] `owner` as the current owner of the selection `selection`.
/// ## `display`
/// the [`Display`][crate::Display]
/// ## `owner`
/// a [`Window`][crate::Window] or [`None`] to indicate that the owner for
///  the given should be unset
/// ## `selection`
/// an atom identifying a selection
/// ## `time_`
/// timestamp to use when setting the selection
///  If this is older than the timestamp given last time the owner was
///  set for the given selection, the request will be ignored
/// ## `send_event`
/// if [`true`], and the new owner is different from the current
///  owner, the current owner will be sent a SelectionClear event
///
/// # Returns
///
/// [`true`] if the selection owner was successfully changed to owner,
///  otherwise [`false`].
#[doc(alias = "gdk_selection_owner_set_for_display")]
pub fn selection_owner_set_for_display(
    display: &Display,
    owner: Option<&Window>,
    selection: &Atom,
    time_: u32,
    send_event: bool,
) -> bool {
    skip_assert_initialized!();
    unsafe {
        from_glib(ffi::gdk_selection_owner_set_for_display(
            display.to_glib_none().0,
            owner.to_glib_none().0,
            selection.to_glib_none().0,
            time_,
            send_event.into_glib(),
        ))
    }
}

/// Sends a response to SelectionRequest event.
/// ## `requestor`
/// window to which to deliver response.
/// ## `selection`
/// selection that was requested.
/// ## `target`
/// target that was selected.
/// ## `property`
/// property in which the selection owner stored the
///  data, or `GDK_NONE` to indicate that the request
///  was rejected.
/// ## `time_`
/// timestamp.
#[doc(alias = "gdk_selection_send_notify")]
pub fn selection_send_notify(
    requestor: &Window,
    selection: &Atom,
    target: &Atom,
    property: &Atom,
    time_: u32,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gdk_selection_send_notify(
            requestor.to_glib_none().0,
            selection.to_glib_none().0,
            target.to_glib_none().0,
            property.to_glib_none().0,
            time_,
        );
    }
}

/// Send a response to SelectionRequest event.
/// ## `display`
/// the [`Display`][crate::Display] where `requestor` is realized
/// ## `requestor`
/// window to which to deliver response
/// ## `selection`
/// selection that was requested
/// ## `target`
/// target that was selected
/// ## `property`
/// property in which the selection owner stored the data,
///  or `GDK_NONE` to indicate that the request was rejected
/// ## `time_`
/// timestamp
#[doc(alias = "gdk_selection_send_notify_for_display")]
pub fn selection_send_notify_for_display(
    display: &Display,
    requestor: &Window,
    selection: &Atom,
    target: &Atom,
    property: &Atom,
    time_: u32,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gdk_selection_send_notify_for_display(
            display.to_glib_none().0,
            requestor.to_glib_none().0,
            selection.to_glib_none().0,
            target.to_glib_none().0,
            property.to_glib_none().0,
            time_,
        );
    }
}

/// Sets a list of backends that GDK should try to use.
///
/// This can be be useful if your application does not
/// work with certain GDK backends.
///
/// By default, GDK tries all included backends.
///
/// For example,
///
///
/// **⚠️ The following code is in C ⚠️**
///
/// ```C
/// gdk_set_allowed_backends ("wayland,quartz,*");
/// ```
/// instructs GDK to try the Wayland backend first,
/// followed by the Quartz backend, and then all
/// others.
///
/// If the `GDK_BACKEND` environment variable
/// is set, it determines what backends are tried in what
/// order, while still respecting the set of allowed backends
/// that are specified by this function.
///
/// The possible backend names are x11, win32, quartz,
/// broadway, wayland. You can also include a * in the
/// list to try all remaining backends.
///
/// This call must happen prior to [`Display::open()`][crate::Display::open()],
/// `gtk_init()`, `gtk_init_with_args()` or `gtk_init_check()`
/// in order to take effect.
/// ## `backends`
/// a comma-separated list of backends
#[doc(alias = "gdk_set_allowed_backends")]
pub fn set_allowed_backends(backends: &str) {
    skip_assert_initialized!();
    unsafe {
        ffi::gdk_set_allowed_backends(backends.to_glib_none().0);
    }
}

/// Set the double click time for the default display. See
/// [`Display::set_double_click_time()`][crate::Display::set_double_click_time()].
/// See also [`Display::set_double_click_distance()`][crate::Display::set_double_click_distance()].
/// Applications should not set this, it is a
/// global user-configured setting.
/// ## `msec`
/// double click time in milliseconds (thousandths of a second)
#[doc(alias = "gdk_set_double_click_time")]
pub fn set_double_click_time(msec: u32) {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gdk_set_double_click_time(msec);
    }
}

/// Sets the program class. The X11 backend uses the program class to set
/// the class name part of the `WM_CLASS` property on
/// toplevel windows; see the ICCCM.
///
/// The program class can still be overridden with the --class command
/// line option.
/// ## `program_class`
/// a string.
#[doc(alias = "gdk_set_program_class")]
pub fn set_program_class(program_class: &str) {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gdk_set_program_class(program_class.to_glib_none().0);
    }
}

/// Sets whether a trace of received events is output.
/// Note that GTK+ must be compiled with debugging (that is,
/// configured using the `--enable-debug` option)
/// to use this option.
/// ## `show_events`
/// [`true`] to output event debugging information.
#[doc(alias = "gdk_set_show_events")]
pub fn set_show_events(show_events: bool) {
    assert_initialized_main_thread!();
    unsafe {
        ffi::gdk_set_show_events(show_events.into_glib());
    }
}

#[doc(alias = "gdk_synthesize_window_state")]
pub fn synthesize_window_state(window: &Window, unset_flags: WindowState, set_flags: WindowState) {
    skip_assert_initialized!();
    unsafe {
        ffi::gdk_synthesize_window_state(
            window.to_glib_none().0,
            unset_flags.into_glib(),
            set_flags.into_glib(),
        );
    }
}

/// Retrieves a pixel from `window` to force the windowing
/// system to carry out any pending rendering commands.
///
/// This function is intended to be used to synchronize with rendering
/// pipelines, to benchmark windowing system rendering operations.
/// ## `window`
/// a mapped [`Window`][crate::Window]
#[doc(alias = "gdk_test_render_sync")]
pub fn test_render_sync(window: &Window) {
    skip_assert_initialized!();
    unsafe {
        ffi::gdk_test_render_sync(window.to_glib_none().0);
    }
}

/// This function is intended to be used in GTK+ test programs.
/// It will warp the mouse pointer to the given (`x`,`y`) coordinates
/// within `window` and simulate a button press or release event.
/// Because the mouse pointer needs to be warped to the target
/// location, use of this function outside of test programs that
/// run in their own virtual windowing system (e.g. Xvfb) is not
/// recommended.
///
/// Also, [`test_simulate_button()`][crate::test_simulate_button()] is a fairly low level function,
/// for most testing purposes, `gtk_test_widget_click()` is the right
/// function to call which will generate a button press event followed
/// by its accompanying button release event.
/// ## `window`
/// a [`Window`][crate::Window] to simulate a button event for
/// ## `x`
/// x coordinate within `window` for the button event
/// ## `y`
/// y coordinate within `window` for the button event
/// ## `button`
/// Number of the pointer button for the event, usually 1, 2 or 3
/// ## `modifiers`
/// Keyboard modifiers the event is setup with
/// ## `button_pressrelease`
/// either [`EventType::ButtonPress`][crate::EventType::ButtonPress] or [`EventType::ButtonRelease`][crate::EventType::ButtonRelease]
///
/// # Returns
///
/// whether all actions necessary for a button event simulation
///  were carried out successfully
#[doc(alias = "gdk_test_simulate_button")]
pub fn test_simulate_button(
    window: &Window,
    x: i32,
    y: i32,
    button: u32,
    modifiers: ModifierType,
    button_pressrelease: EventType,
) -> bool {
    skip_assert_initialized!();
    unsafe {
        from_glib(ffi::gdk_test_simulate_button(
            window.to_glib_none().0,
            x,
            y,
            button,
            modifiers.into_glib(),
            button_pressrelease.into_glib(),
        ))
    }
}

/// This function is intended to be used in GTK+ test programs.
/// If (`x`,`y`) are > (-1,-1), it will warp the mouse pointer to
/// the given (`x`,`y`) coordinates within `window` and simulate a
/// key press or release event.
///
/// When the mouse pointer is warped to the target location, use
/// of this function outside of test programs that run in their
/// own virtual windowing system (e.g. Xvfb) is not recommended.
/// If (`x`,`y`) are passed as (-1,-1), the mouse pointer will not
/// be warped and `window` origin will be used as mouse pointer
/// location for the event.
///
/// Also, [`test_simulate_key()`][crate::test_simulate_key()] is a fairly low level function,
/// for most testing purposes, `gtk_test_widget_send_key()` is the
/// right function to call which will generate a key press event
/// followed by its accompanying key release event.
/// ## `window`
/// a [`Window`][crate::Window] to simulate a key event for
/// ## `x`
/// x coordinate within `window` for the key event
/// ## `y`
/// y coordinate within `window` for the key event
/// ## `keyval`
/// A GDK keyboard value
/// ## `modifiers`
/// Keyboard modifiers the event is setup with
/// ## `key_pressrelease`
/// either [`EventType::KeyPress`][crate::EventType::KeyPress] or [`EventType::KeyRelease`][crate::EventType::KeyRelease]
///
/// # Returns
///
/// whether all actions necessary for a key event simulation
///  were carried out successfully
#[doc(alias = "gdk_test_simulate_key")]
pub fn test_simulate_key(
    window: &Window,
    x: i32,
    y: i32,
    keyval: u32,
    modifiers: ModifierType,
    key_pressrelease: EventType,
) -> bool {
    skip_assert_initialized!();
    unsafe {
        from_glib(ffi::gdk_test_simulate_key(
            window.to_glib_none().0,
            x,
            y,
            keyval,
            modifiers.into_glib(),
            key_pressrelease.into_glib(),
        ))
    }
}

/// Converts a text property in the given encoding to
/// a list of UTF-8 strings.
/// ## `display`
/// a [`Display`][crate::Display]
/// ## `encoding`
/// an atom representing the encoding of the text
/// ## `format`
/// the format of the property
/// ## `text`
/// the text to convert
///
/// # Returns
///
/// the number of strings in the resulting list
///
/// ## `list`
/// location to store the list
///  of strings or [`None`]. The list should be freed with
///  `g_strfreev()`.
#[doc(alias = "gdk_text_property_to_utf8_list_for_display")]
pub fn text_property_to_utf8_list_for_display(
    display: &Display,
    encoding: &Atom,
    format: i32,
    text: &[u8],
) -> (i32, Vec<glib::GString>) {
    skip_assert_initialized!();
    let length = text.len() as _;
    unsafe {
        let mut list = ptr::null_mut();
        let ret = ffi::gdk_text_property_to_utf8_list_for_display(
            display.to_glib_none().0,
            encoding.to_glib_none().0,
            format,
            text.to_glib_none().0,
            length,
            &mut list,
        );
        (ret, FromGlibPtrContainer::from_glib_full(list))
    }
}

/// Converts an UTF-8 string into the best possible representation
/// as a STRING. The representation of characters not in STRING
/// is not specified; it may be as pseudo-escape sequences
/// \x{ABCD}, or it may be in some other form of approximation.
/// ## `str`
/// a UTF-8 string
///
/// # Returns
///
/// the newly-allocated string, or [`None`] if the
///  conversion failed. (It should not fail for any properly
///  formed UTF-8 string unless system limits like memory or
///  file descriptors are exceeded.)
#[doc(alias = "gdk_utf8_to_string_target")]
pub fn utf8_to_string_target(str: &str) -> Option<glib::GString> {
    assert_initialized_main_thread!();
    unsafe { from_glib_full(ffi::gdk_utf8_to_string_target(str.to_glib_none().0)) }
}