Crate glib[][src]

Expand description

Rust GLib and GObject bindings

Rust bindings and wrappers for GLib, part of gtk-rs-core.

GLib 2.48 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.54.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@wrapper] macro, which uses abstractions defined in the [wrapper][mod@wrapper], [boxed][mod@boxed], [shared][mod@shared] and [object][mod@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:

[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 ffi;
pub use gobject_ffi;
pub use self::closure::Closure;
pub use self::error::BoolError;
pub use self::error::Error;
pub use self::object::Cast;
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::SignalHandlerId;
pub use self::types::ILong;
pub use self::types::StaticType;
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::FromVariant;
pub use self::variant::StaticVariantType;
pub use self::variant::ToVariant;
pub use self::variant::Variant;
pub use self::char::*;
pub use self::source::*;
pub use self::send_unique::SendUnique;
pub use self::send_unique::SendUniqueCell;

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.

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.

debuglog_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_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).

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!.

infolog_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).

tracelog_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_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

Binding is the representation of a binding between a property on a Object instance (or source) and another property on another Object instance (or target).

Flags to be passed to [ObjectExtManual::bind_property()][crate::prelude::ObjectExtManual::bind_property()] or [ObjectExtManual::bind_property_full()][crate::prelude::ObjectExtManual::bind_property_full()].

Contains the public fields of a GByteArray.

A shared immutable byte slice (the equivalent of Rc<[u8]>).

An opaque structure representing a checksumming operation.

A CollationKey allows ordering strings using the linguistically correct rules for the current locale.

An opaque structure that represents a date and time, including a time zone.

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.

Flags to pass to file_set_contents_full() to affect its safety and performance.

A test to perform on a file using file_test().

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.

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.

Flags to modify the format of the string returned by format_size_full().

An implementation of a log compatible logger which logs over glib logging facilities.

A bitwise combination representing a condition to watch for on an event source.

The GKeyFile struct contains only private data and should not be accessed directly.

Flags which influence the parsing.

Flags specifying the level of log messages.

The GMainContext struct is an opaque data type representing a set of sources to be handled in a main loop.

The GMainLoop struct is an opaque data type representing the main event loop of a GLib or GTK+ application.

Flags which modify individual options.

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 corresponding Sender or SyncSender.

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.

The GSource struct is an opaque data type representing an event source.

Represents a Future around a glib::Source. The future will be resolved once the source has provided a value

Represents a Stream around a glib::Source. The stream will be provide all values that are provided by the source

Flags passed to g_spawn_sync(), spawn_async() and g_spawn_async_with_pipes().

A mutable text buffer that grows automatically.

A SyncSender that can be used to send items to the corresponding main context receiver.

A value representing an interval of time, in microseconds.

TimeZone is an opaque structure whose members cannot be accessed directly.

The Uri type and related functions can be used to parse URIs into their components, and build valid URIs from individual components.

Flags that describe a URI.

Flags describing what parts of the URI to hide in Uri::to_string_partial(). Note that PASSWORD and AUTH_PARAMS will only work if the Uri was parsed with the corresponding flags.

Flags modifying the way parameters are handled by g_uri_parse_params() and GUriParamsIter.

VariantDict is a mutable key/value store where the keys are always strings and the values are Variants.

Iterator over items in a variant.

Iterator over items in a variant of type as.

Describes Variant types.

Describes Variant types.

Enums

The hashing algorithm to be used by Checksum when performing the digest of some data.

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.

Enumeration of the possible domain handling behaviours for a GlibLogger.

Enumeration of the possible formatting behaviours for a GlibLogger.

Error codes returned by key file parsing.

The OptionArg 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.

Error codes returned by Uri 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.

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

The set of uppercase ASCII alphabet characters. Used for specifying valid identifier characters in GScannerConfig.

The set of ASCII digits. Used for specifying valid identifier characters in GScannerConfig.

The set of lowercase ASCII alphabet characters. Used for specifying valid identifier characters in GScannerConfig.

The name of the main group of a desktop entry file, as defined in the Desktop Entry Specification. Consult the specification for more details about the meanings of the keys below.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a string list giving the available application actions.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a list of strings giving the categories in which the desktop entry should be shown in a menu.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a localized string giving the tooltip for the desktop entry.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true if the application is D-Bus activatable.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a string giving the command line to execute. It is only valid for desktop entries with the Application type.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a localized string giving the generic name of the desktop entry.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a boolean stating whether the desktop entry has been deleted by the user.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a localized string giving the name of the icon to be displayed for the desktop entry.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a list of strings giving the MIME types supported by this desktop entry.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a localized string giving the specific name of the desktop entry.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a list of strings identifying the environments that should not display the desktop entry.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a boolean stating whether the desktop entry should be shown in menus.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a list of strings identifying the environments that should display the desktop entry.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a string containing the working directory to run the program in. It is only valid for desktop entries with the Application type.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a boolean stating whether the application supports the Startup Notification Protocol Specification.

