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.64.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
.
Variant
s 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
pub use ffi;
pub use gobject_ffi;
pub use self::closure::Closure;
pub use self::closure::RustClosure;
pub use self::error::BoolError;
pub use self::error::Error;
pub use self::object::BorrowedObject;
pub use self::object::Cast;
pub use self::object::CastNone;
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::Pointer;
pub use self::types::StaticType;
pub use self::types::StaticTypeExt;
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::FixedSizeVariantArray;
pub use self::variant::FixedSizeVariantType;
pub use self::variant::FromVariant;
pub use self::variant::StaticVariantType;
pub use self::variant::ToVariant;
pub use self::variant::Variant;
pub use collections::ptr_slice::IntoPtrSlice;
pub use collections::strv::IntoStrV;
pub use collections::List;
pub use collections::PtrSlice;
pub use collections::SList;
pub use collections::Slice;
pub use collections::StrV;
pub use collections::StrVItem;
pub use self::char::*;
pub use self::source::*;
Modules
IMPL
Boxed wrapper implementation.IMPL
BoxedInline wrapper implementation.Error
binding and helper trait.IMPL
Object wrapper implementation and Object
binding.IMPL
Shared (reference counted) wrapper implementation.IMPL
Low level signal support.GObject
s and registering boxed types.Value
binding and helper traits.Variant
binding and helper traits.IMPL
The wrapper!
macro and miscellaneous wrapper traits.Macros
Closure
object. This is a wrapper around Closure::new
that
automatically type checks its arguments at run-time.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.log_macros
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).log_macros
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).std::any::type_name
, this macro derives
all the limitations of this function.wrapper!
.wrapper!
.wrapper!
.wrapper!
.log_macros
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_macros
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).log_macros
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).Structs
ObjectExt::bind_property()
or
[ObjectExt::bind_property_full()
][crate::prelude::ObjectExt::bind_property_full()].v2_72
BindingGroup
can be used to bind multiple properties
from an object collectively.v2_72
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.Rc<[u8]>
).CollationKey
allows ordering strings using the linguistically correct rules for the current locale.enum
for dynamically, at runtime, querying the values of the enum and
using them.EnumClass
.v2_66
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.Value
.flags
for dynamically, at runtime, querying the values of the enum and
using themFlagsClass
.log
compatible
logger which logs over glib logging facilities.JoinHandle
.MainContext
.v2_72
ParamFlags
flag values, certain aspects of parameters
can be configured.Receiver
that can be attached to a main context to receive items from its corresponding
Sender
or SyncSender
.Sender
that can be used to send items to the corresponding main context receiver.v2_74
SignalGroup
manages to simplify the process of connecting
many signals to a Object
as a group. As such there is no API
to disconnect a signal from the group.Future
around a glib::Source
. The future will
be resolved once the source has provided a valueStream
around a glib::Source
. The stream will
be provide all values that are provided by the sourceJoinHandle
that is returned from MainContext::spawn_from_within
.SyncSender
that can be used to send items to the corresponding main context receiver.ThreadPool
.v2_66
v2_66
v2_66
v2_66
VariantDict
is a mutable key/value store where the keys are always
strings and the values are Variant
s.as
.Variant
types.Variant
types.Enums
ConvertError
that can hold an offset into the input
string.GString
.GlibLogger
.GlibLogger
.std::io::Error
that can hold an offset into an input string.v2_66
Variant
instances.Constants
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
GScannerConfig
.GScannerConfig
.GScannerConfig
.KEY_FILE_DESKTOP_GROUP
, whose value is a string list
giving the available application actions.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.KEY_FILE_DESKTOP_GROUP
, whose value is a localized
string giving the tooltip for the desktop entry.KEY_FILE_DESKTOP_GROUP
, whose value is a boolean
set to true if the application is D-Bus activatable.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.KEY_FILE_DESKTOP_GROUP
, whose value is a localized
string giving the generic name of the desktop entry.KEY_FILE_DESKTOP_GROUP
, whose value is a boolean
stating whether the desktop entry has been deleted by the user.KEY_FILE_DESKTOP_GROUP
, whose value is a localized
string giving the name of the icon to be displayed for the desktop
entry.KEY_FILE_DESKTOP_GROUP
, whose value is a list
of strings giving the MIME types supported by this desktop entry.KEY_FILE_DESKTOP_GROUP
, whose value is a localized
string giving the specific name of the desktop entry.KEY_FILE_DESKTOP_GROUP
, whose value is a list of
strings identifying the environments that should not display the
desktop entry.KEY_FILE_DESKTOP_GROUP
, whose value is a boolean
stating whether the desktop entry should be shown in menus.KEY_FILE_DESKTOP_GROUP
, whose value is a list of
strings identifying the environments that should display the
desktop entry.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.KEY_FILE_DESKTOP_GROUP
, whose value is a boolean
stating whether the application supports the
Startup Notification Protocol Specification.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.KEY_FILE_DESKTOP_GROUP
, whose value is a boolean
stating whether the program should be run in a terminal window.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.KEY_FILE_DESKTOP_GROUP
, whose value is a string
giving the type of the desktop entry.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.KEY_FILE_DESKTOP_GROUP
, whose value is a string
giving the version of the Desktop Entry Specification used for
the desktop entry file.KEY_FILE_DESKTOP_KEY_TYPE
, key for desktop
entries representing applications.KEY_FILE_DESKTOP_KEY_TYPE
, key for desktop
entries representing directories.KEY_FILE_DESKTOP_KEY_TYPE
, key for desktop
entries representing links to documents.argv
. The option must be of type
OptionArg::Callback
, OptionArg::StringArray
or OptionArg::FilenameArray
.g_strdelimit()
.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.:/?#[]@
.!$&'()*+,;=
.Traits
ParamSpec
builder types.Functions
Future
that will resolve once the child process with the given pid exitsFuture
that will resolve once the child process with the given pid exitsv2_62
Future
.Future
.Stream
that will provide a value every given number of milliseconds.Stream
that will provide a value every given number of seconds.Stream
that will provide a value every given number of seconds.Stream
that will provide a value every given number of milliseconds.log_unset_default_handler
function.log_set_default_handler
function.v2_64
get_prgname()
.log crate
.unset_print_handler
function.unset_printerr_handler
function.set_prgname()
.unquoted_string
.num
. This is used within GLib to calculate the optimum
size of a GHashTable
.v2_58
and non-Windowsspawn_check_wait_status()
, deprecated because its
name is misleading.error
if wait_status
indicates the child exited abnormally
(e.g. with a nonzero exit code, or via a fatal signal).spawn_async()
that parses a command line with
shell_parse_argv()
and passes it to spawn_async()
.Future
that will resolve after the given number of milliseconds.Future
that will resolve after the given number of seconds.Future
that will resolve after the given number of seconds.Future
that will resolve after the given number of milliseconds.iso15924
. ISO 15924 assigns four-letter
codes to scripts. For example, the code for Arabic is ‘Arab’.
This function accepts four letter codes encoded as a guint32
in a
big-endian fashion. That is, the code expected for Arabic is
0x41726162 (0x41 is ASCII code for ‘A’, 0x72 is ASCII code for ‘r’, etc).script
. ISO 15924 assigns four-letter
codes to scripts. For example, the code for Arabic is ‘Arab’. The
four letter codes are encoded as a guint32
by this function in a
big-endian fashion. That is, the code returned for Arabic is
0x41726162 (0x41 is ASCII code for ‘A’, 0x72 is ASCII code for ‘r’, etc).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()
.Future
that will resolve once the given UNIX signal is raisedFuture
that will resolve once the given UNIX signal is raisedStream
that will provide a value whenever the given UNIX signal is raisedStream
that will provide a value whenever the given UNIX signal is raisedunlink()
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.set_print_handler
function.set_printerr_handler
function.v2_72
str
and verify if it is a UUID.GRand
, so must not be used for cryptographic
purposes such as key generation, nonces, salts or one-time pads.Type Definitions
Attribute Macros
bitflags
crate.
This macro will also define a GFlags::type_
function and
the glib::Value
traits.ObjectInterface
implementations.ObjectSubclass
implementations.Derive Macros
glib::clone::Downgrade
and
glib::clone::Upgrade
traits and a weak type.glib::Value
traits.ErrorDomain
trait.glib::Variant
s.