# Crate glib [−] [src]

# glib, gobject and gio bindings for Rust

This library contains

- bindings to some essential GLib, GObject, GIO types and APIs,

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

The library is a work in progress: expect missing functionality and breaking changes.

# Dynamic typing

Most types in the GLib family have type identifiers (`Type`). Their corresponding Rust types implement the `StaticType` trait.

Dynamically typed `Value` can carry values of any `T: StaticType`.

`Variant` can carry values of `T: 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`, `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 iff 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` and `gtk::WidgetExt`), which are blanketly implemented for all their subtypes.

# 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 `glib_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.

## Reexports

`pub use closure::Closure;`
`pub use error::Error;`
`pub use error::BoolError;`
`pub use object::Cast;`
`pub use object::IsA;`
`pub use object::Object;`
`pub use object::ObjectExt;`
`pub use object::WeakRef;`
`pub use signal::signal_handler_block;`
`pub use signal::signal_handler_unblock;`
`pub use signal::signal_stop_emission;`
`pub use signal::signal_stop_emission_by_name;`
`pub use types::StaticType;`
`pub use types::Type;`
`pub use value::ToValue;`
`pub use value::TypedValue;`
`pub use value::Value;`
`pub use variant::StaticVariantType;`
`pub use variant::ToVariant;`
`pub use variant::Variant;`
`pub use source::*;`

## Modules

boxed | `IMPL` Boxed wrapper implementation.
closure |
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 |
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 `glib_wrapper!` macro and miscellaneous wrapper traits.

## Macros

glib_boxed_wrapper | Wrapper implementations for Boxed types. See `glib_wrapper!`.
glib_object_wrapper | Wrapper implementations for Object types. See `glib_wrapper!`.
glib_shared_wrapper | Wrapper implementations for shared types. See `glib_wrapper!`.
glib_wrapper | Defines a wrapper type and implements the appropriate traits.

## Structs

Bytes | A shared immutable byte slice (the equivalent of `Rc<[u8]>`).
Checksum |
Date |
DateTime |
EnumClass | Representation of an `enum` for dynamically, at runtime, querying the values of the enum and using them.
EnumValue | Representation of a single enum value of an `EnumClass`.
FlagsBuilder | Builder for conveniently setting/unsetting flags and returning a `Value`.
FlagsClass | Representation of a `flags` for dynamically, at runtime, querying the values of the enum and using them
FlagsValue | Representation of a single flags value of a `FlagsClass`.
FormatSizeFlags |
KEY_FILE_DESKTOP_GROUP |
KEY_FILE_DESKTOP_KEY_ACTIONS |
KEY_FILE_DESKTOP_KEY_CATEGORIES |
KEY_FILE_DESKTOP_KEY_COMMENT |
KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE |
KEY_FILE_DESKTOP_KEY_EXEC |
KEY_FILE_DESKTOP_KEY_FULLNAME |
KEY_FILE_DESKTOP_KEY_GENERIC_NAME |
KEY_FILE_DESKTOP_KEY_GETTEXT_DOMAIN |
KEY_FILE_DESKTOP_KEY_HIDDEN |
KEY_FILE_DESKTOP_KEY_ICON |
KEY_FILE_DESKTOP_KEY_KEYWORDS |
KEY_FILE_DESKTOP_KEY_MIME_TYPE |
KEY_FILE_DESKTOP_KEY_NAME |
KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN |
KEY_FILE_DESKTOP_KEY_NO_DISPLAY |
KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN |
KEY_FILE_DESKTOP_KEY_PATH |
KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY |
KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS |
KEY_FILE_DESKTOP_KEY_TERMINAL |
KEY_FILE_DESKTOP_KEY_TRY_EXEC |
KEY_FILE_DESKTOP_KEY_TYPE |
KEY_FILE_DESKTOP_KEY_URL |
KEY_FILE_DESKTOP_KEY_VERSION |
KEY_FILE_DESKTOP_TYPE_APPLICATION |
KEY_FILE_DESKTOP_TYPE_DIRECTORY |
KEY_FILE_DESKTOP_TYPE_LINK |
KeyFile |
KeyFileFlags |
MainContext |
MainLoop |
Source |
TimeVal |
TimeZone |
VariantTy | Describes `Variant` types.
VariantType | Describes `Variant` types.

