// 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::SelectionData;
use crate::TextBuffer;
use glib::object::IsA;
use glib::translate::*;
use std::boxed::Box as Box_;
use std::fmt;
use std::mem;
use std::ptr;

glib::wrapper! {
    /// The [`Clipboard`][crate::Clipboard] object represents a clipboard of data shared
    /// between different processes or between different widgets in
    /// the same process. Each clipboard is identified by a name encoded as a
    /// [`gdk::Atom`][crate::gdk::Atom]. (Conversion to and from strings can be done with
    /// [`gdk::Atom::intern()`][crate::gdk::Atom::intern()] and [`gdk::Atom::name()`][crate::gdk::Atom::name()].) The default clipboard
    /// corresponds to the “CLIPBOARD” atom; another commonly used clipboard
    /// is the “PRIMARY” clipboard, which, in X, traditionally contains
    /// the currently selected text.
    ///
    /// To support having a number of different formats on the clipboard
    /// at the same time, the clipboard mechanism allows providing
    /// callbacks instead of the actual data. When you set the contents
    /// of the clipboard, you can either supply the data directly (via
    /// functions like [`set_text()`][Self::set_text()]), or you can supply a
    /// callback to be called at a later time when the data is needed (via
    /// `gtk_clipboard_set_with_data()` or `gtk_clipboard_set_with_owner()`.)
    /// Providing a callback also avoids having to make copies of the data
    /// when it is not needed.
    ///
    /// `gtk_clipboard_set_with_data()` and `gtk_clipboard_set_with_owner()`
    /// are quite similar; the choice between the two depends mostly on
    /// which is more convenient in a particular situation.
    /// The former is most useful when you want to have a blob of data
    /// with callbacks to convert it into the various data types that you
    /// advertise. When the `clear_func` you provided is called, you
    /// simply free the data blob. The latter is more useful when the
    /// contents of clipboard reflect the internal state of a [`glib::Object`][crate::glib::Object]
    /// (As an example, for the PRIMARY clipboard, when an entry widget
    /// provides the clipboard’s contents the contents are simply the
    /// text within the selected region.) If the contents change, the
    /// entry widget can call `gtk_clipboard_set_with_owner()` to update
    /// the timestamp for clipboard ownership, without having to worry
    /// about `clear_func` being called.
    ///
    /// Requesting the data from the clipboard is essentially
    /// asynchronous. If the contents of the clipboard are provided within
    /// the same process, then a direct function call will be made to
    /// retrieve the data, but if they are provided by another process,
    /// then the data needs to be retrieved from the other process, which
    /// may take some time. To avoid blocking the user interface, the call
    /// to request the selection, [`request_contents()`][Self::request_contents()] takes a
    /// callback that will be called when the contents are received (or
    /// when the request fails.) If you don’t want to deal with providing
    /// a separate callback, you can also use [`wait_for_contents()`][Self::wait_for_contents()].
    /// What this does is run the GLib main loop recursively waiting for
    /// the contents. This can simplify the code flow, but you still have
    /// to be aware that other callbacks in your program can be called
    /// while this recursive mainloop is running.
    ///
    /// Along with the functions to get the clipboard contents as an
    /// arbitrary data chunk, there are also functions to retrieve
    /// it as text, [`request_text()`][Self::request_text()] and
    /// [`wait_for_text()`][Self::wait_for_text()]. These functions take care of
    /// determining which formats are advertised by the clipboard
    /// provider, asking for the clipboard in the best available format
    /// and converting the results into the UTF-8 encoding. (The standard
    /// form for representing strings in GTK+.)
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`]
    #[doc(alias = "GtkClipboard")]
    pub struct Clipboard(Object<ffi::GtkClipboard>);

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

impl Clipboard {
    /// Clears the contents of the clipboard. Generally this should only
    /// be called between the time you call `gtk_clipboard_set_with_owner()`
    /// or `gtk_clipboard_set_with_data()`,
    /// and when the `clear_func` you supplied is called. Otherwise, the
    /// clipboard may be owned by someone else.
    #[doc(alias = "gtk_clipboard_clear")]
    pub fn clear(&self) {
        unsafe {
            ffi::gtk_clipboard_clear(self.to_glib_none().0);
        }
    }

    /// Gets the [`gdk::Display`][crate::gdk::Display] associated with `self`
    ///
    /// # Returns
    ///
    /// the [`gdk::Display`][crate::gdk::Display] associated with `self`
    #[doc(alias = "gtk_clipboard_get_display")]
    #[doc(alias = "get_display")]
    pub fn display(&self) -> Option<gdk::Display> {
        unsafe { from_glib_none(ffi::gtk_clipboard_get_display(self.to_glib_none().0)) }
    }

    /// If the clipboard contents callbacks were set with
    /// `gtk_clipboard_set_with_owner()`, and the `gtk_clipboard_set_with_data()` or
    /// [`clear()`][Self::clear()] has not subsequently called, returns the owner set
    /// by `gtk_clipboard_set_with_owner()`.
    ///
    /// # Returns
    ///
    /// the owner of the clipboard, if any;
    ///  otherwise [`None`].
    #[doc(alias = "gtk_clipboard_get_owner")]
    #[doc(alias = "get_owner")]
    pub fn owner(&self) -> Option<glib::Object> {
        unsafe { from_glib_none(ffi::gtk_clipboard_get_owner(self.to_glib_none().0)) }
    }

    /// Gets the selection that this clipboard is for.
    ///
    /// # Returns
    ///
    /// the selection
    #[doc(alias = "gtk_clipboard_get_selection")]
    #[doc(alias = "get_selection")]
    pub fn selection(&self) -> Option<gdk::Atom> {
        unsafe { from_glib_none(ffi::gtk_clipboard_get_selection(self.to_glib_none().0)) }
    }

    /// Requests the contents of clipboard as the given target.
    /// When the results of the result are later received the supplied callback
    /// will be called.
    /// ## `target`
    /// an atom representing the form into which the clipboard
    ///  owner should convert the selection.
    /// ## `callback`
    /// A function to call when the results are received
    ///  (or the retrieval fails). If the retrieval fails the length field of
    ///  `selection_data` will be negative.
    #[doc(alias = "gtk_clipboard_request_contents")]
    pub fn request_contents<P: FnOnce(&Clipboard, &SelectionData) + 'static>(
        &self,
        target: &gdk::Atom,
        callback: P,
    ) {
        let callback_data: Box_<P> = Box_::new(callback);
        unsafe extern "C" fn callback_func<P: FnOnce(&Clipboard, &SelectionData) + 'static>(
            clipboard: *mut ffi::GtkClipboard,
            selection_data: *mut ffi::GtkSelectionData,
            data: glib::ffi::gpointer,
        ) {
            let clipboard = from_glib_borrow(clipboard);
            let selection_data = from_glib_borrow(selection_data);
            let callback: Box_<P> = Box_::from_raw(data as *mut _);
            (*callback)(&clipboard, &selection_data);
        }
        let callback = Some(callback_func::<P> as _);
        let super_callback0: Box_<P> = callback_data;
        unsafe {
            ffi::gtk_clipboard_request_contents(
                self.to_glib_none().0,
                target.to_glib_none().0,
                callback,
                Box_::into_raw(super_callback0) as *mut _,
            );
        }
    }

    /// Requests the contents of the clipboard as image. When the image is
    /// later received, it will be converted to a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf], and
    /// `callback` will be called.
    ///
    /// The `pixbuf` parameter to `callback` will contain the resulting
    /// [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf] if the request succeeded, or [`None`] if it failed. This
    /// could happen for various reasons, in particular if the clipboard
    /// was empty or if the contents of the clipboard could not be
    /// converted into an image.
    /// ## `callback`
    /// a function to call when the image is received,
    ///  or the retrieval fails. (It will always be called one way or the other.)
    #[doc(alias = "gtk_clipboard_request_image")]
    pub fn request_image<P: FnOnce(&Clipboard, Option<&gdk_pixbuf::Pixbuf>) + 'static>(
        &self,
        callback: P,
    ) {
        let callback_data: Box_<P> = Box_::new(callback);
        unsafe extern "C" fn callback_func<
            P: FnOnce(&Clipboard, Option<&gdk_pixbuf::Pixbuf>) + 'static,
        >(
            clipboard: *mut ffi::GtkClipboard,
            pixbuf: *mut gdk_pixbuf::ffi::GdkPixbuf,
            data: glib::ffi::gpointer,
        ) {
            let clipboard = from_glib_borrow(clipboard);
            let pixbuf: Borrowed<Option<gdk_pixbuf::Pixbuf>> = from_glib_borrow(pixbuf);
            let callback: Box_<P> = Box_::from_raw(data as *mut _);
            (*callback)(&clipboard, pixbuf.as_ref().as_ref());
        }
        let callback = Some(callback_func::<P> as _);
        let super_callback0: Box_<P> = callback_data;
        unsafe {
            ffi::gtk_clipboard_request_image(
                self.to_glib_none().0,
                callback,
                Box_::into_raw(super_callback0) as *mut _,
            );
        }
    }

    /// Requests the contents of the clipboard as rich text. When the rich
    /// text is later received, `callback` will be called.
    ///
    /// The `text` parameter to `callback` will contain the resulting rich
    /// text if the request succeeded, or [`None`] if it failed. The `length`
    /// parameter will contain `text`’s length. This function can fail for
    /// various reasons, in particular if the clipboard was empty or if the
    /// contents of the clipboard could not be converted into rich text form.
    /// ## `buffer`
    /// a [`TextBuffer`][crate::TextBuffer]
    /// ## `callback`
    /// a function to call when the text is received,
    ///  or the retrieval fails. (It will always be called one way or the other.)
    #[doc(alias = "gtk_clipboard_request_rich_text")]
    pub fn request_rich_text<P: FnOnce(&Clipboard, &gdk::Atom, Option<&str>, usize) + 'static>(
        &self,
        buffer: &impl IsA<TextBuffer>,
        callback: P,
    ) {
        let callback_data: Box_<P> = Box_::new(callback);
        unsafe extern "C" fn callback_func<
            P: FnOnce(&Clipboard, &gdk::Atom, Option<&str>, usize) + 'static,
        >(
            clipboard: *mut ffi::GtkClipboard,
            format: gdk::ffi::GdkAtom,
            text: *const libc::c_char,
            length: libc::size_t,
            data: glib::ffi::gpointer,
        ) {
            let clipboard = from_glib_borrow(clipboard);
            let format = from_glib_borrow(format);
            let text: Borrowed<Option<glib::GString>> = from_glib_borrow(text);
            let callback: Box_<P> = Box_::from_raw(data as *mut _);
            (*callback)(
                &clipboard,
                &format,
                (*text).as_ref().map(|s| s.as_str()),
                length,
            );
        }
        let callback = Some(callback_func::<P> as _);
        let super_callback0: Box_<P> = callback_data;
        unsafe {
            ffi::gtk_clipboard_request_rich_text(
                self.to_glib_none().0,
                buffer.as_ref().to_glib_none().0,
                callback,
                Box_::into_raw(super_callback0) as *mut _,
            );
        }
    }

    /// Requests the contents of the clipboard as text. When the text is
    /// later received, it will be converted to UTF-8 if necessary, and
    /// `callback` will be called.
    ///
    /// The `text` parameter to `callback` will contain the resulting text if
    /// the request succeeded, or [`None`] if it failed. This could happen for
    /// various reasons, in particular if the clipboard was empty or if the
    /// contents of the clipboard could not be converted into text form.
    /// ## `callback`
    /// a function to call when the text is received,
    ///  or the retrieval fails. (It will always be called one way or the other.)
    #[doc(alias = "gtk_clipboard_request_text")]
    pub fn request_text<P: FnOnce(&Clipboard, Option<&str>) + 'static>(&self, callback: P) {
        let callback_data: Box_<P> = Box_::new(callback);
        unsafe extern "C" fn callback_func<P: FnOnce(&Clipboard, Option<&str>) + 'static>(
            clipboard: *mut ffi::GtkClipboard,
            text: *const libc::c_char,
            data: glib::ffi::gpointer,
        ) {
            let clipboard = from_glib_borrow(clipboard);
            let text: Borrowed<Option<glib::GString>> = from_glib_borrow(text);
            let callback: Box_<P> = Box_::from_raw(data as *mut _);
            (*callback)(&clipboard, (*text).as_ref().map(|s| s.as_str()));
        }
        let callback = Some(callback_func::<P> as _);
        let super_callback0: Box_<P> = callback_data;
        unsafe {
            ffi::gtk_clipboard_request_text(
                self.to_glib_none().0,
                callback,
                Box_::into_raw(super_callback0) as *mut _,
            );
        }
    }

    /// Sets the contents of the clipboard to the given [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf].
    /// GTK+ will take responsibility for responding for requests
    /// for the image, and for converting the image into the
    /// requested format.
    /// ## `pixbuf`
    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf]
    #[doc(alias = "gtk_clipboard_set_image")]
    pub fn set_image(&self, pixbuf: &gdk_pixbuf::Pixbuf) {
        unsafe {
            ffi::gtk_clipboard_set_image(self.to_glib_none().0, pixbuf.to_glib_none().0);
        }
    }

    /// Sets the contents of the clipboard to the given UTF-8 string. GTK+ will
    /// make a copy of the text and take responsibility for responding
    /// for requests for the text, and for converting the text into
    /// the requested format.
    /// ## `text`
    /// a UTF-8 string.
    /// ## `len`
    /// length of `text`, in bytes, or -1, in which case
    ///  the length will be determined with `strlen()`.
    #[doc(alias = "gtk_clipboard_set_text")]
    pub fn set_text(&self, text: &str) {
        let len = text.len() as i32;
        unsafe {
            ffi::gtk_clipboard_set_text(self.to_glib_none().0, text.to_glib_none().0, len);
        }
    }

    /// Stores the current clipboard data somewhere so that it will stay
    /// around after the application has quit.
    #[doc(alias = "gtk_clipboard_store")]
    pub fn store(&self) {
        unsafe {
            ffi::gtk_clipboard_store(self.to_glib_none().0);
        }
    }

    /// Requests the contents of the clipboard using the given target.
    /// This function waits for the data to be received using the main
    /// loop, so events, timeouts, etc, may be dispatched during the wait.
    /// ## `target`
    /// an atom representing the form into which the clipboard
    ///  owner should convert the selection.
    ///
    /// # Returns
    ///
    /// a newly-allocated [`SelectionData`][crate::SelectionData] object or [`None`]
    ///  if retrieving the given target failed. If non-[`None`],
    ///  this value must be freed with `gtk_selection_data_free()`
    ///  when you are finished with it.
    #[doc(alias = "gtk_clipboard_wait_for_contents")]
    pub fn wait_for_contents(&self, target: &gdk::Atom) -> Option<SelectionData> {
        unsafe {
            from_glib_full(ffi::gtk_clipboard_wait_for_contents(
                self.to_glib_none().0,
                target.to_glib_none().0,
            ))
        }
    }

    /// Requests the contents of the clipboard as image and converts
    /// the result to a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf]. This function waits for
    /// the data to be received using the main loop, so events,
    /// timeouts, etc, may be dispatched during the wait.
    ///
    /// # Returns
    ///
    /// a newly-allocated [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf]
    ///  object which must be disposed with `g_object_unref()`, or
    ///  [`None`] if retrieving the selection data failed. (This could
    ///  happen for various reasons, in particular if the clipboard
    ///  was empty or if the contents of the clipboard could not be
    ///  converted into an image.)
    #[doc(alias = "gtk_clipboard_wait_for_image")]
    pub fn wait_for_image(&self) -> Option<gdk_pixbuf::Pixbuf> {
        unsafe { from_glib_full(ffi::gtk_clipboard_wait_for_image(self.to_glib_none().0)) }
    }

    /// Requests the contents of the clipboard as rich text. This function
    /// waits for the data to be received using the main loop, so events,
    /// timeouts, etc, may be dispatched during the wait.
    /// ## `buffer`
    /// a [`TextBuffer`][crate::TextBuffer]
    ///
    /// # Returns
    ///
    /// a
    ///  newly-allocated binary block of data which must be
    ///  freed with `g_free()`, or [`None`] if retrieving the
    ///  selection data failed. (This could happen for various
    ///  reasons, in particular if the clipboard was empty or
    ///  if the contents of the clipboard could not be
    ///  converted into text form.)
    ///
    /// ## `format`
    /// return location for the format of the returned data
    #[doc(alias = "gtk_clipboard_wait_for_rich_text")]
    pub fn wait_for_rich_text(&self, buffer: &impl IsA<TextBuffer>) -> (Vec<u8>, gdk::Atom) {
        unsafe {
            let mut format = gdk::Atom::uninitialized();
            let mut length = mem::MaybeUninit::uninit();
            let ret = FromGlibContainer::from_glib_full_num(
                ffi::gtk_clipboard_wait_for_rich_text(
                    self.to_glib_none().0,
                    buffer.as_ref().to_glib_none().0,
                    format.to_glib_none_mut().0,
                    length.as_mut_ptr(),
                ),
                length.assume_init() as usize,
            );
            (ret, format)
        }
    }

    /// Returns a list of targets that are present on the clipboard, or [`None`]
    /// if there aren’t any targets available. The returned list must be
    /// freed with `g_free()`.
    /// This function waits for the data to be received using the main
    /// loop, so events, timeouts, etc, may be dispatched during the wait.
    ///
    /// # Returns
    ///
    /// [`true`] if any targets are present on the clipboard,
    ///  otherwise [`false`].
    ///
    /// ## `targets`
    /// location
    ///  to store an array of targets. The result stored here must
    ///  be freed with `g_free()`.
    #[doc(alias = "gtk_clipboard_wait_for_targets")]
    pub fn wait_for_targets(&self) -> Option<Vec<gdk::Atom>> {
        unsafe {
            let mut targets = ptr::null_mut();
            let mut n_targets = mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gtk_clipboard_wait_for_targets(
                self.to_glib_none().0,
                &mut targets,
                n_targets.as_mut_ptr(),
            ));
            if ret {
                Some(FromGlibContainer::from_glib_container_num(
                    targets,
                    n_targets.assume_init() as usize,
                ))
            } else {
                None
            }
        }
    }

    /// Requests the contents of the clipboard as text and converts
    /// the result to UTF-8 if necessary. This function waits for
    /// the data to be received using the main loop, so events,
    /// timeouts, etc, may be dispatched during the wait.
    ///
    /// # Returns
    ///
    /// a newly-allocated UTF-8 string which must
    ///  be freed with `g_free()`, or [`None`] if retrieving
    ///  the selection data failed. (This could happen
    ///  for various reasons, in particular if the
    ///  clipboard was empty or if the contents of the
    ///  clipboard could not be converted into text form.)
    #[doc(alias = "gtk_clipboard_wait_for_text")]
    pub fn wait_for_text(&self) -> Option<glib::GString> {
        unsafe { from_glib_full(ffi::gtk_clipboard_wait_for_text(self.to_glib_none().0)) }
    }

    /// Requests the contents of the clipboard as URIs. This function waits
    /// for the data to be received using the main loop, so events,
    /// timeouts, etc, may be dispatched during the wait.
    ///
    /// # Returns
    ///
    ///
    ///  a newly-allocated [`None`]-terminated array of strings which must
    ///  be freed with `g_strfreev()`, or [`None`] if retrieving the
    ///  selection data failed. (This could happen for various reasons,
    ///  in particular if the clipboard was empty or if the contents of
    ///  the clipboard could not be converted into URI form.)
    #[doc(alias = "gtk_clipboard_wait_for_uris")]
    pub fn wait_for_uris(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::gtk_clipboard_wait_for_uris(
                self.to_glib_none().0,
            ))
        }
    }

    /// Test to see if there is an image available to be pasted
    /// This is done by requesting the TARGETS atom and checking
    /// if it contains any of the supported image targets. This function
    /// waits for the data to be received using the main loop, so events,
    /// timeouts, etc, may be dispatched during the wait.
    ///
    /// This function is a little faster than calling
    /// [`wait_for_image()`][Self::wait_for_image()] since it doesn’t need to retrieve
    /// the actual image data.
    ///
    /// # Returns
    ///
    /// [`true`] is there is an image available, [`false`] otherwise.
    #[doc(alias = "gtk_clipboard_wait_is_image_available")]
    pub fn wait_is_image_available(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_clipboard_wait_is_image_available(
                self.to_glib_none().0,
            ))
        }
    }

    /// Test to see if there is rich text available to be pasted
    /// This is done by requesting the TARGETS atom and checking
    /// if it contains any of the supported rich text targets. This function
    /// waits for the data to be received using the main loop, so events,
    /// timeouts, etc, may be dispatched during the wait.
    ///
    /// This function is a little faster than calling
    /// [`wait_for_rich_text()`][Self::wait_for_rich_text()] since it doesn’t need to retrieve
    /// the actual text.
    /// ## `buffer`
    /// a [`TextBuffer`][crate::TextBuffer]
    ///
    /// # Returns
    ///
    /// [`true`] is there is rich text available, [`false`] otherwise.
    #[doc(alias = "gtk_clipboard_wait_is_rich_text_available")]
    pub fn wait_is_rich_text_available(&self, buffer: &impl IsA<TextBuffer>) -> bool {
        unsafe {
            from_glib(ffi::gtk_clipboard_wait_is_rich_text_available(
                self.to_glib_none().0,
                buffer.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Checks if a clipboard supports pasting data of a given type. This
    /// function can be used to determine if a “Paste” menu item should be
    /// insensitive or not.
    ///
    /// If you want to see if there’s text available on the clipboard, use
    /// gtk_clipboard_wait_is_text_available () instead.
    /// ## `target`
    /// A [`gdk::Atom`][crate::gdk::Atom] indicating which target to look for.
    ///
    /// # Returns
    ///
    /// [`true`] if the target is available, [`false`] otherwise.
    #[doc(alias = "gtk_clipboard_wait_is_target_available")]
    pub fn wait_is_target_available(&self, target: &gdk::Atom) -> bool {
        unsafe {
            from_glib(ffi::gtk_clipboard_wait_is_target_available(
                self.to_glib_none().0,
                target.to_glib_none().0,
            ))
        }
    }

    /// Test to see if there is text available to be pasted
    /// This is done by requesting the TARGETS atom and checking
    /// if it contains any of the supported text targets. This function
    /// waits for the data to be received using the main loop, so events,
    /// timeouts, etc, may be dispatched during the wait.
    ///
    /// This function is a little faster than calling
    /// [`wait_for_text()`][Self::wait_for_text()] since it doesn’t need to retrieve
    /// the actual text.
    ///
    /// # Returns
    ///
    /// [`true`] is there is text available, [`false`] otherwise.
    #[doc(alias = "gtk_clipboard_wait_is_text_available")]
    pub fn wait_is_text_available(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_clipboard_wait_is_text_available(
                self.to_glib_none().0,
            ))
        }
    }

    /// Test to see if there is a list of URIs available to be pasted
    /// This is done by requesting the TARGETS atom and checking
    /// if it contains the URI targets. This function
    /// waits for the data to be received using the main loop, so events,
    /// timeouts, etc, may be dispatched during the wait.
    ///
    /// This function is a little faster than calling
    /// [`wait_for_uris()`][Self::wait_for_uris()] since it doesn’t need to retrieve
    /// the actual URI data.
    ///
    /// # Returns
    ///
    /// [`true`] is there is an URI list available, [`false`] otherwise.
    #[doc(alias = "gtk_clipboard_wait_is_uris_available")]
    pub fn wait_is_uris_available(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_clipboard_wait_is_uris_available(
                self.to_glib_none().0,
            ))
        }
    }

    /// Returns the clipboard object for the given selection.
    /// See [`for_display()`][Self::for_display()] for complete details.
    /// ## `selection`
    /// a [`gdk::Atom`][crate::gdk::Atom] which identifies the clipboard to use
    ///
    /// # Returns
    ///
    /// the appropriate clipboard object. If no clipboard
    ///  already exists, a new one will be created. Once a clipboard
    ///  object has been created, it is persistent and, since it is
    ///  owned by GTK+, must not be freed or unreffed.
    #[doc(alias = "gtk_clipboard_get")]
    pub fn get(selection: &gdk::Atom) -> Clipboard {
        assert_initialized_main_thread!();
        unsafe { from_glib_none(ffi::gtk_clipboard_get(selection.to_glib_none().0)) }
    }

    /// Returns the default clipboard object for use with cut/copy/paste menu items
    /// and keyboard shortcuts.
    /// ## `display`
    /// the [`gdk::Display`][crate::gdk::Display] for which the clipboard is to be retrieved.
    ///
    /// # Returns
    ///
    /// the default clipboard object.
    #[doc(alias = "gtk_clipboard_get_default")]
    #[doc(alias = "get_default")]
    pub fn default(display: &gdk::Display) -> Option<Clipboard> {
        assert_initialized_main_thread!();
        unsafe { from_glib_none(ffi::gtk_clipboard_get_default(display.to_glib_none().0)) }
    }

    /// Returns the clipboard object for the given selection.
    /// Cut/copy/paste menu items and keyboard shortcuts should use
    /// the default clipboard, returned by passing `GDK_SELECTION_CLIPBOARD` for `selection`.
    /// (`GDK_NONE` is supported as a synonym for GDK_SELECTION_CLIPBOARD
    /// for backwards compatibility reasons.)
    /// The currently-selected object or text should be provided on the clipboard
    /// identified by `GDK_SELECTION_PRIMARY`. Cut/copy/paste menu items
    /// conceptually copy the contents of the `GDK_SELECTION_PRIMARY` clipboard
    /// to the default clipboard, i.e. they copy the selection to what the
    /// user sees as the clipboard.
    ///
    /// (Passing `GDK_NONE` is the same as using `gdk_atom_intern
    /// ("CLIPBOARD", FALSE)`.
    ///
    /// See the
    /// [FreeDesktop Clipboard Specification](http://www.freedesktop.org/Standards/clipboards-spec)
    /// for a detailed discussion of the “CLIPBOARD” vs. “PRIMARY”
    /// selections under the X window system. On Win32 the
    /// `GDK_SELECTION_PRIMARY` clipboard is essentially ignored.)
    ///
    /// It’s possible to have arbitrary named clipboards; if you do invent
    /// new clipboards, you should prefix the selection name with an
    /// underscore (because the ICCCM requires that nonstandard atoms are
    /// underscore-prefixed), and namespace it as well. For example,
    /// if your application called “Foo” has a special-purpose
    /// clipboard, you might call it “_FOO_SPECIAL_CLIPBOARD”.
    /// ## `display`
    /// the [`gdk::Display`][crate::gdk::Display] for which the clipboard is to be retrieved or created.
    /// ## `selection`
    /// a [`gdk::Atom`][crate::gdk::Atom] which identifies the clipboard to use.
    ///
    /// # Returns
    ///
    /// the appropriate clipboard object. If no
    ///  clipboard already exists, a new one will be created. Once a clipboard
    ///  object has been created, it is persistent and, since it is owned by
    ///  GTK+, must not be freed or unrefd.
    #[doc(alias = "gtk_clipboard_get_for_display")]
    #[doc(alias = "get_for_display")]
    pub fn for_display(display: &gdk::Display, selection: &gdk::Atom) -> Clipboard {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_none(ffi::gtk_clipboard_get_for_display(
                display.to_glib_none().0,
                selection.to_glib_none().0,
            ))
        }
    }

    //#[doc(alias = "owner-change")]
    //pub fn connect_owner_change<Unsupported or ignored types>(&self, f: F) -> SignalHandlerId {
    //    Ignored event: Gdk.EventOwnerChange
    //}
}

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