gtk/auto/

im_context.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::{InputHints, InputPurpose, ffi};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    ///
    /// GtkIMContext * im_module_create(const gchar *context_id);
    /// ]|
    /// This function should return a pointer to a newly created instance of the
    /// [`IMContext`][crate::IMContext] subclass identified by `context_id`. The context ID is the same
    /// as specified in the `GtkIMContextInfo` array returned by `im_module_list()`.
    ///
    /// After a new loadable input method module has been installed on the system,
    /// the configuration file `gtk.immodules` needs to be
    /// regenerated by [gtk-query-immodules-3.0][gtk-query-immodules-3.0],
    /// in order for the new input method to become available to GTK+ applications.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `input-hints`
    ///  Readable | Writable
    ///
    ///
    /// #### `input-purpose`
    ///  Readable | Writable
    ///
    /// ## Signals
    ///
    ///
    /// #### `commit`
    ///  The ::commit signal is emitted when a complete input sequence
    /// has been entered by the user. This can be a single character
    /// immediately after a key press or the final result of preediting.
    ///
    ///
    ///
    ///
    /// #### `delete-surrounding`
    ///  The ::delete-surrounding signal is emitted when the input method
    /// needs to delete all or part of the context surrounding the cursor.
    ///
    ///
    ///
    ///
    /// #### `preedit-changed`
    ///  The ::preedit-changed signal is emitted whenever the preedit sequence
    /// currently being entered has changed. It is also emitted at the end of
    /// a preedit sequence, in which case
    /// [`IMContextExt::preedit_string()`][crate::prelude::IMContextExt::preedit_string()] returns the empty string.
    ///
    ///
    ///
    ///
    /// #### `preedit-end`
    ///  The ::preedit-end signal is emitted when a preediting sequence
    /// has been completed or canceled.
    ///
    ///
    ///
    ///
    /// #### `preedit-start`
    ///  The ::preedit-start signal is emitted when a new preediting sequence
    /// starts.
    ///
    ///
    ///
    ///
    /// #### `retrieve-surrounding`
    ///  The ::retrieve-surrounding signal is emitted when the input method
    /// requires the context surrounding the cursor. The callback should set
    /// the input method surrounding context by calling the
    /// [`IMContextExt::set_surrounding()`][crate::prelude::IMContextExt::set_surrounding()] method.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`IMContextExt`][trait@crate::prelude::IMContextExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GtkIMContext")]
    pub struct IMContext(Object<ffi::GtkIMContext, ffi::GtkIMContextClass>);

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

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

