Crate glib

glib, gobject and gio bindings for Rust

This library contains

• bindings to some essential GLib, GObject, GIO types and APIs,

• common building blocks used in both handmade and machine generated bindings to GTK+ and other GLib-based libraries.

It is the foundation for higher level libraries with uniform Rusty (safe and strongly typed) APIs. It avoids exposing GLib-specific data types where possible and is not meant to provide comprehensive GLib bindings, which would often amount to duplicating the Rust Standard Library or other utility crates.

The library is a work in progress: expect missing functionality and breaking changes.

Dynamic typing

Most types in the GLib family have type identifiers (Type). Their corresponding Rust types implement the StaticType trait.

Dynamically typed Value can carry values of any T: StaticType.

Variant can carry values of T: StaticVariantType.

Errors

Errors are represented by Error, which can carry values from various error domains (such as FileError).

Objects

Each class and interface has a corresponding smart pointer struct representing an instance of that type (e.g. Object for GObject, gtk::Widget for GtkWidget). They are reference counted and feature interior mutability similarly to Rust's Rc<RefCell<T>> idiom. Consequently, cloning objects is cheap and their methods never require mutable borrows. Two smart pointers are equal iff they point to the same object.

The root of the object hierarchy is Object. Inheritance and subtyping is denoted with the IsA marker trait. The Cast trait enables upcasting and downcasting.

Interfaces and non-leaf classes also have corresponding traits (e.g. ObjectExt and gtk::WidgetExt), which are blanketly implemented for all their subtypes.

Under the hood

GLib-based libraries largely operate on pointers to various boxed or reference counted structures so the bindings have to implement corresponding smart pointers (wrappers), which encapsulate resource management and safety checks. Such wrappers are defined via the glib_wrapper! macro, which uses abstractions defined in the wrapper, boxed, shared and object modules.

The translate module defines and partly implements conversions between high level Rust types (including the aforementioned wrappers) and their FFI counterparts.

Reexports

pub use error::Error;

pub use object::Cast;

pub use object::IsA;

pub use object::Object;

pub use object::ObjectExt;

pub use signal::signal_handler_block;

pub use signal::signal_handler_unblock;

pub use signal::signal_stop_emission;

pub use signal::signal_stop_emission_by_name;

pub use types::StaticType;

pub use types::Type;

pub use value::ToValue;

pub use value::TypedValue;

pub use value::Value;

pub use variant::StaticVariantType;

pub use variant::ToVariant;

pub use variant::Variant;

Modules

boxed	IMPL Boxed wrapper implementation.
error	Error binding and helper trait.
object	IMPL Object wrapper implementation and Object binding.
prelude	Traits and essential types intended for blanket imports.
shared	IMPL Shared (reference counted) wrapper implementation.
signal	IMPL Low level signal support.
translate	Translation between GLib/GLib-based FFI types and their Rust counterparts.
types	Runtime type information.
utils
value	Value binding and helper traits.
variant	Variant binding and helper traits.
wrapper	IMPL The glib_wrapper! macro and miscellaneous wrapper traits.

Macros

glib_boxed_wrapper	Wrapper implementations for Boxed types. See glib_wrapper!.
glib_object_wrapper	Wrapper implementations for Object types. See glib_wrapper!.
glib_shared_wrapper	Wrapper implementations for shared types. See glib_wrapper!.
glib_wrapper	Defines a wrapper type and implements the appropriate traits.

Structs

Bytes	A shared immutable byte slice (the equivalent of Rc<[u8]>).
CallbackGuard	Unwinding propagation guard. Aborts the process if destroyed while panicking.
Continue	Continue calling the closure in the future iterations or drop it.
KeyFile
KeyFileFlags
SourceId	The id of a source that is returned by idle_add and timeout_add.
TimeVal
VariantTy	Describes Variant types.
VariantType	Describes Variant types.

Enums

FileError
KeyFileError
UserDirectory

Constants

KEY_FILE_DESKTOP_GROUP
KEY_FILE_DESKTOP_KEY_ACTIONS
KEY_FILE_DESKTOP_KEY_CATEGORIES
KEY_FILE_DESKTOP_KEY_COMMENT
KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE
KEY_FILE_DESKTOP_KEY_EXEC
KEY_FILE_DESKTOP_KEY_FULLNAME
KEY_FILE_DESKTOP_KEY_GENERIC_NAME
KEY_FILE_DESKTOP_KEY_GETTEXT_DOMAIN
KEY_FILE_DESKTOP_KEY_HIDDEN
KEY_FILE_DESKTOP_KEY_ICON
KEY_FILE_DESKTOP_KEY_KEYWORDS
KEY_FILE_DESKTOP_KEY_MIME_TYPE
KEY_FILE_DESKTOP_KEY_NAME
KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN
KEY_FILE_DESKTOP_KEY_NO_DISPLAY
KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN
KEY_FILE_DESKTOP_KEY_PATH
KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY
KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS
KEY_FILE_DESKTOP_KEY_TERMINAL
KEY_FILE_DESKTOP_KEY_TRY_EXEC
KEY_FILE_DESKTOP_KEY_TYPE
KEY_FILE_DESKTOP_KEY_URL
KEY_FILE_DESKTOP_KEY_VERSION
KEY_FILE_DESKTOP_TYPE_APPLICATION
KEY_FILE_DESKTOP_TYPE_DIRECTORY
KEY_FILE_DESKTOP_TYPE_LINK
KEY_FILE_KEEP_COMMENTS
KEY_FILE_KEEP_TRANSLATIONS
KEY_FILE_NONE

Functions

get_current_time
idle_add	Adds a closure to be called by the default main loop when it's idle.
source_remove	Removes the source with the given id source_id from the default main context.
timeout_add	Adds a closure to be called by the default main loop at regular intervals with millisecond granularity.
timeout_add_seconds	Adds a closure to be called by the default main loop at regular intervals with second granularity.