Module glib::translate

Translation between GLib/GLib-based FFI types and their Rust counterparts.

This module allows library bindings authors to decouple type translation logic and use unified idioms at FFI boundaries. It also implements translation of GLib core data types.

FromGlib, from_glib and ToGlib translate simple types like bool.

    pub fn set_accept_focus(&self, accept_focus: bool) {
        unsafe { gdk_sys::gdk_window_set_accept_focus(self.pointer, accept_focus.to_glib()) }
    }

    pub fn get_accept_focus(&self) -> bool {
        unsafe { from_glib(gdk_sys::gdk_window_get_accept_focus(self.pointer)) }
    }

ToGlibPtr, FromGlibPtrNone, FromGlibPtrFull and FromGlibPtrBorrow work on gpointers and ensure correct ownership of values according to Glib ownership transfer rules.

FromGlibPtrNone and FromGlibPtrFull must be called on values obtained from C, according to their transfer annotations. They acquire non-gobject types, as well as turning floating references to strong ones, which are the only ones properly handled by the Rust bindings.

For more information about floating references, please refer to the "Floating references" section of the gobject reference.

    fn get_title(&self) -> Option<String> {
        unsafe {
            let title = gtk_sys::gtk_window_get_title(self.pointer);
            from_glib_none(title)
        }
    }
    fn create_bool(value: gboolean) -> Variant {
        unsafe {
            let variant = glib_sys::g_variant_new_boolean(value);
            // g_variant_new_boolean has `transfer none`
            from_glib_none(variant)
        }
    }

Letting the foreign library borrow pointers from the Rust side often requires having a temporary variable of an intermediate type (e.g. CString). A Stash contains the temporary storage and a pointer into it that is valid for the lifetime of the Stash. As the lifetime of the Stash returned from to_glib_none is at least the enclosing statement, you can avoid explicitly binding the stash in most cases and just take the pointer out of it:

    pub fn set_icon_name(&self, name: &str) {
        unsafe {
            gdk_sys::gdk_window_set_icon_name(self.pointer, name.to_glib_none().0)
        }
    }

Structs

Array
Borrowed	Wrapper around values representing borrowed C memory.
HashTable
List
PtrArray
SList
Stash	Helper type that stores temporary values used for translation.
StashMut

Traits

FromGlib	Translate a simple type.
FromGlibContainer	Translate from a container.
FromGlibContainerAsVec
FromGlibPtrArrayContainerAsVec
FromGlibPtrBorrow	Translate from a pointer type by borrowing, without affecting the refcount.
FromGlibPtrContainer	Translate from a container of pointers.
FromGlibPtrFull	Translate from a pointer type which is annotated with transfer full. This transfers the ownership of the value to the Rust side.
FromGlibPtrNone	Translate from a pointer type which is annotated with transfer none. The resulting value is referenced at least once, by the bindings.
GlibPtrDefault	Provides the default pointer type to be used in some container conversions.
Ptr	A pointer
ToGlib	Translate a simple type.
ToGlibContainerFromSlice
ToGlibPtr	Translate to a pointer.
ToGlibPtrMut	Translate to a pointer with a mutable borrow.
Uninitialized	A trait for creating an uninitialized value. Handy for receiving outparams.

Functions

c_ptr_array_len⚠
const_override	Overrides pointer constness.
from_glib	Translate a simple type.
from_glib_borrow⚠	Translate from a pointer type, borrowing the pointer.
from_glib_full⚠	Translate from a pointer type, transfer: full (assume ownership).
from_glib_none⚠	Translate from a pointer type, transfer: none.
mut_override	Overrides pointer mutability.
uninitialized⚠	Returns an uninitialized value.