Crate glib

source ·
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]. 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.

Re-exports§

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.
  • This module is inefficient and should not be used by Rust programs except for compatibility with GLib.Regex based APIs.
  • 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.
  • debuglog and log_macros
    A 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).
  • errorlog and log_macros
    A 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).
  • 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.
  • infolog and log_macros
    A 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.
  • tracelog and log_macros
    A 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).
  • warnlog and log_macros
    A 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§

Enums§

  • The result of a single step of the Unicode canonical decomposition algorithm
  • The hashing algorithm to be used by #GChecksum when performing the digest of some data.
  • Continue calling the closure in the future iterations or drop it.
  • Error codes returned by character set conversion routines.
  • A wrapper for ConvertError that can hold an offset into the input string.
  • Enumeration representing a month; values are January, February, etc. BadMonth is the invalid value.
  • Enumeration representing a day of the week; Monday, Tuesday, etc. BadWeekday is an invalid weekday.
  • The kind of decomposition to perform
  • Values corresponding to @errno codes returned from file operations on UNIX. Unlike @errno codes, GFileError values are available on all systems, even Windows. The exact meaning of each code depends on what sort of file operation you were performing; the UNIX documentation gives more details. The following error code descriptions come from the GNU C Library manual, and are under the copyright of that manual.
  • 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.
  • Error codes returned by key file parsing.
  • Return values from #GLogWriterFuncs to indicate whether the given log entry was successfully handled by the writer, or whether there was an error in handling it (and hence a fallback writer should be used).
  • Error codes returned by markup parsing.
  • Defines how a Unicode string is transformed in a canonical form, standardizing such issues as whether a character with an accent is represented as a base character and combining accent or as a single precomposed character. Unicode strings should generally be normalized before comparing them.
  • The #GOptionArg enum values determine which type of extra argument the options expect to find. If an option expects an extra argument, it can be specified in several ways; with a short option: -x arg, with a long option: --name arg or combined in a single argument: --name=arg.
  • An enumeration specifying the base position for a g_io_channel_seek_position() operation.
  • Disambiguates a given time in two ways.
  • These are the possible line break classifications.
  • The #GUnicodeScript 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 with #PangoScript.
  • These are the possible character classifications from the Unicode specification. See Unicode Character Database.
  • Error codes returned by #GUri methods.
  • The range of possible top-level types of #GVariant 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§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§