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.70.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
.
Variant
s 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:
# This will not compile
[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 self::closure::Closure;
pub use self::closure::RustClosure;
pub use self::error::BoolError;
pub use self::error::Error;
pub use self::object::BorrowedObject;
pub use self::object::Cast;
pub use self::object::CastNone;
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::Propagation;
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 self::FileError;
pub use collections::ptr_slice::IntoPtrSlice;
pub use collections::strv::IntoStrV;
pub use collections::List;
pub use collections::PtrSlice;
pub use collections::SList;
pub use collections::Slice;
pub use collections::StrV;
pub use bitflags;
pub use ffi;
pub use gobject_ffi;
pub use once_cell;
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 andObject
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
GObject
s 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
Thewrapper!
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 aroundClosure::new
that automatically type checks its arguments at run-time. - The same as
closure!
but usesClosure::new_local
as a constructor. This is useful for closures which can’t be sent across threads. See the documentation ofclosure!
for details. - debug
log
andlog_macros
A macro which behaves exactly aslog::debug!
except that it sets the current log target to the contents of aG_LOG_DOMAIN
constant (and fails to build if not defined). - error
log
andlog_macros
A macro which behaves exactly aslog::error!
except that it sets the current log target to the contents of aG_LOG_DOMAIN
constant (and fails to build if not defined). - This macro returns the name of the enclosing function. As the internal implementation is based on the
std::any::type_name
, this macro derives all the limitations of this function. - Macro used to log using GLib logging system. It uses g_log.
- Macro used to log using GLib logging system. It uses g_log.
- Macro used to log using GLib logging system. It uses g_log.
- Macro used to log using GLib logging system. It uses g_log.
- Macro used to log using GLib logging system. It uses g_log.
- Macro used to log using GLib logging system. It uses g_log.
- Macro used to print messages. It uses g_print.
- Macro used to print error messages. It uses g_printerr.
- Macro used to log using GLib logging system. It uses g_log.
- Creates a
GString
using interpolation of runtime expressions. - 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
andlog_macros
A macro which behaves exactly aslog::info!
except that it sets the current log target to the contents of aG_LOG_DOMAIN
constant (and fails to build if not defined). - Macro used to log using GLib structured logging system.
- trace
log
andlog_macros
A macro which behaves exactly aslog::trace!
except that it sets the current log target to the contents of aG_LOG_DOMAIN
constant (and fails to build if not defined). - warn
log
andlog_macros
A macro which behaves exactly aslog::warn!
except that it sets the current log target to the contents of aG_LOG_DOMAIN
constant (and fails to build if not defined). - Defines a wrapper type and implements the appropriate traits.
Structs
- BindingGroup
v2_72
- BindingGroupBuilder
v2_72
Builder 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 aglib::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_66
- A
FilenameCollationKey
allows ordering file names using the linguistically correct rules for the current locale. Compared toCollationKey
, 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 them - Representation of a single flags value of a
FlagsClass
. - The error returned when a future times out.
- Representation of a borrowed
GString
. - Error type indicating that a buffer had unexpected nul-bytes.
- A type representing an owned, C-compatible, nul-terminated UTF-8 string.
- A mutable text buffer that grows automatically.
- Error type indicating that a buffer had unexpected nul-bytes.
- Error type indicating that a buffer did not have a trailing nul-byte.
NULL
-terminated UTF-8 string as stored in [StrV
].- Error type indicating that a buffer had invalid UTF-8.
- GlibLogger
log
An implementation of alog
compatible logger which logs over glib logging facilities. - Task failure from awaiting a
JoinHandle
. - A handle to a task running on a
MainContext
. - Structure representing a single field in a structured log entry.
- MainContextFlags
v2_72
- Through 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 correspondingSender
orSyncSender
. - 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_74
SignalGroup
manages to simplify the process of connecting many signals to aObject
as a group. As such there is no API to disconnect a signal from the group. - Represents a
Future
around aglib::Source
. The future will be resolved once the source has provided a value - Represents a
Stream
around aglib::Source
. The stream will be provide all values that are provided by the source - Variant of
JoinHandle
that is returned fromMainContext::spawn_from_within
. - A
SyncSender
that can be used to send items to the corresponding main context receiver. - A handle to a thread running on a
ThreadPool
. - A value representing an interval of time, in microseconds.
TimeZone
is an opaque structure whose members cannot be accessed directly.- Uri
v2_66
TheUri
type and related functions can be used to parse URIs into their components, and build valid URIs from individual components. - UriFlags
v2_66
Flags that describe a URI. - UriHideFlags
v2_66
Flags describing what parts of the URI to hide inUri::to_string_partial()
. Note thatPASSWORD
andAUTH_PARAMS
will only work if theUri
was parsed with the corresponding flags. - UriParamsFlags
v2_66
Flags modifying the way parameters are handled byg_uri_parse_params()
andGUriParamsIter
. VariantDict
is a mutable key/value store where the keys are always strings and the values areVariant
s.- 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
- The result of a single step of the Unicode canonical decomposition algorithm
- Continue calling the closure in the future iterations or drop it.
- A wrapper for
ConvertError
that can hold an offset into the input string. - The kind of decomposition to perform
- Error type holding all possible failures when creating a
GStr
reference. - Error type holding all possible failures when creating a
GString
. - 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. - Disambiguates a given time in two ways.
- These are the possible line break classifications.
- The
UnicodeScript
enumeration identifies different writing systems. The values correspond to the names as defined in the Unicode standard. The enumeration has been added in GLib 2.14, and is interchangeable withPangoScript
. - These are the possible character classifications from the Unicode specification. See Unicode Character Database.
- UriError
v2_66
Error codes returned byUri
methods. - 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 correspondinglog
functions.
Statics
Traits
- A trait implemented by the various
ParamSpec
builder types. - A type that can be used as a property. It covers every type which have an associated
ParamSpec
(HasParamSpec
) and some useful types wrappingHasParamSpec
. The definition is recursive, so you can nest manyProperty
s together. The finalParamSpec
will be the one of the innermost type - A container type implementing this trait can be read by the default getter generated by the
Props
macro. - A container type implementing this trait can be written by the default setter generated by the
Props
macro. - A container type implementing this trait can be written by the default setter generated by the
Props
macro. It takes aFnOnce(&mut Self::Value)
so that the caller may access nested fields of a struct by doing${Self::Value}.member
- This trait provides access to Unicode character classification and manipulations functions provided by GLib that do not exist in the standard library
Functions
- A wrapper for the POSIX
access()
function. This function is used to test a pathname for one or several of read, write or execute permissions, or just existence. - Decode a sequence of Base-64 encoded text into binary data. Note that the returned binary data is not necessarily zero-terminated, so it should not be used as a character string.
- Encode a sequence of binary data into its Base-64 stringified representation.
- Obtain the character set for the current locale.
- Checks that the GLib library in use is compatible with the given version.
- Create a
Future
that will resolve once the child process with the given pid exits - Create a
Future
that will resolve once the child process with the given pid exits - Computes the checksum for a binary
data
. This is a convenience wrapper forChecksum::new()
,Checksum::string()
andg_checksum_free()
. - Computes the checksum for a binary
data
oflength
. This is a convenience wrapper forChecksum::new()
,Checksum::string()
andg_checksum_free()
. - Computes the HMAC for a binary
data
. This is a convenience wrapper forg_hmac_new()
,g_hmac_get_string()
andg_hmac_unref()
. - Computes the HMAC for a binary
data
oflength
. This is a convenience wrapper forg_hmac_new()
,g_hmac_get_string()
andg_hmac_unref()
. - Add 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.
- Same as
get_prgname()
. - Provides a glib log handler which routes all logging messages to the
log crate
. - 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()
. - spawn_check_exit_statusDeprecated
- Spawn a new infallible
Future
on the thread-default main context. - Spawn a new infallible
Future
on the thread-default main context. - 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 raised - Create a
Future
that will resolve once the given UNIX signal is raised - Create a
Stream
that will provide a value whenever the given UNIX signal is raised - Create a
Stream
that will provide a value whenever the given UNIX signal is raised - To set the default print handler, use the
set_print_handler
function. - To set the default print handler, use the
set_printerr_handler
function.
Type Aliases
Attribute Macros
- When applied to
ObjectImpl
- Attribute macro for defining flags using the
bitflags
crate. This macro will also define aGFlags::type_
function and theglib::Value
traits. - Macro for boilerplate of
ObjectInterface
implementations. - Macro for boilerplate of
ObjectSubclass
implementations.
Derive Macros
- Derive macro for defining a
BoxedType
::type_
function and theglib::Value
traits. Optionally, the type can be marked asnullable
to get an implemention ofglib::value::ToValueOptional
. - Macro for deriving implementations of
glib::clone::Downgrade
andglib::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. - This macro enables you to derive object properties in a quick way.
- Derive macro for defining a
SharedType
::get_type
function and theglib::Value
traits. Optionally, the type can be marked asnullable
to get an implemention ofglib::value::ToValueOptional
. - Example
- Derive macro for serializing/deserializing custom structs/enums as
glib::Variant
s.