Expand description
Rust GLib and GObject bindings
Rust bindings and wrappers for GLib, part of gtk-rs-core.
GLib 2.56 is the lowest supported version for the underlying library.
This library contains bindings to GLib and GObject types and APIs as well as 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.
Minimum supported Rust version
Currently, the minimum supported Rust version is 1.63.0.
Dynamic typing
Most types in the GLib family have Type identifiers.
Their corresponding Rust types implement the StaticType trait.
A dynamically typed Value can carry values of any StaticType.
Variants can carry values of 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 or
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 if 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 or gtk::WidgetExt), which are blanketly implemented for all
their subtypes.
You can create new subclasses of Object or other object types. Look at
the module’s documentation for further details and a code example.
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
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.
Documentation
Using
We recommend using crates from crates.io, as demonstrated here.
If you want to track the bleeding edge, use the git dependency instead:
[dependencies]
glib = { git = "https://github.com/gtk-rs/gtk-rs-core.git", package = "glib" }Avoid mixing versioned and git crates like this:
[dependencies]
glib = "0.13"
glib = { git = "https://github.com/gtk-rs/gtk-rs-core.git", package = "glib" }License
glib is available under the MIT License, please refer to it.
Re-exports
pub use ffi;pub use gobject_ffi;pub use self::closure::Closure;pub use self::closure::RustClosure;pub use self::error::BoolError;pub use self::error::Error;pub use self::object::Cast;pub use self::object::Class;pub use self::object::InitiallyUnowned;pub use self::object::Interface;pub use self::object::IsA;pub use self::object::Object;pub use self::object::ObjectExt;pub use self::object::ObjectType;pub use self::object::SendWeakRef;pub use self::object::WeakRef;pub use self::signal::signal_handler_block;pub use self::signal::signal_handler_disconnect;pub use self::signal::signal_handler_unblock;pub use self::signal::signal_stop_emission_by_name;pub use self::signal::SignalHandlerId;pub use self::types::ILong;pub use self::types::Pointer;pub use self::types::StaticType;pub use self::types::StaticTypeExt;pub use self::types::Type;pub use self::types::ULong;pub use self::value::BoxedValue;pub use self::value::SendValue;pub use self::value::ToSendValue;pub use self::value::ToValue;pub use self::value::Value;pub use self::variant::FixedSizeVariantArray;pub use self::variant::FixedSizeVariantType;pub use self::variant::FromVariant;pub use self::variant::StaticVariantType;pub use self::variant::ToVariant;pub use self::variant::Variant;pub use collections::List;pub use collections::PtrSlice;pub use collections::SList;pub use collections::Slice;pub use self::char::*;pub use self::source::*;Modules
IMPL Boxed wrapper implementation.IMPL BoxedInline wrapper implementation.Error binding and helper trait.IMPL Object wrapper implementation and Object binding.Traits and essential types intended for blanket imports.
IMPL Shared (reference counted) wrapper implementation.IMPL Low level signal support.Module containing infrastructure for subclassing
GObjects and registering boxed types.Translation between GLib/GLib-based FFI types and their Rust counterparts.
Runtime type information.
Value binding and helper traits.Variant binding and helper traits.IMPL The wrapper! macro and miscellaneous wrapper traits.Macros
Generic error used for functions that fail without any further information
Macro for passing variables as strong or weak references into a closure.
Macro for creating a
Closure object. This is a wrapper around Closure::new that
automatically type checks its arguments at run-time.The same as
closure! but uses Closure::new_local as a constructor.
This is useful for closures which can’t be sent across threads. See the documentation of
closure! for details.debug
log_macrosA macro which behaves exactly as
log::debug! except that it sets the
current log target to the contents of a G_LOG_DOMAIN constant (and fails
to build if not defined).error
log_macrosA macro which behaves exactly as
log::error! except that it sets the
current log target to the contents of a G_LOG_DOMAIN constant (and fails
to build if not defined).Macro used to log using GLib logging system. It uses g_log.
Macro used to print error messages. It uses g_printerr.
Wrapper implementations for BoxedInline types. See
wrapper!.Wrapper implementations for Boxed types. See
wrapper!.ObjectType implementations for Object types. See
wrapper!.Wrapper implementations for shared types. See
wrapper!.Converts a static string literal into a static nul-terminated string.
info
log_macrosA macro which behaves exactly as
log::info! except that it sets the
current log target to the contents of a G_LOG_DOMAIN constant (and fails
to build if not defined).Macro used to log using GLib structured logging system.
trace
log_macrosA macro which behaves exactly as
log::trace! except that it sets the
current log target to the contents of a G_LOG_DOMAIN constant (and fails
to build if not defined).warn
log_macrosA macro which behaves exactly as
log::warn! except that it sets the
current log target to the contents of a G_LOG_DOMAIN constant (and fails
to build if not defined).Defines a wrapper type and implements the appropriate traits.
Structs
Flags to be passed to
ObjectExt::bind_property() or
[ObjectExt::bind_property_full()][crate::prelude::ObjectExt::bind_property_full()].BindingGroup
v2_72The
BindingGroup can be used to bind multiple properties
from an object collectively.BindingGroupBuilder
v2_72Builder for binding group bindings.
This is a subclass of
glib::object::Object capable of storing any Rust type.
It let’s you insert a Rust type anywhere a glib::object::Object is needed.
The inserted value can then be borrowed as a Rust type, by using the various
provided methods.A shared immutable byte slice (the equivalent of
Rc<[u8]>).A
CollationKey allows ordering strings using the linguistically correct rules for the current locale.Representation of an
enum for dynamically, at runtime, querying the values of the enum and
using them.Representation of a single enum value of an
EnumClass.FileSetContentsFlags
v2_66A
FilenameCollationKey allows ordering file names using the linguistically correct rules for the current locale.
Compared to CollationKey, filename collation keys take into consideration dots and other characters
commonly found in file names.Builder for conveniently setting/unsetting flags and returning a
Value.Representation of a
flags for dynamically, at runtime, querying the values of the enum and
using themRepresentation of a single flags value of a
FlagsClass.The error returned when a future times out.
A type representing an owned, C-compatible, nul-terminated UTF-8 string.
A mutable text buffer that grows automatically.
An implementation of a
log compatible
logger which logs over glib logging facilities.Structure representing a single field in a structured log entry.
MainContextFlags
v2_72Through the
ParamFlags flag values, certain aspects of parameters
can be configured.A
Receiver that can be attached to a main context to receive items from its corresponding
Sender or SyncSender.A
Sender that can be used to send items to the corresponding main context receiver.The signal flags are used to specify a signal’s behaviour.
SignalGroup
v2_74SignalGroup manages to simplify the process of connecting
many signals to a Object as a group. As such there is no API
to disconnect a signal from the group.Represents a
Future around a glib::Source. The future will
be resolved once the source has provided a valueRepresents a
Stream around a glib::Source. The stream will
be provide all values that are provided by the sourceA
SyncSender that can be used to send items to the corresponding main context receiver.A value representing an interval of time, in microseconds.
Uri
v2_66UriFlags
v2_66Flags that describe a URI.
UriHideFlags
v2_66Flags describing what parts of the URI to hide in
Uri::to_string_partial(). Note that PASSWORD and
AUTH_PARAMS will only work if the Uri was parsed with
the corresponding flags.UriParamsFlags
v2_66Flags modifying the way parameters are handled by
g_uri_parse_params() and
GUriParamsIter.VariantDict is a mutable key/value store where the keys are always
strings and the values are Variants.Iterator over items in a variant.
Iterator over items in a variant of type
as.Describes
Variant types.An iterator over the individual components of a tuple VariantTy.
Describes
Variant types.Enums
A wrapper for
ConvertError that can hold an offset into the input
string.Enumeration of the possible domain handling behaviours for a
GlibLogger.Enumeration of the possible formatting behaviours for a
GlibLogger.A wrapper for
std::io::Error that can hold an offset into an input string.These are logical ids for special directories which are defined
depending on the platform used. You should use
user_special_dir()
to retrieve the full path associated to the logical id.The range of possible top-level types of
Variant instances.Constants
This is the log domain used by the
clone! macro. If you want to use a custom
logger (it prints to stdout by default), you can set your own logger using the corresponding
log functions.Statics
Traits
A trait implemented by the various
ParamSpec builder types.Functions
Obtain the character set for the current locale.
Create a
Future that will resolve once the child process with the given pid exitsCreate a
Future that will resolve once the child process with the given pid exitsconsole_charset
v2_62Add a timeout to a
Future.Add a timeout to a
Future.Create a
Stream that will provide a value every given number of milliseconds.Create a
Stream that will provide a value every given number of seconds.Create a
Stream that will provide a value every given number of seconds.Create a
Stream that will provide a value every given number of milliseconds.To set back the default print handler, use the
log_unset_default_handler function.To set the default print handler, use the
log_set_default_handler function.Sets whether GLib log functions output to stderr or stdout.
os_info
v2_64Same as
get_prgname().Returns a random
gint32 equally distributed over the range
[begin..end-1].Sets the seed for the global random number generator, which is used
by the g_random_* functions, to
seed.Resets the cache used for
user_special_dir(), so
that the latest on-disk version is used. Call this only
if you just changed the data on disk yourself.Provides a glib log handler which routes all logging messages to the
log crate.Sets a human-readable name for the application. This name should be
localized if possible, and is intended for display to the user.
Contrast with
g_set_prgname(), which sets a non-localized name.
g_set_prgname() will be called automatically by gtk_init(),
but set_application_name() will not.To set back the default print handler, use the
unset_print_handler function.To set back the default print handler, use the
unset_printerr_handler function.Same as
set_prgname().Sets an environment variable. On UNIX, both the variable’s name and
value can be arbitrary byte strings, except that the variable’s name
cannot contain ‘=’. On Windows, they should be in UTF-8.
Parses a command line into an argument vector, in much the same way
the shell would, but without many of the expansions the shell would
perform (variable expansion, globs, operators, filename expansion,
etc. are not supported).
Quotes a string so that the shell (/bin/sh) will interpret the
quoted string to mean
unquoted_string.Unquotes a string as the shell (/bin/sh) would.
Gets the smallest prime number from a built-in array of primes which
is larger than
num. This is used within GLib to calculate the optimum
size of a GHashTable.Executes a child program asynchronously.
spawn_async_with_fds
v2_58 and non-Windowsspawn_async_with_pipesNon-Windows
Create a
Future that will resolve after the given number of milliseconds.Create a
Future that will resolve after the given number of seconds.Create a
Future that will resolve after the given number of seconds.Create a
Future that will resolve after the given number of milliseconds.Create a
Future that will resolve once the given UNIX signal is raisedCreate a
Future that will resolve once the given UNIX signal is raisedCreate a
Stream that will provide a value whenever the given UNIX signal is raisedCreate a
Stream that will provide a value whenever the given UNIX signal is raisedTo set the default print handler, use the
set_print_handler function.To set the default print handler, use the
set_printerr_handler function.user_state_dir
v2_72Type Definitions
Attribute Macros
Attribute macro for defining flags using the
bitflags crate.
This macro will also define a GFlags::type_ function and
the glib::Value traits.Macro for boilerplate of
ObjectInterface implementations.Macro for boilerplate of
ObjectSubclass implementations.Derive Macros
Macro for deriving implementations of
glib::clone::Downgrade and
glib::clone::Upgrade traits and a weak type.Derive macro for register a rust enum in the glib type system and derive the
the
glib::Value traits.Derive macro for defining a GLib error domain and its associated
ErrorDomain trait.Derive macro for serializing/deserializing custom structs/enums as
glib::Variants.