A key under KEY_FILE_DESKTOP_GROUP, whose value is string identifying the WM class or name hint of a window that the application will create, which can be used to emulate Startup Notification with older applications.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a boolean stating whether the program should be run in a terminal window.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a string giving the file name of a binary on disk used to determine if the program is actually installed. It is only valid for desktop entries with the Application type.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a string giving the type of the desktop entry.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a string giving the URL to access. It is only valid for desktop entries with the Link type.

A key under KEY_FILE_DESKTOP_GROUP, whose value is a string giving the version of the Desktop Entry Specification used for the desktop entry file.

The value of the KEY_FILE_DESKTOP_KEY_TYPE, key for desktop entries representing applications.

The value of the KEY_FILE_DESKTOP_KEY_TYPE, key for desktop entries representing directories.

The value of the KEY_FILE_DESKTOP_KEY_TYPE, key for desktop entries representing links to documents.

If a long option in the main group has this name, it is not treated as a regular option. Instead it collects all non-option arguments which would otherwise be left in argv. The option must be of type OptionArg::Callback, OptionArg::StringArray or OptionArg::FilenameArray.

The standard delimiters, used in g_strdelimit().

Creates a unique temporary directory for each unit test and uses g_set_user_dirs() to set XDG directories to point into subdirectories of it for the duration of the unit test. The directory tree is cleaned up after the test finishes successfully. Note that this doesn’t take effect until g_test_run() is called, so calls to (for example) g_get_user_home_dir() will return the system-wide value when made in a test program’s main() function.

Generic delimiters characters as defined in RFC 3986. Includes :/?#[]@.

Subcomponent delimiter characters as defined in RFC 3986. Includes !$&'()*+,;=.

Traits

Functions

Behaves exactly like g_build_filename(), but takes the path elements as a string array, instead of varargs. This function is mainly meant for language bindings.

Behaves exactly like g_build_path(), but takes the path elements as a string array, instead of varargs. This function is mainly meant for language bindings.

Gets the canonical file name from filename. All triple slashes are turned into single slashes, and all .. and .s resolved against relative_to.

Obtain the character set for the current locale.

A wrapper for the POSIX chdir() function. The function changes the current directory of the process to path.

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

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.

os_infov2_64

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.

Gets the smallest prime number from a built-in array of primes which is larger than num. This is used within GLib to calculate the optimum size of a GHashTable.

Executes a child program asynchronously.

spawn_async_with_fdsv2_58 and non-Windows

Executes a child program asynchronously.

Identical to g_spawn_async_with_pipes_and_fds() but with n_fds set to zero, so no FD assignments are used.

An old name for spawn_check_wait_status(), deprecated because its name is misleading.

Set error if wait_status indicates the child exited abnormally (e.g. with a nonzero exit code, or via a fatal signal).

A simple version of spawn_async() that parses a command line with shell_parse_argv() and passes it to spawn_async().

Copies a nul-terminated string into the dest buffer, include the trailing nul, and return a pointer to the trailing nul byte. This is useful for concatenating multiple strings together without having to repeatedly scan for the end.

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.

Similar to the UNIX pipe() call, but on modern systems like Linux uses the pipe2() system call, which atomically creates a pipe with the configured flags. The only supported flag currently is FD_CLOEXEC. If for example you want to configure O_NONBLOCK, that must still be done separately with fcntl().

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

A wrapper for the POSIX unlink() function. The unlink() function deletes a name from the filesystem. If this was the last link to the file and no processes have it opened, the diskspace occupied by the file is freed.

To set the default print handler, use the set_print_handler function.

To set the default print handler, use the set_printerr_handler function.

Removes an environment variable from the environment.

Pauses the current thread for the given number of microseconds.

Parses the string str and verify if it is a UUID.

Generates a random UUID (RFC 4122 version 4) as a string. It has the same randomness guarantees as GRand, so must not be used for cryptographic purposes such as key generation, nonces, salts or one-time pads.

Internal function used to print messages from the public g_warn_if_reached() and g_warn_if_fail() macros.

Type Definitions

Attribute Macros

Attribute macro for defining flags using the bitflags crate. This macro will also define a GFlags::type_ function and the glib::Value traits.

Macro for boilerplate of ObjectInterface implementations.

Macro for boilerplate of ObjectSubclass implementations.

Derive Macros

Macro for deriving implementations of glib::clone::Downgrade and glib::clone::Upgrade traits and a weak type.

Derive macro for defining a BoxedType::type_ function and the glib::Value traits.

Derive macro for defining a GLib error domain and its associated ErrorDomain trait.

Derive macro for defining a SharedType::get_type function and the glib::Value traits.