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:
# 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.
Modules
- A typesafe bitmask flag generator useful for sets of C-style bitmask flags. It can be used for creating typesafe wrappers around C APIs.
IMPLBoxed wrapper implementation.IMPLBoxedInline wrapper implementation.Errorbinding and helper trait.IMPLObject wrapper implementation andObjectbinding.- Overview
- Traits and essential types intended for blanket imports.
IMPLShared (reference counted) wrapper implementation.IMPLLow 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.
Valuebinding and helper traits.Variantbinding and helper traits.IMPLThewrapper!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
Closureobject. This is a wrapper aroundClosure::newthat automatically type checks its arguments at run-time. - The same as
closure!but usesClosure::new_localas a constructor. This is useful for closures which can’t be sent across threads. See the documentation ofclosure!for details. - 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.
- 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.
- Macro used to log using GLib structured logging system.
- Defines a wrapper type and implements the appropriate traits.
Structs
- Borrowed reference to an object of type
T. - This is a subclass of
glib::object::Objectcapable of storing any Rust type. It let’s you insert a Rust type anywhere aglib::object::Objectis 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]>). - Wrapper for values where C functions expect a plain C
char - Class struct of type
T. - A
CollationKeyallows ordering strings using the linguistically correct rules for the current locale. - Continue calling the closure in the future iterations or drop it.
- Representation of an
enumfor dynamically, at runtime, querying the values of the enum and using them. - Representation of a single enum value of an
EnumClass. - A generic error capable of representing various error domains (types).
- A
FilenameCollationKeyallows 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. - Wrapper type for fixed size type arrays.
- Builder for conveniently setting/unsetting flags and returning a
Value. - Representation of a
flagsfor 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. - A type representing an owned, C-compatible, nul-terminated UTF-8 string.
- A mutable text buffer that grows automatically.
- Interface struct of type
Tfor some type. - A list of items of type
T. - Structure representing a single field in a structured log entry.
- The base class in the object hierarchy.
- Process identificator
- The priority of sources
- Slice of elements of type
Tallocated by the GLib allocator. - A
Receiverthat can be attached to a main context to receive items from its correspondingSenderorSyncSender. - A list of items of type
T. - A version of
Valuefor storingSendtypes, that implements Send itself. - A weak reference to the object it was created for that can be sent to different threads even for object types that don’t implement
Send. - A
Senderthat can be used to send items to the corresponding main context receiver. - The id of a signal that is returned by
connect. - Slice of elements of type
Tallocated by the GLib allocator. - Represents a
Futurearound aglib::Source. The future will be resolved once the source has provided a value - The id of a source that is returned by
idle_addandtimeout_add. - Represents a
Streamaround aglib::Source. The stream will be provide all values that are provided by the source - A
SyncSenderthat can be used to send items to the corresponding main context receiver. - A value representing an interval of time, in microseconds.
- A GLib or GLib-based library type
- Wrapper for values where C functions expect a plain C
unsigned char - A generic value capable of carrying various types.
- A generic immutable value capable of carrying various types.
VariantDictis a mutable key/value store where the keys are always strings and the values areVariants.- Iterator over items in a variant.
- Iterator over items in a variant of type
as. - Describes
Varianttypes. - An iterator over the individual components of a tuple VariantTy.
- Describes
Varianttypes. - A weak reference to an object.
Enums
- A wrapper for
ConvertErrorthat can hold an offset into the input string. - A wrapper for
std::io::Errorthat can hold an offset into an input string.
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 correspondinglogfunctions.
Statics
Traits
- Upcasting and downcasting support.
- Convenience trait mirroring
Cast, implemented onOption<Object>types. - Trait for fixed size variant types.
- Extracts a value.
- Declares the “is a” relationship.
- Implemented by types representing
glib::Objectand subclasses of it. - A trait implemented by the various
ParamSpecbuilder types. - Types that are supported by GLib dynamic typing.
- Returns
VariantTypeofSelf. - Converts to
SendValue. - Trait to convert a value to a
Value. - Converts to
Variant.
Functions
- Obtain the character set for the current locale.
- Adds a closure to be called by the main loop the returned
Sourceis attached to when a child process exits. - Adds a closure to be called by the main loop the returned
Sourceis attached to when a child process exits. - Create a
Futurethat will resolve once the child process with the given pid exits - Create a
Futurethat will resolve once the child process with the given pid exits - Adds a closure to be called by the main loop the returned
Sourceis attached to when a child process exits. - Add a timeout to a
Future. - Add a timeout to a
Future. - Adds a closure to be called by the default main loop when it’s idle.
- Adds a closure to be called by the default main loop when it’s idle.
- Adds a closure to be called by the default main loop when it’s idle.
- Adds a closure to be called by the default main loop when it’s idle.
- Adds a closure to be called by the main loop the return
Sourceis attached to when it’s idle. - Create a
Streamthat will provide a value every given number of milliseconds. - Create a
Streamthat will provide a value every given number of seconds. - Create a
Streamthat will provide a value every given number of seconds. - Create a
Streamthat will provide a value every given number of milliseconds. - To set back the default print handler, use the
log_unset_default_handlerfunction. - To set the default print handler, use the
log_set_default_handlerfunction. - Same as
get_prgname(). - To set back the default print handler, use the
unset_print_handlerfunction. - To set back the default print handler, use the
unset_printerr_handlerfunction. - Same as
set_prgname(). - Adds a closure to be called by the default main loop at regular intervals with millisecond granularity.
- Adds a closure to be called by the default main loop at regular intervals with millisecond granularity.
- Adds a closure to be called by the default main loop at regular intervals with millisecond granularity.
- Adds a closure to be called by the default main loop at regular intervals with millisecond granularity.
- Adds a closure to be called by the default main loop at regular intervals with second granularity.
- Adds a closure to be called by the default main loop at regular intervals with second granularity.
- Adds a closure to be called by the default main loop at regular intervals with second granularity.
- Adds a closure to be called by the default main loop at regular intervals with second granularity.
- Create a
Futurethat will resolve after the given number of milliseconds. - Create a
Futurethat will resolve after the given number of seconds. - Create a
Futurethat will resolve after the given number of seconds. - Create a
Futurethat will resolve after the given number of milliseconds. - Adds a closure to be called by the main loop the returned
Sourceis attached to at regular intervals with millisecond granularity. - Adds a closure to be called by the main loop the returned
Sourceis attached to at regular intervals with second granularity. - Adds a closure to be called by the main loop the returned
Sourceis attached to whenever a UNIX file descriptor reaches the given IO condition. - Adds a closure to be called by the main loop the returned
Sourceis attached to whenever a UNIX file descriptor reaches the given IO condition. - Adds a closure to be called by the main loop the returned
Sourceis attached to whenever a UNIX file descriptor reaches the given IO condition. - Adds a closure to be called by the default main loop whenever a UNIX signal is raised.
- Adds a closure to be called by the default main loop whenever a UNIX signal is raised.
- Adds a closure to be called by the default main loop whenever a UNIX signal is raised.
- Adds a closure to be called by the default main loop whenever a UNIX signal is raised.
- Create a
Futurethat will resolve once the given UNIX signal is raised - Create a
Futurethat will resolve once the given UNIX signal is raised - Adds a closure to be called by the main loop the returned
Sourceis attached to whenever a UNIX signal is raised. - Create a
Streamthat will provide a value whenever the given UNIX signal is raised - Create a
Streamthat will provide a value whenever the given UNIX signal is raised - To set the default print handler, use the
set_print_handlerfunction. - To set the default print handler, use the
set_printerr_handlerfunction.
Type Definitions
- A GLib pointer
Attribute Macros
- Attribute macro for defining flags using the
bitflagscrate. This macro will also define aGFlags::type_function and theglib::Valuetraits. - Macro for boilerplate of
ObjectInterfaceimplementations. - Macro for boilerplate of
ObjectSubclassimplementations.
Derive Macros
- Macro for deriving implementations of
glib::clone::Downgradeandglib::clone::Upgradetraits and a weak type. - Derive macro for register a rust enum in the glib type system and derive the the
glib::Valuetraits. - Derive macro for defining a GLib error domain and its associated
ErrorDomaintrait. - Derive macro for serializing/deserializing custom structs/enums as
glib::Variants.