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.80.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 gtk4::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 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
  • enums
  • error
    Error binding and helper trait.
  • match_info
  • object
    IMPL Object wrapper implementation and Object binding.
  • prelude
    Traits and essential types intended for blanket imports.
  • property
  • regex
    This module is inefficient and should not be used by Rust programs except for compatibility with GLib.Regex based APIs.
  • 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§

  • Binding
    GObject instance (or source) and another property on another GObject instance (or target).
  • BindingFlags
    Flags to be passed to ObjectExt::bind_property() or [ObjectExt::bind_property_full()][crate::prelude::ObjectExt::bind_property_full()].
  • BindingGroupv2_72
    GBindingGroup can be used to bind multiple properties from an object collectively.
  • BindingGroupBuilderv2_72
    Builder for binding group bindings.
  • BoxedAnyObject
    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.
  • ByteArray
    Contains the public fields of a GByteArray. Contains the public fields of a GByteArray.
  • Bytes
    A shared immutable byte slice (the equivalent of Rc<[u8]>).
  • Checksum
    GLib provides a generic API for computing checksums (or ‘digests’) for a sequence of arbitrary bytes, using various hashing algorithms like MD5, SHA-1 and SHA-256. Checksums are commonly used in various environments and specifications.
  • CollationKey
    A CollationKey allows ordering strings using the linguistically correct rules for the current locale.
  • Date
    GLib type: Inline allocated boxed type with stack copy semantics.
  • DateTime
    GDateTime is a structure that combines a Gregorian date and time into a single structure.
  • ExitCode
  • FileSetContentsFlagsv2_66
    Flags to pass to g_file_set_contents_full() to affect its safety and performance.
  • FilenameCollationKey
    A 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.
  • FormatSizeFlags
    Flags to modify the format of the string returned by g_format_size_full().
  • FutureWithTimeoutError
    The error returned when a future times out.
  • GStr
    Representation of a borrowed GString.
  • GStrInteriorNulError
    Error type indicating that a buffer had unexpected nul-bytes.
  • GString
    A type representing an owned, C-compatible, nul-terminated UTF-8 string.
  • GStringBuilder
    A mutable text buffer that grows automatically.
  • GStringInteriorNulError
    Error type indicating that a buffer had unexpected nul-bytes.
  • GStringNoTrailingNulError
    Error type indicating that a buffer did not have a trailing nul-byte.
  • GStringPtr
    NULL-terminated UTF-8 string as stored in StrV.
  • GStringUtf8Error
    Error type indicating that a buffer had invalid UTF-8.
  • GlibLoggerlog
    An implementation of a log compatible logger which logs over glib logging facilities.
  • IConv
    The GIConv struct wraps an iconv() conversion descriptor. It contains private data and should only be accessed using the following functions. The GIConv struct wraps an iconv() conversion descriptor. It contains private data and should only be accessed using the following functions.
  • IOCondition
    A bitwise combination representing a condition to watch for on an event source.
  • InterfaceInfo
    A structure that provides information to the type system which is used specifically for managing interface types. A structure that provides information to the type system which is used specifically for managing interface types.
  • JoinError
    Task failure from awaiting a JoinHandle.
  • JoinHandle
    A handle to a task running on a MainContext.
  • KeyFile
    GKeyFile parses .ini-like config files.
  • KeyFileFlags
    Flags which influence the parsing.
  • LogField
    Structure representing a single field in a structured log entry.
  • LogHandlerId
  • LogLevelFlags
    Flags specifying the level of log messages.
  • LogLevels
  • MainContext
    The GMainContext struct is an opaque data type representing a set of sources to be handled in a main loop. The GMainContext struct is an opaque data type representing a set of sources to be handled in a main loop.
  • MainContextAcquireGuard
  • MainContextFlagsv2_72
    Flags to pass to GLib::MainContext::new_with_flags() which affect the behaviour of a MainContext.
  • MainLoop
    The GMainLoop struct is an opaque data type representing the main event loop of a GLib or GTK application. The GMainLoop struct is an opaque data type representing the main event loop of a GLib or GTK application.
  • MarkupParseContext
    A parse context is used to parse a stream of bytes that you expect to contain marked-up text.
  • OptionFlags
    Flags which modify individual options.
  • ParamFlags
    Through the ParamFlags flag values, certain aspects of parameters can be configured.
  • ParamSpec
    GParamSpec encapsulates the metadata required to specify parameters, such as GObject properties.
  • ParamSpecBoolean
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecBooleanBuilder
  • ParamSpecBoxed
    A ParamSpec derived structure that contains the meta data for boxed properties. A ParamSpec derived structure that contains the meta data for boxed properties.
  • ParamSpecBoxedBuilder
  • ParamSpecChar
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecCharBuilder
  • ParamSpecDouble
    A ParamSpec derived structure that contains the meta data for double properties. A ParamSpec derived structure that contains the meta data for double properties.
  • ParamSpecDoubleBuilder
  • ParamSpecEnum
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecEnumBuilder
  • ParamSpecFlags
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecFlagsBuilder
  • ParamSpecFloat
    A ParamSpec derived structure that contains the meta data for float properties. A ParamSpec derived structure that contains the meta data for float properties.
  • ParamSpecFloatBuilder
  • ParamSpecGType
    A ParamSpec derived structure that contains the meta data for GType properties. A ParamSpec derived structure that contains the meta data for GType properties.
  • ParamSpecGTypeBuilder
  • ParamSpecInt
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecInt64
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecInt64Builder
  • ParamSpecIntBuilder
  • ParamSpecLong
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecLongBuilder
  • ParamSpecObject
    A ParamSpec derived structure that contains the meta data for object properties. A ParamSpec derived structure that contains the meta data for object properties.
  • ParamSpecObjectBuilder
  • ParamSpecOverride
    A ParamSpec derived structure that redirects operations to other types of ParamSpec.
  • ParamSpecOverrideBuilder
  • ParamSpecParam
    A ParamSpec derived structure that contains the meta data for G_TYPE_PARAM properties. A ParamSpec derived structure that contains the meta data for G_TYPE_PARAM properties.
  • ParamSpecParamBuilder
  • ParamSpecPointer
    A ParamSpec derived structure that contains the meta data for pointer properties. A ParamSpec derived structure that contains the meta data for pointer properties.
  • ParamSpecPointerBuilder
  • ParamSpecString
    A ParamSpec derived structure that contains the meta data for string properties. A ParamSpec derived structure that contains the meta data for string properties.
  • ParamSpecStringBuilder
  • ParamSpecUChar
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecUCharBuilder
  • ParamSpecUInt
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecUInt64
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecUInt64Builder
  • ParamSpecUIntBuilder
  • ParamSpecULong
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecULongBuilder
  • ParamSpecUnichar
    GLib type: Shared boxed type with reference counted clone semantics.
  • ParamSpecUnicharBuilder
  • ParamSpecValueArray
    A ParamSpec derived structure that contains the meta data for GValueArray properties. A ParamSpec derived structure that contains the meta data for GValueArray properties.
  • ParamSpecValueArrayBuilder
  • ParamSpecVariant
    A ParamSpec derived structure that contains the meta data for GVariant properties.
  • ParamSpecVariantBuilder
  • Quark
  • Regex
    A GRegex is the “compiled” form of a regular expression pattern.
  • RegexCompileFlags
    Flags specifying compile-time options.
  • RegexMatchFlags
    Flags specifying match-time options.
  • SignalFlags
    The signal flags are used to specify a signal’s behaviour. The signal flags are used to specify a signal’s behaviour.
  • SignalGroupv2_74
    GSignalGroup manages a collection of signals on a GObject.
  • Source
    The GSource struct is an opaque data type representing an event source. The GSource struct is an opaque data type representing an event source.
  • SourceFuture
    Represents a Future around a glib::Source. The future will be resolved once the source has provided a value
  • SourceStream
    Represents a Stream around a glib::Source. The stream will be provide all values that are provided by the source
  • SpawnFlags
    Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().
  • SpawnWithinJoinHandle
    Variant of JoinHandle that is returned from MainContext::spawn_from_within.
  • ThreadHandle
    A handle to a thread running on a ThreadPool.
  • ThreadPool
    The GThreadPool struct represents a thread pool.
  • TimeSpan
    A value representing an interval of time, in microseconds.
  • TimeZone
    A GTimeZone represents a time zone, at no particular point in time.
  • TypeFlags
    Bit masks used to check or determine characteristics of a type. Bit masks used to check or determine characteristics of a type.
  • TypeInfo
    This structure is used to provide the type system with the information required to initialize and destruct (finalize) a type’s class and its instances.
  • TypeModule
    GTypeModule provides a simple implementation of the GTypePlugin interface.
  • TypePlugin
    An interface that handles the lifecycle of dynamically loaded types.
  • TypeValueTable
    The TypeValueTable provides the functions required by the Value implementation, to serve as a container for values of a type. The TypeValueTable provides the functions required by the Value implementation, to serve as a container for values of a type.
  • Uriv2_66
    The GUri type and related functions can be used to parse URIs into their components, and build valid URIs from individual components.
  • UriFlagsv2_66
    Flags that describe a URI.
  • UriHideFlagsv2_66
    Flags describing what parts of the URI to hide in g_uri_to_string_partial(). Note that PASSWORD and AUTH_PARAMS will only work if the #GUri was parsed with the corresponding flags.
  • UriParamsFlagsv2_66
    Flags modifying the way parameters are handled by g_uri_parse_params() and #GUriParamsIter.
  • ValueArray
    GLib type: Boxed type with copy-on-clone semantics.
  • VariantDict
    VariantDict is a mutable key/value store where the keys are always strings and the values are Variants.
  • VariantIter
    Iterator over items in a variant.
  • VariantStrIter
    Iterator over items in a variant of type as.
  • VariantTy
    Describes Variant types.
  • VariantTyIterator
    An iterator over the individual components of a tuple VariantTy.
  • VariantType
    Describes Variant types.

