gtk/auto/

editable.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::ffi;
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// The [`Editable`][crate::Editable] interface is an interface which should be implemented by
    /// text editing widgets, such as [`Entry`][crate::Entry] and [`SpinButton`][crate::SpinButton]. It contains functions
    /// for generically manipulating an editable widget, a large number of action
    /// signals used for key bindings, and several signals that an application can
    /// connect to to modify the behavior of a widget.
    ///
    /// As an example of the latter usage, by connecting
    /// the following handler to [`insert-text`][struct@crate::Editable#insert-text], an application
    /// can convert all entry into a widget into uppercase.
    ///
    /// ## Forcing entry to uppercase.
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    /// #include <ctype.h>;
    ///
    /// void
    /// insert_text_handler (GtkEditable *editable,
    ///                      const gchar *text,
    ///                      gint         length,
    ///                      gint        *position,
    ///                      gpointer     data)
    /// {
    ///   gchar *result = g_utf8_strup (text, length);
    ///
    ///   g_signal_handlers_block_by_func (editable,
    ///                                (gpointer) insert_text_handler, data);
    ///   gtk_editable_insert_text (editable, result, length, position);
    ///   g_signal_handlers_unblock_by_func (editable,
    ///                                      (gpointer) insert_text_handler, data);
    ///
    ///   g_signal_stop_emission_by_name (editable, "insert_text");
    ///
    ///   g_free (result);
    /// }
    /// ```
    ///
    /// ## Signals
    ///
    ///
    /// #### `changed`
    ///  The ::changed signal is emitted at the end of a single
    /// user-visible operation on the contents of the [`Editable`][crate::Editable].
    ///
    /// E.g., a paste operation that replaces the contents of the
    /// selection will cause only one signal emission (even though it
    /// is implemented by first deleting the selection, then inserting
    /// the new content, and may cause multiple ::notify::text signals
    /// to be emitted).
    ///
    ///
    ///
    ///
    /// #### `delete-text`
    ///  This signal is emitted when text is deleted from
    /// the widget by the user. The default handler for
    /// this signal will normally be responsible for deleting
    /// the text, so by connecting to this signal and then
    /// stopping the signal with `g_signal_stop_emission()`, it
    /// is possible to modify the range of deleted text, or
    /// prevent it from being deleted entirely. The `start_pos`
    /// and `end_pos` parameters are interpreted as for
    /// [`EditableExt::delete_text()`][crate::prelude::EditableExt::delete_text()].
    ///
    ///
    ///
    ///
    /// #### `insert-text`
    ///  This signal is emitted when text is inserted into
    /// the widget by the user. The default handler for
    /// this signal will normally be responsible for inserting
    /// the text, so by connecting to this signal and then
    /// stopping the signal with `g_signal_stop_emission()`, it
    /// is possible to modify the inserted text, or prevent
    /// it from being inserted entirely.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`EditableExt`][trait@crate::prelude::EditableExt], [`EditableSignals`][trait@crate::prelude::EditableSignals]
    #[doc(alias = "GtkEditable")]
    pub struct Editable(Interface<ffi::GtkEditable, ffi::GtkEditableInterface>);

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

impl Editable {
    pub const NONE: Option<&'static Editable> = None;
}