## Enums

ChecksumType |
DateMonth |
DateWeekday |
FileError |
KeyFileError |
TimeType |
UserDirectory |

## Constants

FORMAT_SIZE_DEFAULT |
FORMAT_SIZE_IEC_UNITS |
FORMAT_SIZE_LONG_FORMAT |
KEY_FILE_KEEP_COMMENTS |
KEY_FILE_KEEP_TRANSLATIONS |
KEY_FILE_NONE |

## Functions

access |
assert_warning |
assertion_message |
assertion_message_cmpstr |
assertion_message_expr |
base64_decode |
base64_encode |
basename |
bit_nth_lsf |
bit_nth_msf |
bit_storage |
build_filenamev |
build_pathv |
chdir |
check_version |
clear_error |
compute_checksum_for_data |
compute_checksum_for_string |
compute_hmac_for_data |
compute_hmac_for_string |
dcgettext |
dgettext |
dngettext |
dpgettext |
dpgettext2 |
environ_getenv |
environ_setenv |
environ_unsetenv |
file_get_contents |
file_open_tmp |
file_read_link |
file_set_contents |
filename_display_basename |
filename_display_name |
filename_from_uri |
filename_to_uri |
find_program_in_path |
format_size |
format_size_for_display |
format_size_full |
get_application_name |
get_charset |
get_codeset |
get_current_dir |
get_current_time |
get_environ |
get_home_dir |
get_host_name |
get_language_names |
get_locale_variants |
get_monotonic_time |
get_prgname |
get_program_name | Same as `get_prgname()`.
get_real_name |
get_real_time |
get_system_config_dirs |
get_system_data_dirs |
get_tmp_dir |
get_user_cache_dir |
get_user_config_dir |
get_user_data_dir |
get_user_name |
get_user_runtime_dir |
get_user_special_dir |
getenv |
hostname_is_ascii_encoded |
hostname_is_ip_address |
hostname_is_non_ascii |
hostname_to_ascii |
hostname_to_unicode |
intern_static_string |
intern_string |
listenv |
log_remove_handler |
main_current_source |
main_depth |
mem_is_system_malloc |
mem_profile |
mkdir_with_parents |
mkdtemp |
mkdtemp_full |
mkstemp |
mkstemp_full |
on_error_query |
on_error_stack_trace |
path_get_basename |
path_get_dirname |
path_is_absolute |
path_skip_root |
pattern_match_simple |
random_double |
random_double_range |
random_int |
random_int_range |
random_set_seed |
reload_user_special_dirs_cache |
return_if_fail_warning |
rmdir |
set_application_name |
set_prgname |
set_program_name | Same as `set_prgname()`.
setenv |
shell_parse_argv |
shell_quote |
shell_unquote |
spaced_primes_closest |
spawn_command_line_async |
stpcpy |
test_assert_expected_messages_internal |
test_bug |
test_bug_base |
test_fail |
test_rand_double |
test_rand_double_range |
test_rand_int |
test_rand_int_range |
test_run |
test_timer_elapsed |
test_timer_last |
test_timer_start |
test_trap_assertions |
test_trap_has_passed |
test_trap_reached_timeout |
unix_set_fd_nonblocking |
unlink |
unsetenv |
uri_escape_string |
uri_list_extract_uris |
uri_parse_scheme |
uri_unescape_segment |
uri_unescape_string |
usleep |
variant_get_gtype |
warn_message |

## Type Definitions

DateDay |
DateYear |
Time |
TimeSpan |

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
↑
  Move up in search results
↓
  Move down in search results
↹
  Switch tab
⏎
  Go to active search result
+ / -
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)