Enums§

  • CharacterDecomposition
    The result of a single step of the Unicode canonical decomposition algorithm
  • ChecksumType
    The hashing algorithm to be used by #GChecksum when performing the digest of some data.
  • ControlFlow
    Continue calling the closure in the future iterations or drop it.
  • ConvertError
    Error codes returned by character set conversion routines.
  • CvtError
    A wrapper for ConvertError that can hold an offset into the input string.
  • DateMonth
    Enumeration representing a month; values are January, February, etc. BadMonth is the invalid value.
  • DateWeekday
    Enumeration representing a day of the week; Monday, Tuesday, etc. BadWeekday is an invalid weekday.
  • DecompositionKind
    The kind of decomposition to perform
  • FileError
    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.
  • GStrError
    Error type holding all possible failures when creating a GStr reference.
  • GStringFromError
    Error type holding all possible failures when creating a GString.
  • GlibLoggerDomainlog
    Enumeration of the possible domain handling behaviours for a GlibLogger.
  • GlibLoggerFormatlog
    Enumeration of the possible formatting behaviours for a GlibLogger.
  • IConvError
    A wrapper for std::io::Error that can hold an offset into an input string.
  • KeyFileError
    Error codes returned by key file parsing.
  • LogLevel
  • LogWriterOutput
    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).
  • MarkupError
    Error codes returned by markup parsing.
  • NormalizeMode
    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.
  • OptionArg
    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.
  • SeekType
    An enumeration specifying the base position for a g_io_channel_seek_position() operation.
  • TimeType
    Disambiguates a given time in two ways.
  • UnicodeBreakType
    These are the possible line break classifications.
  • UnicodeScript
    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.
  • UnicodeType
    These are the possible character classifications from the Unicode specification. See Unicode Character Database.
  • UriErrorv2_66
    Error codes returned by #GUri methods.
  • VariantClass
    The range of possible top-level types of #GVariant instances.

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§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§