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

  • boxed
    IMPL Boxed wrapper implementation.
  • boxed_inline
    IMPL BoxedInline wrapper implementation.
  • char
  • clone
  • closure
  • collections
  • error
    Error binding and helper trait.
  • functions
  • 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.
  • source
  • subclass
    Module containing infrastructure for subclassing GObjects and registering boxed types.
  • thread_guard
  • translate
    Translation between GLib/GLib-based FFI types and their Rust counterparts.
  • types
    Runtime type information.
  • value
    Value binding and helper traits.
  • variant
    Variant binding and helper traits.
  • wrapper
    IMPL The wrapper! macro and miscellaneous wrapper traits.

Macros

  • bool_error
    Generic error used for functions that fail without any further information
  • clone
    Macro for passing variables as strong or weak references into a closure.
  • closure
    Macro for creating a Closure object. This is a wrapper around Closure::new that automatically type checks its arguments at run-time.
  • closure_local
    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).
  • function_name
    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.
  • g_critical
    Macro used to log using GLib logging system. It uses g_log.
  • g_debug
    Macro used to log using GLib logging system. It uses g_log.
  • g_error
    Macro used to log using GLib logging system. It uses g_log.
  • g_info
    Macro used to log using GLib logging system. It uses g_log.
  • g_log
    Macro used to log using GLib logging system. It uses g_log.
  • g_message
    Macro used to log using GLib logging system. It uses g_log.
  • g_print
    Macro used to print messages. It uses g_print.
  • g_printerr
    Macro used to print error messages. It uses g_printerr.
  • g_warning
    Macro used to log using GLib logging system. It uses g_log.
  • gformat
    Creates a GString using interpolation of runtime expressions.
  • glib_boxed_inline_wrapper
    Wrapper implementations for BoxedInline types. See wrapper!.
  • glib_boxed_wrapper
    Wrapper implementations for Boxed types. See wrapper!.
  • glib_object_wrapper
    ObjectType implementations for Object types. See wrapper!.
  • glib_shared_wrapper
    Wrapper implementations for shared types. See wrapper!.
  • gstr
    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).
  • log_structured
    Macro used to log using GLib structured logging system.
  • result_from_gboolean
  • 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).
  • wrapper
    Defines a wrapper type and implements the appropriate traits.

Structs

Enums

Constants

  • CLONE_MACRO_LOG_DOMAIN
    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.
  • NONE_STR

Statics

Traits

  • HasParamSpec
  • IntoGStr
    A trait to accept both &str or &GStr as an argument.
  • IntoOptionalGStr
    A trait to accept both Option<&str> or Option<&GStr> as an argument.
  • ParamSpecBuilderExt
    A trait implemented by the various ParamSpec builder types.
  • ParamSpecType
  • Property
    A type that can be used as a property. It covers every type which have an associated ParamSpec (HasParamSpec) and some useful types wrapping HasParamSpec. The definition is recursive, so you can nest many Propertys together. The final ParamSpec will be the one of the innermost type
  • PropertyGet
    A container type implementing this trait can be read by the default getter generated by the Props macro.
  • PropertySet
    A container type implementing this trait can be written by the default setter generated by the Props macro.
  • PropertySetNested
    A container type implementing this trait can be written by the default setter generated by the Props macro. It takes a FnOnce(&mut Self::Value) so that the caller may access nested fields of a struct by doing ${Self::Value}.member

Functions

Type Definitions

Attribute Macros

Derive Macros