/// Trait containing all [`struct@IMContext`] methods.
///
/// # Implementors
///
/// [`IMContextSimple`][struct@crate::IMContextSimple], [`IMContext`][struct@crate::IMContext], [`IMMulticontext`][struct@crate::IMMulticontext]
pub trait IMContextExt: IsA<IMContext> + 'static {
    /// Asks the widget that the input context is attached to to delete
    /// characters around the cursor position by emitting the
    /// GtkIMContext::delete_surrounding signal. Note that `offset` and `n_chars`
    /// are in characters not in bytes which differs from the usage other
    /// places in [`IMContext`][crate::IMContext].
    ///
    /// In order to use this function, you should first call
    /// [`surrounding()`][Self::surrounding()] to get the current context, and
    /// call this function immediately afterwards to make sure that you
    /// know what you are deleting. You should also account for the fact
    /// that even if the signal was handled, the input context might not
    /// have deleted all the characters that were requested to be deleted.
    ///
    /// This function is used by an input method that wants to make
    /// subsitutions in the existing text in response to new input. It is
    /// not useful for applications.
    /// ## `offset`
    /// offset from cursor position in chars;
    ///  a negative value means start before the cursor.
    /// ## `n_chars`
    /// number of characters to delete.
    ///
    /// # Returns
    ///
    /// [`true`] if the signal was handled.
    #[doc(alias = "gtk_im_context_delete_surrounding")]
    fn delete_surrounding(&self, offset: i32, n_chars: i32) -> bool {
        unsafe {
            from_glib(ffi::gtk_im_context_delete_surrounding(
                self.as_ref().to_glib_none().0,
                offset,
                n_chars,
            ))
        }
    }

    /// Allow an input method to internally handle key press and release
    /// events. If this function returns [`true`], then no further processing
    /// should be done for this key event.
    /// ## `event`
    /// the key event
    ///
    /// # Returns
    ///
    /// [`true`] if the input method handled the key event.
    #[doc(alias = "gtk_im_context_filter_keypress")]
    fn filter_keypress(&self, event: &gdk::EventKey) -> bool {
        unsafe {
            from_glib(ffi::gtk_im_context_filter_keypress(
                self.as_ref().to_glib_none().0,
                mut_override(event.to_glib_none().0),
            ))
        }
    }

    /// Notify the input method that the widget to which this
    /// input context corresponds has gained focus. The input method
    /// may, for example, change the displayed feedback to reflect
    /// this change.
    #[doc(alias = "gtk_im_context_focus_in")]
    fn focus_in(&self) {
        unsafe {
            ffi::gtk_im_context_focus_in(self.as_ref().to_glib_none().0);
        }
    }

    /// Notify the input method that the widget to which this
    /// input context corresponds has lost focus. The input method
    /// may, for example, change the displayed feedback or reset the contexts
    /// state to reflect this change.
    #[doc(alias = "gtk_im_context_focus_out")]
    fn focus_out(&self) {
        unsafe {
            ffi::gtk_im_context_focus_out(self.as_ref().to_glib_none().0);
        }
    }

    /// Retrieve the current preedit string for the input context,
    /// and a list of attributes to apply to the string.
    /// This string should be displayed inserted at the insertion
    /// point.
    ///
    /// # Returns
    ///
    ///
    /// ## `str`
    /// location to store the retrieved
    ///  string. The string retrieved must be freed with `g_free()`.
    ///
    /// ## `attrs`
    /// location to store the retrieved
    ///  attribute list. When you are done with this list, you
    ///  must unreference it with `pango_attr_list_unref()`.
    ///
    /// ## `cursor_pos`
    /// location to store position of cursor (in characters)
    ///  within the preedit string.
    #[doc(alias = "gtk_im_context_get_preedit_string")]
    #[doc(alias = "get_preedit_string")]
    fn preedit_string(&self) -> (glib::GString, pango::AttrList, i32) {
        unsafe {
            let mut str = std::ptr::null_mut();
            let mut attrs = std::ptr::null_mut();
            let mut cursor_pos = std::mem::MaybeUninit::uninit();
            ffi::gtk_im_context_get_preedit_string(
                self.as_ref().to_glib_none().0,
                &mut str,
                &mut attrs,
                cursor_pos.as_mut_ptr(),
            );
            (
                from_glib_full(str),
                from_glib_full(attrs),
                cursor_pos.assume_init(),
            )
        }
    }

    /// Retrieves context around the insertion point. Input methods
    /// typically want context in order to constrain input text based on
    /// existing text; this is important for languages such as Thai where
    /// only some sequences of characters are allowed.
    ///
    /// This function is implemented by emitting the
    /// GtkIMContext::retrieve_surrounding signal on the input method; in
    /// response to this signal, a widget should provide as much context as
    /// is available, up to an entire paragraph, by calling
    /// [`set_surrounding()`][Self::set_surrounding()]. Note that there is no obligation
    /// for a widget to respond to the ::retrieve_surrounding signal, so input
    /// methods must be prepared to function without context.
    ///
    /// # Returns
    ///
    /// [`true`] if surrounding text was provided; in this case
    ///  you must free the result stored in *text.
    ///
    /// ## `text`
    /// location to store a UTF-8 encoded
    ///  string of text holding context around the insertion point.
    ///  If the function returns [`true`], then you must free the result
    ///  stored in this location with `g_free()`.
    ///
    /// ## `cursor_index`
    /// location to store byte index of the insertion
    ///  cursor within `text`.
    #[doc(alias = "gtk_im_context_get_surrounding")]
    #[doc(alias = "get_surrounding")]
    fn surrounding(&self) -> Option<(glib::GString, i32)> {
        unsafe {
            let mut text = std::ptr::null_mut();
            let mut cursor_index = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gtk_im_context_get_surrounding(
                self.as_ref().to_glib_none().0,
                &mut text,
                cursor_index.as_mut_ptr(),
            ));
            if ret {
                Some((from_glib_full(text), cursor_index.assume_init()))
            } else {
                None
            }
        }
    }

    /// Notify the input method that a change such as a change in cursor
    /// position has been made. This will typically cause the input
    /// method to clear the preedit state.
    #[doc(alias = "gtk_im_context_reset")]
    fn reset(&self) {
        unsafe {
            ffi::gtk_im_context_reset(self.as_ref().to_glib_none().0);
        }
    }

    /// Set the client window for the input context; this is the
    /// [`gdk::Window`][crate::gdk::Window] in which the input appears. This window is
    /// used in order to correctly position status windows, and may
    /// also be used for purposes internal to the input method.
    /// ## `window`
    /// the client window. This may be [`None`] to indicate
    ///  that the previous client window no longer exists.
    #[doc(alias = "gtk_im_context_set_client_window")]
    fn set_client_window(&self, window: Option<&gdk::Window>) {
        unsafe {
            ffi::gtk_im_context_set_client_window(
                self.as_ref().to_glib_none().0,
                window.to_glib_none().0,
            );
        }
    }

    /// Notify the input method that a change in cursor
    /// position has been made. The location is relative to the client
    /// window.
    /// ## `area`
    /// new location
    #[doc(alias = "gtk_im_context_set_cursor_location")]
    fn set_cursor_location(&self, area: &gdk::Rectangle) {
        unsafe {
            ffi::gtk_im_context_set_cursor_location(
                self.as_ref().to_glib_none().0,
                area.to_glib_none().0,
            );
        }
    }

    /// Sets surrounding context around the insertion point and preedit
    /// string. This function is expected to be called in response to the
    /// GtkIMContext::retrieve_surrounding signal, and will likely have no
    /// effect if called at other times.
    /// ## `text`
    /// text surrounding the insertion point, as UTF-8.
    ///  the preedit string should not be included within
    ///  `text`.
    /// ## `len`
    /// the length of `text`, or -1 if `text` is nul-terminated
    /// ## `cursor_index`
    /// the byte index of the insertion cursor within `text`.
    #[doc(alias = "gtk_im_context_set_surrounding")]
    fn set_surrounding(&self, text: &str, cursor_index: i32) {
        let len = text.len() as _;
        unsafe {
            ffi::gtk_im_context_set_surrounding(
                self.as_ref().to_glib_none().0,
                text.to_glib_none().0,
                len,
                cursor_index,
            );
        }
    }

    /// Sets whether the IM context should use the preedit string
    /// to display feedback. If `use_preedit` is FALSE (default
    /// is TRUE), then the IM context may use some other method to display
    /// feedback, such as displaying it in a child of the root window.
    /// ## `use_preedit`
    /// whether the IM context should use the preedit string.
    #[doc(alias = "gtk_im_context_set_use_preedit")]
    fn set_use_preedit(&self, use_preedit: bool) {
        unsafe {
            ffi::gtk_im_context_set_use_preedit(
                self.as_ref().to_glib_none().0,
                use_preedit.into_glib(),
            );
        }
    }

    #[doc(alias = "input-hints")]
    fn input_hints(&self) -> InputHints {
        ObjectExt::property(self.as_ref(), "input-hints")
    }

    #[doc(alias = "input-hints")]
    fn set_input_hints(&self, input_hints: InputHints) {
        ObjectExt::set_property(self.as_ref(), "input-hints", input_hints)
    }

    #[doc(alias = "input-purpose")]
    fn input_purpose(&self) -> InputPurpose {
        ObjectExt::property(self.as_ref(), "input-purpose")
    }

    #[doc(alias = "input-purpose")]
    fn set_input_purpose(&self, input_purpose: InputPurpose) {
        ObjectExt::set_property(self.as_ref(), "input-purpose", input_purpose)
    }

    /// The ::commit signal is emitted when a complete input sequence
    /// has been entered by the user. This can be a single character
    /// immediately after a key press or the final result of preediting.
    /// ## `str`
    /// the completed character(s) entered by the user
    #[doc(alias = "commit")]
    fn connect_commit<F: Fn(&Self, &str) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn commit_trampoline<P: IsA<IMContext>, F: Fn(&P, &str) + 'static>(
            this: *mut ffi::GtkIMContext,
            str: *mut std::ffi::c_char,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    IMContext::from_glib_borrow(this).unsafe_cast_ref(),
                    &glib::GString::from_glib_borrow(str),
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"commit".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    commit_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// The ::delete-surrounding signal is emitted when the input method
    /// needs to delete all or part of the context surrounding the cursor.
    /// ## `offset`
    /// the character offset from the cursor position of the text
    ///  to be deleted. A negative value indicates a position before
    ///  the cursor.
    /// ## `n_chars`
    /// the number of characters to be deleted
    ///
    /// # Returns
    ///
    /// [`true`] if the signal was handled.
    #[doc(alias = "delete-surrounding")]
    fn connect_delete_surrounding<F: Fn(&Self, i32, i32) -> bool + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn delete_surrounding_trampoline<
            P: IsA<IMContext>,
            F: Fn(&P, i32, i32) -> bool + 'static,
        >(
            this: *mut ffi::GtkIMContext,
            offset: std::ffi::c_int,
            n_chars: std::ffi::c_int,
            f: glib::ffi::gpointer,
        ) -> glib::ffi::gboolean {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    IMContext::from_glib_borrow(this).unsafe_cast_ref(),
                    offset,
                    n_chars,
                )
                .into_glib()
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"delete-surrounding".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    delete_surrounding_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// The ::preedit-changed signal is emitted whenever the preedit sequence
    /// currently being entered has changed. It is also emitted at the end of
    /// a preedit sequence, in which case
    /// [`preedit_string()`][Self::preedit_string()] returns the empty string.
    #[doc(alias = "preedit-changed")]
    fn connect_preedit_changed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn preedit_changed_trampoline<P: IsA<IMContext>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkIMContext,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(IMContext::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"preedit-changed".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    preedit_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// The ::preedit-end signal is emitted when a preediting sequence
    /// has been completed or canceled.
    #[doc(alias = "preedit-end")]
    fn connect_preedit_end<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn preedit_end_trampoline<P: IsA<IMContext>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkIMContext,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(IMContext::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"preedit-end".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    preedit_end_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// The ::preedit-start signal is emitted when a new preediting sequence
    /// starts.
    #[doc(alias = "preedit-start")]
    fn connect_preedit_start<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn preedit_start_trampoline<P: IsA<IMContext>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkIMContext,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(IMContext::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"preedit-start".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    preedit_start_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// The ::retrieve-surrounding signal is emitted when the input method
    /// requires the context surrounding the cursor. The callback should set
    /// the input method surrounding context by calling the
    /// [`set_surrounding()`][Self::set_surrounding()] method.
    ///
    /// # Returns
    ///
    /// [`true`] if the signal was handled.
    #[doc(alias = "retrieve-surrounding")]
    fn connect_retrieve_surrounding<F: Fn(&Self) -> bool + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn retrieve_surrounding_trampoline<
            P: IsA<IMContext>,
            F: Fn(&P) -> bool + 'static,
        >(
            this: *mut ffi::GtkIMContext,
            f: glib::ffi::gpointer,
        ) -> glib::ffi::gboolean {
            unsafe {
                let f: &F = &*(f as *const F);
                f(IMContext::from_glib_borrow(this).unsafe_cast_ref()).into_glib()
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"retrieve-surrounding".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    retrieve_surrounding_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "input-hints")]
    fn connect_input_hints_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_input_hints_trampoline<
            P: IsA<IMContext>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GtkIMContext,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(IMContext::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::input-hints".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_input_hints_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "input-purpose")]
    fn connect_input_purpose_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_input_purpose_trampoline<
            P: IsA<IMContext>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GtkIMContext,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(IMContext::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::input-purpose".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_input_purpose_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<IMContext>> IMContextExt for O {}