`IMPL` Boxed wrapper implementation.
Wrapper implementations for Boxed types. See `glib_wrapper!`.
Memory management functions for a boxed type.
Makes a copy.
Frees the object.
Encapsulates memory management logic for boxed types.
A shared immutable byte slice (the equivalent of `Rc<[u8]>`).
`From` implementations that take references (e.g. `&[u8]`) copy the
data. The `from_static` constructor avoids copying static data.
```
use glib::Bytes;
let v = vec![1, 2, 3];
let b = Bytes::from(&v);
assert_eq!(v, b);
let s = b"xyz";
let b = Bytes::from_static(s);
assert_eq!(&s[..], b);
```
Copies `data` into a new shared slice.
Creates a view into static `data` without copying.
Representation of an `enum` for dynamically, at runtime, querying the values of the enum and
using them.
Create a new `EnumClass` from a `Type`.
Returns `None` if `type_` is not representing an enum.
`Type` of the enum.
Gets `EnumValue` by integer `value`, if existing.
Returns `None` if the enum does not contain any value
with `value`.
Gets `EnumValue` by string name `name`, if existing.
Returns `None` if the enum does not contain any value
with name `name`.
Gets `EnumValue` by string nick `nick`, if existing.
Returns `None` if the enum does not contain any value
with nick `nick`.
Gets all `EnumValue` of this `EnumClass`.
Converts integer `value` to a `Value`, if part of the enum.
Converts string name `name` to a `Value`, if part of the enum.
Converts string nick `nick` to a `Value`, if part of the enum.
Representation of a single enum value of an `EnumClass`.
Get integer value corresponding to the value.
Get name corresponding to the value.
Get nick corresponding to the value.
Convert enum value to a `Value`.
Convert enum value from a `Value`.
Get `EnumClass` to which the enum value belongs.
Representation of a `flags` for dynamically, at runtime, querying the values of the enum and
using them
Create a new `FlagsClass` from a `Type`
Returns `None` if `type_` is not representing a flags type.
`Type` of the flags.
Gets `FlagsValue` by integer `value`, if existing.
Returns `None` if the flags do not contain any value
with `value`.
Gets `FlagsValue` by string name `name`, if existing.
Returns `None` if the flags do not contain any value
with name `name`.
Gets `FlagsValue` by string nick `nick`, if existing.
Returns `None` if the flags do not contain any value
with nick `nick`.
Gets all `FlagsValue` of this `FlagsClass`.
Converts integer `value` to a `Value`, if part of the flags.
Converts string name `name` to a `Value`, if part of the flags.
Converts string nick `nick` to a `Value`, if part of the flags.
Checks if the flags corresponding to integer `f` is set in `value`.
Checks if the flags corresponding to string name `name` is set in `value`.
Checks if the flags corresponding to string nick `nick` is set in `value`.
Sets flags value corresponding to integer `f` in `value`, if part of that flags. If the
flag is already set, it will succeed without doing any changes.
Returns `Ok(value)` with the flag set if successful, or `Err(value)` with the original
value otherwise.
Sets flags value corresponding to string name `name` in `value`, if part of that flags.
If the flag is already set, it will succeed without doing any changes.
Returns `Ok(value)` with the flag set if successful, or `Err(value)` with the original
value otherwise.
Sets flags value corresponding to string nick `nick` in `value`, if part of that flags.
If the flag is already set, it will succeed without doing any changes.
Returns `Ok(value)` with the flag set if successful, or `Err(value)` with the original
value otherwise.
Unsets flags value corresponding to integer `f` in `value`, if part of that flags.
If the flag is already unset, it will succeed without doing any changes.
Returns `Ok(value)` with the flag unset if successful, or `Err(value)` with the original
value otherwise.
Unsets flags value corresponding to string name `name` in `value`, if part of that flags.
If the flag is already unset, it will succeed without doing any changes.
Returns `Ok(value)` with the flag unset if successful, or `Err(value)` with the original
value otherwise.
Unsets flags value corresponding to string nick `nick` in `value`, if part of that flags.
If the flag is already unset, it will succeed without doing any changes.
Returns `Ok(value)` with the flag unset if successful, or `Err(value)` with the original
value otherwise.
Returns a new `FlagsBuilder` for conveniently setting/unsetting flags
and building a `Value`.
Returns a new `FlagsBuilder` for conveniently setting/unsetting flags
and building a `Value`. The `Value` is initialized with `value`.
Representation of a single flags value of a `FlagsClass`.
Get integer value corresponding to the value.
Get name corresponding to the value.
Get nick corresponding to the value.
Convert flags value to a `Value`.
Convert flags values from a `Value`. This returns all flags that are set.
Get `FlagsClass` to which the flags value belongs.
Builder for conveniently setting/unsetting flags and returning a `Value`.
Example for getting a flags property, unsetting some flags and setting the updated flags on the
object again:
```ignore
let flags = obj.get_property("flags").unwrap();
let flags_class = FlagsClass::new(flags.type_()).unwrap();
let flags = flags_class.builder_with_value(flags).unwrap()
.unset_by_nick("some-flag")
.unset_by_nick("some-other-flag")
.build()
.unwrap();
obj.set_property("flags", &flags).unwrap();
```
If setting/unsetting any value fails, `build()` returns `None`.
Sets flags corresponding to integer value `f`.
Sets flags corresponding to string name `name`.
Sets flags corresponding to string nick `nick`.
Unsets flags corresponding to integer value `f`.
Unsets flags corresponding to string name `name`.
Unsets flags corresponding to string nick `nick`.
Converts to the final `Value`, unless any previous setting/unsetting of flags failed.
`Error` binding and helper trait.
A generic error capable of representing various error domains (types).
Creates an error with supplied error enum variant and message.
Checks if the error domain matches `T`.
Tries to convert to a specific error enum.
Returns `Some` if the error belongs to the enum's error domain and
`None` otherwise.
# Examples
```ignore
if let Some(file_error) = error.kind::<FileError>() {
match file_error {
FileError::Exist => ...
FileError::Isdir => ...
...
}
}
```
```ignore
match error {
Some(FileError::Exist) => ...
Some(FileError::Isdir) => ...
...
}
```
`GLib` error domain.
This trait is implemented by error enums that represent error domains (types).
Returns the quark identifying the error domain.
As returned from `g_some_error_quark`.
Gets the integer representation of the variant.
Tries to convert an integer code to an enum variant.
By convention, the `Failed` variant, if present, is a catch-all,
i.e. any unrecognized codes map to it.
Generic error used for functions that fail without any further information
# **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`](types/enum.Type.html)). Their corresponding Rust types implement
the [`StaticType`](types/trait.StaticType.html) trait.
Dynamically typed [`Value`](value/index.html) can carry values of any `T:
StaticType`.
[`Variant`](variant/index.html) can carry values of `T: StaticVariantType`.
# Errors
Errors are represented by [`Error`](error/struct.Error.html), which can
carry values from various [error
domains](error/trait.ErrorDomain.html#implementors) (such as
[`FileError`](enum.FileError.html)).
# 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`](object/struct.Object.html).
Inheritance and subtyping is denoted with the [`IsA`](object/trait.IsA.html)
marker trait. The [`Cast`](object/trait.Cast.html) 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.glib_wrapper!.html) macro, which uses abstractions
defined in the [`wrapper`](wrapper/index.html), [`boxed`](boxed/index.html),
[`shared`](shared/index.html) and [`object`](object/index.html) modules.
The [`translate`](translate/index.html) module defines and partly implements
conversions between high level Rust types (including the aforementioned
wrappers) and their FFI counterparts.
`IMPL` Object wrapper implementation and `Object` binding.
Upcasting and downcasting support.
Provides conversions up and down the class hierarchy tree.
Upcasts an object to a superclass or interface `T`.
*NOTE*: This statically checks at compile-time if casting is possible. It is not always
known at compile-time, whether a specific object implements an interface or not, in which case
`upcast` would fail to compile. `dynamic_cast` can be used in these circumstances, which
is checking the types at runtime.
# Example
```ignore
let button = gtk::Button::new();
let widget = button.upcast::<gtk::Widget>();
```
Tries to downcast to a subclass or interface implementor `T`.
Returns `Ok(T)` if the object is an instance of `T` and `Err(self)`
otherwise.
*NOTE*: This statically checks at compile-time if casting is possible. It is not always
known at compile-time, whether a specific object implements an interface or not, in which case
`upcast` would fail to compile. `dynamic_cast` can be used in these circumstances, which
is checking the types at runtime.
# Example
```ignore
let button = gtk::Button::new();
let widget = button.upcast::<gtk::Widget>();
assert!(widget.downcast::<gtk::Button>().is_ok());
```
Returns `true` if the object is an instance of (can be cast to) `T`.
Tries to cast to an object of type `T`. This handles upcasting, downcasting
and casting between interface and interface implementors. All checks are performed at
runtime, while `downcast` and `upcast` will do many checks at compile-time already.
It is not always known at compile-time, whether a specific object implements an interface or
not, and checking as to be performed at runtime.
Returns `Ok(T)` if the object is an instance of `T` and `Err(self)`
otherwise.
# Example
```ignore
let button = gtk::Button::new();
let widget = button.dynamic_cast::<gtk::Widget>();
assert!(widget.is_ok);
let widget = widget.unwrap();
assert!(widget.dynamic_cast::<gtk::Button>().is_ok());
```
Declares the "is a" relationship.
`Self` is said to implement `T`.
For instance, since originally `GtkWidget` is a subclass of `GObject` and
implements the `GtkBuildable` interface, `gtk::Widget` implements
`IsA<glib::Object>` and `IsA<gtk::Buildable>`.
The trait can only be implemented if the appropriate `ToGlibPtr`
implementations exist.
`T` always implements `IsA<T>`.
Downcasts support.
Checks if it's possible to downcast to `T`.
Returns `true` if the instance implements `T` and `false` otherwise.
Tries to downcast to `T`.
Returns `Ok(T)` if the instance implements `T` and `Err(Self)` otherwise.
Downcasts to `T` unconditionally.
Panics if compiled with `debug_assertions` and the instance doesn't implement `T`.
Wrapper implementations for Object types. See `glib_wrapper!`.
Traits and essential types intended for blanket imports.
`IMPL` Shared (reference counted) wrapper implementation.
Wrapper implementations for shared types. See `glib_wrapper!`.
Encapsulates memory management logic for shared types.
`IMPL` Low level signal support.
Whether to propagate the signal to the default handler.
Don't inhibit default handlers without a reason, they're usually helpful.
The id of a source that is returned by `idle_add` and `timeout_add`.
A value of 0 is a good default as it is never a valid source ID.
Continue calling the closure in the future iterations or drop it.
This is the return type of `idle_add` and `timeout_add` closures.
`Continue(true)` keeps the closure assigned, to be rerun when appropriate.
`Continue(false)` disconnects and drops it.
Unwinding propagation guard. Aborts the process if destroyed while
panicking.
Adds a closure to be called by the default main loop when it's idle.
`func` will be called repeatedly until it returns `Continue(false)`.
The default main loop almost always is the main loop of the main thread.
Thus the closure is called on the main thread.
Adds a closure to be called by the default main loop at regular intervals
with millisecond granularity.
`func` will be called repeatedly every `interval` milliseconds until it
returns `Continue(false)`. Precise timing is not guaranteed, the timeout may
be delayed by other events. Prefer `timeout_add_seconds` when millisecond
precision is not necessary.
The default main loop almost always is the main loop of the main thread.
Thus the closure is called on the main thread.
Adds a closure to be called by the default main loop at regular intervals
with second granularity.
`func` will be called repeatedly every `interval` seconds until it
returns `Continue(false)`. Precise timing is not guaranteed, the timeout may
be delayed by other events.
The default main loop almost always is the main loop of the main thread.
Thus the closure is called on the main thread.
Adds a closure to be called by the main loop the returned `Source` is attached to when a child
process exits.
`func` will be called when `pid` exits
Adds a closure to be called by the default main loop whenever a UNIX signal is raised.
`func` will be called repeatedly every time `signum` is raised until it
returns `Continue(false)`.
The default main loop almost always is the main loop of the main thread.
Thus the closure is called on the main thread.
Removes the source with the given id `source_id` from the default main context.
It is a programmer error to attempt to remove a non-existent source.
Note: source id are reused.
For historical reasons, the native function always returns true, so we
ignore it here.
The priority of sources
Adds a closure to be called by the main loop the return `Source` is attached to when it's idle.
`func` will be called repeatedly until it returns `Continue(false)`.
Adds a closure to be called by the main loop the returned `Source` is attached to at regular
intervals with millisecond granularity.
`func` will be called repeatedly every `interval` milliseconds until it
returns `Continue(false)`. Precise timing is not guaranteed, the timeout may
be delayed by other events. Prefer `timeout_add_seconds` when millisecond
precision is not necessary.
Adds a closure to be called by the main loop the returned `Source` is attached to at regular
intervals with second granularity.
`func` will be called repeatedly every `interval` seconds until it
returns `Continue(false)`. Precise timing is not guaranteed, the timeout may
be delayed by other events.
Adds a closure to be called by the main loop the returned `Source` is attached to when a child
process exits.
`func` will be called when `pid` exits
Adds a closure to be called by the main loop the returned `Source` is attached to whenever a
UNIX signal is raised.
`func` will be called repeatedly every time `signum` is raised until it
returns `Continue(false)`.
Translation between GLib/GLib-based FFI types and their Rust counterparts.
This module allows library bindings authors to decouple type translation
logic and use unified idioms at FFI boundaries. It also implements
translation of GLib core data types.
`FromGlib`, `from_glib` and `ToGlib` translate simple types like `bool`.
```ignore
pub fn set_accept_focus(&self, accept_focus: bool) {
unsafe { glib_ffi::gdk_window_set_accept_focus(self.pointer, accept_focus.to_glib()) }
}
pub fn get_accept_focus(&self) -> bool {
unsafe { from_glib(glib_ffi::gdk_window_get_accept_focus(self.pointer)) }
}
```
`ToGlibPtr`, `FromGlibPtrNone`, `FromGlibPtrFull` and `FromGlibPtrBorrow` work on `gpointer`s
and support different modes of ownership transfer.
```ignore
fn get_title(&self) -> Option<String> {
unsafe {
let title = glib_ffi::gtk_window_get_title(self.pointer);
from_glib_none(title)
}
}
```
Letting the foreign library borrow pointers from the Rust side often
requires having a temporary variable of an intermediate type (e.g. `CString`).
A `Stash` contains the temporary storage and a pointer into it that
is valid for the lifetime of the `Stash`. As the lifetime of the `Stash` returned
from `to_glib_none` is at least the enclosing statement, you can avoid explicitly
binding the stash in most cases and just take the pointer out of it:
```ignore
pub fn set_icon_name(&self, name: &str) {
unsafe {
glib_ffi::gdk_window_set_icon_name(self.pointer, name.to_glib_none().0)
}
}
```
A pointer
Overrides pointer mutability.
Use when the C API should be specifying a const pointer but doesn't.
A trait for creating an uninitialized value. Handy for receiving outparams.
Returns an uninitialized value.
Returns an uninitialized value.
Returns `Some(val)` if the condition is true and `None` otherwise.
Helper type that stores temporary values used for translation.
`P` is the foreign type pointer and the first element of the tuple.
`T` is the Rust type that is translated.
The second element of the tuple is the temporary storage defined
by the implementation of `ToGlibPtr<P> for T`
Say you want to pass a `*mut GdkWindowAttr` to a foreign function. The `Stash`
will own a `GdkWindowAttr` and a `CString` that `GdkWindowAttr::title` points into.
```ignore
impl <'a> ToGlibPtr<'a, *mut glib_ffi::GdkWindowAttr> for WindowAttr {
type Storage = (Box<glib_ffi::GdkWindowAttr>, Stash<'a, *const c_char, Option<String>>);
fn to_glib_none(&'a self) -> Stash<*mut glib_ffi::GdkWindowAttr, WindowAttr> {
let title = self.title.to_glib_none();
let mut attrs = Box::new(glib_ffi::GdkWindowAttr {
title: title.0,
// ....
});
Stash(&mut *attrs, (attrs, title))
}
}
```
Translate a simple type.
Provides the default pointer type to be used in some container conversions.
It's `*mut c_char` for `String`, `*mut GtkButton` for `gtk::Button`, etc.
Translate to a pointer.
Transfer: none.
The pointer in the `Stash` is only valid for the lifetime of the `Stash`.
Transfer: container.
We transfer the container ownership to the foreign library retaining
the elements ownership.
Transfer: full.
We transfer the ownership to the foreign library.
Translate to a pointer with a mutable borrow.
Transfer: none.
The pointer in the `Stash` is only valid for the lifetime of the `Stash`.
Translate a simple type.
Translate a simple type.
Translate from a pointer type without taking ownership, transfer: none.
Translate from a pointer type taking ownership, transfer: full.
Translate from a pointer type by borrowing. Don't increase the refcount
Translate from a pointer type, transfer: none.
Translate from a pointer type, transfer: full (assume ownership).
Translate from a pointer type, borrowing the pointer.
Translate from a container.
Transfer: none.
`num` is the advised number of elements.
Transfer: container.
`num` is the advised number of elements.
Transfer: full.
`num` is the advised number of elements.
Translate from a container of pointers.
Transfer: none.
Transfer: container.
Transfer: full.
Runtime type information.
A GLib or GLib-based library type
An invalid `Type` used as error return value in some functions
The fundamental type corresponding to the unit type `()`
The fundamental type corresponding to `i8`
The fundamental type corresponding to `u8`
The fundamental type corresponding to `bool`
The fundamental type corresponding to `i32`
The fundamental type corresponding to `u32`
The fundamental type corresponding to C `long`
The fundamental type corresponding to C `unsigned long`
The fundamental type corresponding to `i64`
The fundamental type corresponding to `u64`
The fundamental type corresponding to `f32`
The fundamental type corresponding to `f64`
The fundamental type corresponding to `String`
The fundamental type corresponding to a pointer
The fundamental type of GVariant
The fundamental type from which all interfaces are derived
The fundamental type from which all enumeration types are derived
The fundamental type from which all flags types are derived
The fundamental type from which all boxed types are derived
The fundamental type from which all `GParamSpec` types are derived
The fundamental type from which all objects are derived
A non-fundamental type identified by value of type `usize`
Types that are supported by GLib dynamic typing.
Returns the type identifier of `Self`.
Same as [`get_prgname()`].
[`get_prgname()`]: fn.get_prgname.html
Same as [`set_prgname()`].
[`set_prgname()`]: fn.set_prgname.html
`Value` binding and helper traits.
The type of a [`Value`](struct.Value.html) is dynamic in that it generally
isn't known at compile time but once created a `Value` can't change its
type.
[`TypedValue`](struct.TypedValue.html) has a statically known type and
dereferences to `Value` so it can be used everywhere `Value` references are
accepted.
Supported types are `bool`, `i8`, `u8`, `i32`, `u32`, `i64`, `u64`, `f32`,
`f64`, `String` and objects (`T: IsA<Object>`).
# Examples
```
use glib::prelude::*; // or `use gtk::prelude::*;`
use glib::{TypedValue, Value};
// Value and TypedValue implement From<&i32>, From<&str>
// and From<Option<&str>>. Another option is the `ToValue` trait.
let mut num = 10.to_value();
let mut hello = Value::from("Hello!");
let none: Option<&str> = None;
let str_none = Value::from(none.clone());
let typed_str_none = TypedValue::from(none);
// `is` tests the type of the value.
assert!(num.is::<i32>());
assert!(hello.is::<String>());
// `get` tries to get a value of specific type and returns None
// if the type doesn't match or the value is None.
assert_eq!(num.get(), Some(10));
assert_eq!(num.get::<String>(), None);
assert_eq!(hello.get(), Some(String::from("Hello!")));
assert_eq!(hello.get::<String>(), Some(String::from("Hello!")));
assert_eq!(str_none.get::<String>(), None);
// `typed` tries to convert a `Value` to `TypedValue`.
let mut typed_num = num.downcast::<i32>().unwrap();
let mut typed_hello = hello.downcast::<String>().unwrap();
// `str_none` is not an `i32`
assert!(str_none.downcast::<i32>().is_err());
// `get`
assert!(typed_hello.get().unwrap() == "Hello!");
assert!(typed_str_none.get() == None);
// Numeric types can't have value `None`, `get` always returns `Some`.
// Such types have `get_some`, which avoids unnecessary `unwrap`ping.
assert_eq!(typed_num.get().unwrap(), 10);
assert_eq!(typed_num.get_some(), 10);
// `set_none` sets the value to `None` if the type supports it.
typed_hello.set_none();
assert!(typed_hello.get().is_none());
// `set` takes an optional reference for types that support `None`.
typed_hello.set(Some("Hello again!"));
assert!(typed_hello.get().unwrap() == "Hello again!");
// `set_some` is the only setter for types that don't support `None`.
typed_num.set_some(&20);
assert_eq!(typed_num.get_some(), 20);
```
A generic value capable of carrying various types.
Once created the type of the value can't be changed.
Some types (e.g. `String` and objects) support `None` values while others
(e.g. numeric types) don't.
See the [module documentation](index.html) for more details.
Tries to downcast to a `TypedValue`.
Returns `Ok(TypedValue<T>)` if the value carries a type corresponding
to `T` and `Err(self)` otherwise.
Tries to get a value of type `T`.
Returns `Some` if the type is correct and the value is not `None`.
This function doesn't distinguish between type mismatches and correctly
typed `None` values. Use `downcast` or `is` for that.
Returns `true` if the type of the value corresponds to `T`.
Returns the type of the value.
Returns whether `Value`s of type `src` can be transformed to type `dst`.
A statically typed [`Value`](struct.Value.html).
It dereferences to `Value` and can be used everywhere `Value` references are
accepted.
See the [module documentation](index.html) for more details.
Returns the value.
Types that don't support a `None` value always return `Some`. See
`get_some`.
Returns the value.
This method is only available for types that don't support a `None`
value.
Sets the value.
This method is only available for types that support a `None` value.
Sets the value to `None`.
This method is only available for types that support a `None` value.
Sets the value.
Converts to `Value`.
Returns a `Value` clone of `self`.
Returns the type identifer of `self`.
This is the type of the value to be returned by `to_value`.
Extracts a value.
Types that don't support a `None` value always return `Some`.
Extracts a value.
Only implemented for types that don't support a `None` value.
Sets a value.
Only implemented for types that support a `None` value.
Sets a value.
`Variant` binding and helper traits.
[`Variant`](struct.Variant.html) is an immutable dynamically-typed generic
container. Its type and value are defined at construction and never change.
`Variant` types are described by [`VariantType`](../struct.VariantType.html)
"type strings".
Although `GVariant` supports arbitrarily complex types, this binding is
currently limited to the basic ones: `bool`, `u8`, `i16`, `u16`, `i32`,
`u32`, `i64`, `u64`, `f64` and `&str`/`String`.
# Examples
```
use glib::prelude::*; // or `use gtk::prelude::*;`
use glib::Variant;
// Using the `ToVariant` trait.
let num = 10.to_variant();
// `is` tests the type of the value.
assert!(num.is::<i32>());
// `get` tries to extract the value.
assert_eq!(num.get::<i32>(), Some(10));
assert_eq!(num.get::<u32>(), None);
// `Variant` implements `From`
let hello = Variant::from("Hello!");
// `get_str` tries to borrow a string slice.
assert_eq!(hello.get_str(), Some("Hello!"));
assert_eq!(num.get_str(), None);
```
A generic immutable value capable of carrying various types.
See the [module documentation](index.html) for more details.
Returns the type of the value.
Returns `true` if the type of the value corresponds to `T`.
Tries to extract a value of type `T`.
Returns `Some` if `T` matches the variant's type.
Tries to extract a `&str`.
Returns `Some` if the variant has a string type (`s`, `o` or `g` type
strings).
Converts to `Variant`.
Returns a `Variant` clone of `self`.
Extracts a value.
Tries to extract a value.
Returns `Some` if the variant's type matches `Self`.
Returns `VariantType` of `Self`.
Returns the `VariantType` corresponding to `Self`.
Describes `Variant` types.
The `Variant` type system (based on the D-Bus one) describes types with
"type strings". `VariantType` is an owned immutable type string (you can
think of it as a `Box<str>` statically guaranteed to be a valid type
string), `&VariantTy` is a borrowed one (like `&str`).
Tries to create a `VariantType` from a string slice.
Returns `Ok` if the string is a valid type string, `Err` otherwise.
Describes `Variant` types.
This is a borrowed counterpart of [`VariantType`](struct.VariantType.html).
Essentially it's a `str` statically guaranteed to be a valid type string.
Tries to create a `&VariantTy` from a string slice.
Returns `Ok` if the string is a valid type string, `Err` otherwise.
Converts a type string into `&VariantTy` without any checks.
Creates `&VariantTy` with a wildcard lifetime from a `GVariantType`
pointer.
Returns a `GVariantType` pointer.
Converts to a string slice.
`IMPL` The `glib_wrapper!` macro and miscellaneous wrapper traits.
Defines a wrapper type and implements the appropriate traits.
The basic syntax is
```ignore
glib_wrapper! {
Documentation
pub struct $name($kind<$foreign>);
match fn {
$fn_name => /* a closure-like expression ,
...
}
}
```
This creates a wrapper named `$name` around the foreign type `$foreign`
of `$kind` (one of `Boxed`, `Shared`, `Object`) using expressions from the `match fn`
block to implement type-specific low-level operations (the expression
will be evaluated in `unsafe` context).
### Boxed
Boxed records with single ownership.
```ignore
glib_wrapper! {
Text buffer iterator
pub struct TextIter(Boxed<ffi::GtkTextIter>);
match fn {
copy => |ptr| ffi::gtk_text_iter_copy(ptr),
free => |ptr| ffi::gtk_text_iter_free(ptr),
}
}
```
`copy`: `|*const $foreign| -> *mut $foreign` creates a copy of the value.
`free`: `|*mut $foreign|` frees the value.
`get_type`: `||` (optional) returns the `Type`, if any
### Shared
Records with reference counted shared ownership.
```ignore
glib_wrapper! {
Object holding timing information for a single frame.
pub struct FrameTimings(Shared<ffi::GdkFrameTimings>);
match fn {
ref => |ptr| ffi::gdk_frame_timings_ref(ptr),
unref => |ptr| ffi::gdk_frame_timings_unref(ptr),
}
}
```
`ref`: `|*mut $foreign|` increases the refcount.
`unref`: `|*mut $foreign|` decreases the refcount.
`get_type`: `||` (optional) returns the `Type`, if any
### Object
Objects -- classes and interfaces.
```ignore
glib_wrapper! {
Object representing an input device.
pub struct Device(Object<ffi::GdkDevice>);
match fn {
get_type => || ffi::gdk_device_get_type(),
}
}
```
```ignore
glib_wrapper! {
A container with just one child.
pub struct Bin(Object<ffi::GtkBin>): Container, Widget, Buildable;
match fn {
get_type => || ffi::gtk_bin_get_type(),
}
}
```
Implementing types from other crates requires specifying their FFI
counterparts as well:
```ignore
glib_wrapper! {
pub struct Application(Object<ffi::GtkApplication>): [
gio::Application => gio_ffi::GApplication,
gio::ActionGroup => gio_ffi::GActionGroup,
gio::ActionMap => gio_ffi::GActionMap,
];
match fn {
get_type => || ffi::gtk_application_get_type(),
}
}
```
`get_type: || -> GType` returns the type identifier of the class or interface.
A wrapper struct.
Foreign type represented by the struct.