Expand description
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 IntoGlib
translate simple types like bool
.
pub fn set_accept_focus(&self, accept_focus: bool) {
unsafe { gdk::ffi::gdk_window_set_accept_focus(self.pointer, accept_focus.into_glib()) }
}
pub fn get_accept_focus(&self) -> bool {
unsafe { from_glib(gdk::ffi::gdk_window_get_accept_focus(self.pointer)) }
}
Implementing OptionIntoGlib
on a Rust type T
allows specifying a sentinel to indicate
a None
value and auto-implementing FromGlib
for Option<T>
, which would not be
possible in dependent crates due to the orphan rule.
In the example below, IntoGlib
is auto-implemented for Option<SpecialU32>
.
struct SpecialU32(u32);
impl IntoGlib for SpecialU32 {
type GlibType = libc::c_uint;
fn into_glib(self) -> libc::c_uint {
self.0 as libc::c_uint
}
}
impl OptionIntoGlib for SpecialU32 {
const GLIB_NONE: Self::GlibType = 0xFFFFFF;
}
In order to auto-implement FromGlib
for Option<SpecialU32>
, proceed as follows:
impl TryFromGlib<libc::c_uint> for SpecialU32 {
type Error = GlibNoneError;
unsafe fn try_from_glib(val: libc::c_uint) -> Result<Self, GlibNoneError> {
if val == SpecialU32::GLIB_NONE {
return Err(GlibNoneError);
}
Ok(SpecialU32(val as u32))
}
}
The TryFromGlib
trait can also be implemented when the Glib type range is larger than the
target Rust type’s range. In the example below, the Rust type U32
can be built from a signed
[libc::c_long
], which means that the negative range is not valid.
struct U32(u32);
impl TryFromGlib<libc::c_long> for U32 {
type Error = TryFromIntError;
unsafe fn try_from_glib(val: libc::c_long) -> Result<Self, TryFromIntError> {
Ok(U32(u32::try_from(val)?))
}
}
Finally, you can define TryFromGlib
with both None
and Invalid
alternatives by setting
the associated type Error = GlibNoneOrInvalidError<I>
(where I
is the Error
type
when the value is invalid), which results in auto-implementing FromGlib
for
Result<Option<T>, I>
.
ToGlibPtr
, FromGlibPtrNone
, FromGlibPtrFull
and FromGlibPtrBorrow
work on gpointer
s
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::ffi::gtk_window_get_title(self.pointer);
from_glib_none(title)
}
}
fn create_bool(value: gboolean) -> Variant {
unsafe {
let variant = ffi::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::ffi::gdk_window_set_icon_name(self.pointer, name.to_glib_none().0)
}
}
Re-exports§
pub use crate::collections::ptr_slice::IntoPtrSlice;
pub use crate::collections::strv::IntoStrV;
Structs§
- Borrowed
- Wrapper around values representing borrowed C memory.
- Glib
None Error - Error type for
TryFromGlib
when the Glib value is None. - Hash
Table - List
- PtrArray
- SList
- Stash
- Helper type that stores temporary values used for translation.
- Stash
Mut
Enums§
- Glib
None OrInvalid Error - Error type for
TryFromGlib
when the Glib value can be None or invalid.
Traits§
- From
Glib - Translate a simple type.
- From
Glib Container - Translate from a container.
- From
Glib Container AsVec - From
Glib PtrArray Container AsVec - From
Glib PtrBorrow - Translate from a pointer type by borrowing, without affecting the refcount.
- From
Glib PtrContainer - Translate from a container of pointers.
- From
Glib PtrFull - Translate from a pointer type which is annotated with
transfer full
. This transfers the ownership of the value to the Rust side. - From
Glib PtrNone - Translate from a pointer type which is annotated with
transfer none
. The resulting value is referenced at least once, by the bindings. - Glib
PtrDefault - Provides the default pointer type to be used in some container conversions.
- IntoG
Str - A trait to accept both
&str
or&GStr
as an argument. - Into
Glib - Translate a simple type.
- Into
Glib Ptr - Translate to a pointer.
- Into
OptionalG Str - A trait to accept both
Option<&str>
orOption<&GStr>
as an argument. - Option
Into Glib - A Rust type
T
for whichOption<T>
translates to the same glib type as T. - Ptr
- A pointer
- ToGlib
Container From Slice - ToGlib
Ptr - Translate to a pointer.
- ToGlib
PtrMut - Translate to a pointer with a mutable borrow.
- Transparent
PtrType - Trait for types that have the same memory representation as a pointer to their FFI type.
- Transparent
Type - Trait for types that have the same memory representation as their FFI type.
- TryFrom
Glib - Translate from a Glib type which can result in an undefined and/or invalid value.
- Uninitialized
- A trait for creating an uninitialized value. Handy for receiving outparams.
- Unsafe
From - Unsafe variant of the
From
trait.
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.
- try_
from_ ⚠glib - Translate from a Glib type which can result in an undefined and/or invalid value.
- uninitialized⚠
- Returns an uninitialized value.