/// Trait containing all [`struct@Editable`] methods.
///
/// # Implementors
///
/// [`Editable`][struct@crate::Editable], [`Entry`][struct@crate::Entry], [`SearchEntry`][struct@crate::SearchEntry], [`SpinButton`][struct@crate::SpinButton]
pub trait EditableExt: IsA<Editable> + 'static {
    /// Copies the contents of the currently selected content in the editable and
    /// puts it on the clipboard.
    #[doc(alias = "gtk_editable_copy_clipboard")]
    fn copy_clipboard(&self) {
        unsafe {
            ffi::gtk_editable_copy_clipboard(self.as_ref().to_glib_none().0);
        }
    }

    /// Removes the contents of the currently selected content in the editable and
    /// puts it on the clipboard.
    #[doc(alias = "gtk_editable_cut_clipboard")]
    fn cut_clipboard(&self) {
        unsafe {
            ffi::gtk_editable_cut_clipboard(self.as_ref().to_glib_none().0);
        }
    }

    /// Deletes the currently selected text of the editable.
    /// This call doesn’t do anything if there is no selected text.
    #[doc(alias = "gtk_editable_delete_selection")]
    fn delete_selection(&self) {
        unsafe {
            ffi::gtk_editable_delete_selection(self.as_ref().to_glib_none().0);
        }
    }

    /// Deletes a sequence of characters. The characters that are deleted are
    /// those characters at positions from `start_pos` up to, but not including
    /// `end_pos`. If `end_pos` is negative, then the characters deleted
    /// are those from `start_pos` to the end of the text.
    ///
    /// Note that the positions are specified in characters, not bytes.
    /// ## `start_pos`
    /// start position
    /// ## `end_pos`
    /// end position
    #[doc(alias = "gtk_editable_delete_text")]
    fn delete_text(&self, start_pos: i32, end_pos: i32) {
        unsafe {
            ffi::gtk_editable_delete_text(self.as_ref().to_glib_none().0, start_pos, end_pos);
        }
    }

    /// Retrieves a sequence of characters. The characters that are retrieved
    /// are those characters at positions from `start_pos` up to, but not
    /// including `end_pos`. If `end_pos` is negative, then the characters
    /// retrieved are those characters from `start_pos` to the end of the text.
    ///
    /// Note that positions are specified in characters, not bytes.
    /// ## `start_pos`
    /// start of text
    /// ## `end_pos`
    /// end of text
    ///
    /// # Returns
    ///
    /// a pointer to the contents of the widget as a
    ///  string. This string is allocated by the [`Editable`][crate::Editable]
    ///  implementation and should be freed by the caller.
    #[doc(alias = "gtk_editable_get_chars")]
    #[doc(alias = "get_chars")]
    fn chars(&self, start_pos: i32, end_pos: i32) -> Option<glib::GString> {
        unsafe {
            from_glib_full(ffi::gtk_editable_get_chars(
                self.as_ref().to_glib_none().0,
                start_pos,
                end_pos,
            ))
        }
    }

    /// Retrieves whether `self` is editable. See
    /// [`set_editable()`][Self::set_editable()].
    ///
    /// # Returns
    ///
    /// [`true`] if `self` is editable.
    #[doc(alias = "gtk_editable_get_editable")]
    #[doc(alias = "get_editable")]
    fn is_editable(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_editable_get_editable(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Retrieves the current position of the cursor relative to the start
    /// of the content of the editable.
    ///
    /// Note that this position is in characters, not in bytes.
    ///
    /// # Returns
    ///
    /// the cursor position
    #[doc(alias = "gtk_editable_get_position")]
    #[doc(alias = "get_position")]
    fn position(&self) -> i32 {
        unsafe { ffi::gtk_editable_get_position(self.as_ref().to_glib_none().0) }
    }

    /// Retrieves the selection bound of the editable. start_pos will be filled
    /// with the start of the selection and `end_pos` with end. If no text was
    /// selected both will be identical and [`false`] will be returned.
    ///
    /// Note that positions are specified in characters, not bytes.
    ///
    /// # Returns
    ///
    /// [`true`] if an area is selected, [`false`] otherwise
    ///
    /// ## `start_pos`
    /// location to store the starting position, or [`None`]
    ///
    /// ## `end_pos`
    /// location to store the end position, or [`None`]
    #[doc(alias = "gtk_editable_get_selection_bounds")]
    #[doc(alias = "get_selection_bounds")]
    fn selection_bounds(&self) -> Option<(i32, i32)> {
        unsafe {
            let mut start_pos = std::mem::MaybeUninit::uninit();
            let mut end_pos = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gtk_editable_get_selection_bounds(
                self.as_ref().to_glib_none().0,
                start_pos.as_mut_ptr(),
                end_pos.as_mut_ptr(),
            ));
            if ret {
                Some((start_pos.assume_init(), end_pos.assume_init()))
            } else {
                None
            }
        }
    }

    /// Inserts `new_text_length` bytes of `new_text` into the contents of the
    /// widget, at position `position`.
    ///
    /// Note that the position is in characters, not in bytes.
    /// The function updates `position` to point after the newly inserted text.
    /// ## `new_text`
    /// the text to append
    /// ## `new_text_length`
    /// the length of the text in bytes, or -1
    ///
    /// # Returns
    ///
    ///
    /// ## `position`
    /// location of the position text will be inserted at
    #[doc(alias = "gtk_editable_insert_text")]
    fn insert_text(&self, new_text: &str, position: &mut i32) {
        let new_text_length = new_text.len() as _;
        unsafe {
            ffi::gtk_editable_insert_text(
                self.as_ref().to_glib_none().0,
                new_text.to_glib_none().0,
                new_text_length,
                position,
            );
        }
    }

    /// Pastes the content of the clipboard to the current position of the
    /// cursor in the editable.
    #[doc(alias = "gtk_editable_paste_clipboard")]
    fn paste_clipboard(&self) {
        unsafe {
            ffi::gtk_editable_paste_clipboard(self.as_ref().to_glib_none().0);
        }
    }

    /// Selects a region of text. The characters that are selected are
    /// those characters at positions from `start_pos` up to, but not
    /// including `end_pos`. If `end_pos` is negative, then the
    /// characters selected are those characters from `start_pos` to
    /// the end of the text.
    ///
    /// Note that positions are specified in characters, not bytes.
    /// ## `start_pos`
    /// start of region
    /// ## `end_pos`
    /// end of region
    #[doc(alias = "gtk_editable_select_region")]
    fn select_region(&self, start_pos: i32, end_pos: i32) {
        unsafe {
            ffi::gtk_editable_select_region(self.as_ref().to_glib_none().0, start_pos, end_pos);
        }
    }

    /// Determines if the user can edit the text in the editable
    /// widget or not.
    /// ## `is_editable`
    /// [`true`] if the user is allowed to edit the text
    ///  in the widget
    #[doc(alias = "gtk_editable_set_editable")]
    fn set_editable(&self, is_editable: bool) {
        unsafe {
            ffi::gtk_editable_set_editable(self.as_ref().to_glib_none().0, is_editable.into_glib());
        }
    }

    /// Sets the cursor position in the editable to the given value.
    ///
    /// The cursor is displayed before the character with the given (base 0)
    /// index in the contents of the editable. The value must be less than or
    /// equal to the number of characters in the editable. A value of -1
    /// indicates that the position should be set after the last character
    /// of the editable. Note that `position` is in characters, not in bytes.
    /// ## `position`
    /// the position of the cursor
    #[doc(alias = "gtk_editable_set_position")]
    fn set_position(&self, position: i32) {
        unsafe {
            ffi::gtk_editable_set_position(self.as_ref().to_glib_none().0, position);
        }
    }
}

impl<O: IsA<Editable>> EditableExt for O {}