gtk-rs blog

New Release

Wed, 17 Jul 2024 09:00:00 +0000

gtk4-rs 0.9 and gtk-rs-core 0.20 were just freshly released, just in time for also being included in the GNOME 47 release.

This release is again relatively small, mostly providing bindings to new APIs and improvements to the glib::clone! and glib::closure! macros to work better with cargo fmt and rust-analyzer.

As usual, at the same time gstreamer-rs 0.23 and gst-plugins-rs 0.13, libadwaita 0.7 and other related crates got a new release compatible with the new gtk4-rs and gtk-rs-core releases and their own set of changes.

gtk-rs-core

New syntax for `glib::clone!` and `glib::closure!`

The syntax for the clone! and closure! macros was updated to look more like valid Rust code, and as a side effect it is also handled correctly by cargo fmt, rust-analyzer and other tooling now.

The old syntax is still supported but will give a deprecation warning.

To get an idea of the change, what previously looked like:

clone!(@strong self as obj, @weak v => @default-return false, move |x| {
    println!("obj: {}, v: {}, x: {}", obj, v, x);
    true
})

would now look like this:

clone!(
    #[strong(rename_to = obj)]
    self,
    #[weak]
    v,
    #[upgrade_or]
    false,
    move |x| {
        println!("obj: {}, v: {}, x: {}", obj, v, x);
        true
    },
);

Check the documentation for more details about the new syntax.

GLib 2.82 APIs

New GLib and GIO 2.82 APIs are supported with this release. GLib 2.56 is still the minimum version supported by the bindings.

Trait re-organization for defining new GObject interfaces

The traits for defining new GObject interfaces were slightly re-organized to make them more similar with the ones for defining new GObjects.

Previously one would write:

#[derive(Clone, Copy)]
#[repr(C)]
pub struct MyStaticInterface {
    parent: glib::gobject_ffi::GTypeInterface,
}

#[glib::object_interface]
unsafe impl ObjectInterface for MyStaticInterface {
    const NAME: &'static str = "MyStaticInterface";
}

This would now become:

#[derive(Clone, Copy)]
#[repr(C)]
pub struct MyStaticInterfaceClass {
    parent: glib::gobject_ffi::GTypeInterface,
}

unsafe impl InterfaceStruct for MyStaticInterfaceClass {
    type Type = MyStaticInterface;
}

pub enum MyStaticInterface {}

#[glib::object_interface]
impl ObjectInterface for MyStaticInterface {
    const NAME: &'static str = "MyStaticInterface";

    type Interface = MyStaticInterfaceClass;
}

While it is a bit more code, this is almost the same as for GObjects now.

Safer borrowing of GObjects and other types from FFI code

It is possible to directly borrow GObjects and other types in FFI code without additional refcounting or copying. In previous releases the API for that was completely based on pointers, which allowed to accidentally create dangling pointers without the compiler being able to help.

let obj = {
    let mut ptr: *mut glib::ffi::GObject = ...;
    let obj: &glib::Object = glib::Object::from_glib_ptr_borrow(&mut ptr);
    obj
};
// At this point `obj` is pointing at a stack frame that does not exist anymore

Starting with this release, a reference to a pointer is used instead to avoid this from happening. The above code would not compile anymore. Previously the lifetime of the returned object would be arbitrary, now it is bound strictly to the lifetime of the pointer.

Code using this API likely does not need any changes unless the code was previously wrong.

gtk4-rs

GTK 4.16 APIs

New GTK 4.16 APIs are supported with this release. GTK 4.0 is still the minimum version supported by the bindings.

Changes

For the interested ones, here is the list of the merged pull requests:

gtk4-rs:

gtk-rs-core:

All this was possible thanks to the gtk-rs/gir project as well:

Thanks to all of our contributors for their (awesome!) work on this release:

New Release

Sat, 01 Jun 2024 13:00:00 +0000

This is the blog post release for gtk4-rs 0.8 and gtk-rs-core 0.19.

Although this release happened a few months ago, we finally had time to finish this release blog post!

This is a smaller release than usual, bringing some nice quality of life improvements.

Enjoy!

gtk3

Support for gtk3-rs crates was dropped. No more updates will be done on it. If you didn’t yet, please migrate to gtk4-rs.

gtk-rs-core

Removal of glib channels

In this release the glib::MainContext::channel() function was removed, together with the corresponding sender/receiver types. In many cases this API has led to overly complicated code in applications because people tried to develop state machines via callbacks, instead of simply making use of async Rust for that purpose.

Instead of using the main context channel, the new way of passing values between other threads and the main thread is by using any of the many async channel implementations. Examples for this are the async-channel crate, the MPSC channels from tokio or async-std, the task/thread join handles of both, the flume crate, …

For example, the following code:

let (sender, receiver) = glib::MainContext::channel(glib::Priority::DEFAULT);
receiver.attach(Some(&glib::MainContext::default()), move |msg| do_things(msg));

sender.send(MyMessage);

Could be rewritten like this with the async-channel crate:

let (sender, receiver) = async_channel::unbounded();
glib::MainContext::default().spawn_local(async move {
    while let Ok(msg) = receiver.recv().await {
        do_things(msg);
    }
});

sender.send_blocking(MyMessage).expect("Channel closed");

Removal of re-exported once_cell crate, use `std::cell::OnceCell` / `std::sync::OnceLock`

If you need lazy initialization then once_cell::sync::Lazy is still useful until LazyCell / LazyLock from std are finalized.

Re-organized traits in glib

If you get a compiler error because of missing traits, usually the solution would be to make sure that the prelude of the crates (e.g. gtk::prelude::*) is imported.

Dynamic types support

Let’s say you want to create a plugin to add some features or to customize some application. object_class_dynamic, object_interface_dynamic , enum_dynamic and flags_dynamic are macro helper attributes to make your types dynamic.

// My object types
#[derive(Default)]
pub struct MyType;

#[glib::object_subclass]
#[object_subclass_dynamic]
impl ObjectSubclass for MyType { ... }

// My interfaces
pub struct MyInterface {
    parent: glib::gobject_ffi::GTypeInterface,
}

#[glib::object_interface]
#[object_interface_dynamic]
unsafe impl ObjectInterface for MyInterface { ... }

// My enums
#[derive(Debug, Copy, Clone, PartialEq, Eq, glib::Enum)]
#[enum_type(name = "MyModuleEnum")]
#[enum_dynamic]
enum MyModuleEnum { ... }

// My flags
#[glib::flags(name = "MyFlags")]
#[flags_dynamic]
enum MyFlags { ... }

Your plugin code has to implement the TypePlugin interface or to extend the TypeModule type in order to register or unregister your dynamic types when the module (or plugin) is loaded or unloaded.

#[derive(Default)]
pub struct MyModule;

#[glib::object_subclass]
impl ObjectSubclass for MyModule { ... }

impl ObjectImpl for MyModule {}

impl TypePluginImpl for MyModule {}

impl TypeModuleImpl for MyModule {
    fn load(&self) -> bool {
        // registers my plugin types as dynamic types.
        let my_module = self.obj();
        let type_module: &glib::TypeModule = my_module.upcast_ref();
        MyInterface::on_implementation_load(type_module)
            && MyType::on_implementation_load(type_module)
            && MyEnum::on_implementation_load(type_module)
            && MyFlags::on_implementation_load(type_module)
    }

    fn unload(&self) {
        // marks my plugin types as unregistered.
        let my_module = self.obj();
        let type_module: &glib::TypeModule = my_module.upcast_ref();
        MyFlags::on_implementation_unload(type_module);
        MyEnum::on_implementation_unload(type_module);
        MyType::on_implementation_unload(type_module);
        MyInterface::on_implementation_unload(type_module);
    }
}

By default dynamic types are registered when the system loads your plugin. In some cases, it could be useful to postpone the registration of a dynamic type on the first use. This can be done by setting lazy_registration = true:

// My object types
#[derive(Default)]
pub struct MyType;

#[glib::object_subclass]
#[object_subclass_dynamic(lazy_registration = true)]
impl ObjectSubclass for MyType { ... }

For more complex cases, see the documentation glib::object_subclass, glib::object_interface, glib::Enum, glib::flags, glib::subclass::type_module::TypeModuleImpl and glib::subclass::type_plugin::TypePluginImpl.

gtk4-rs

GTK 4.14 APIs support
Support TemplateChild<T> usage with glib::Properties macro, allowing TemplateChild<T> to be used as properties

gtk4-rs:

gtk-rs-core:

All this was possible thanks to the gtk-rs/gir project as well:

Thanks to all of our contributors for their (awesome!) work on this release:

New Release

Mon, 28 Aug 2023 20:00:00 +0000

It is time again for a new gtk-rs release!

If you have been watching our crates on crates.io closely or if you have attended GUADEC you may already have noticed that we have released new versions of the gtk-rs crates.

The new versions contain less breaking changes than some of our previous releases, so updating will be easier. The release however does include some nice improvements that can simplify your application as well as support the latest API additions of the underlying libraries.

As anticipated in the previous release, this will likely be the last release of the gtk3-rs bindings and we recommend to everyone to upgrade to GTK4. If you require gtk3-rs to keep up with new versions of gtk-rs-core please consider volunteering to help with maintenance of the project.

Increase of the minimum supported Rust version (MSRV)

With this release, Rust 1.70 is the minimum version required to compile and use the bindings.

Supported versions

glib/gio: from version 2.56 to 2.78
cairo: 1.16
pango/pangocairo: from version 1.40 to the to be released 1.52
gdk-pixbuf: from version 2.36 to 2.42
graphene: from version 1.10 to 1.12
gtk4: from 4.0 to 4.12 with minimal support of the upcoming 4.14 release
gtk3: from 3.22

Documentation improvements

In this release, we also started a slow but steady path towards automatically generating subclassing traits. The first step is to parse the corresponding virtual methods data from the GIR file and embed the documentation for these functions to their corresponding Rust functions like we do for normal functions/methods/types.

See https://gtk-rs.org/gtk4-rs/stable/latest/docs/gtk4/subclass/widget/trait.WidgetImpl.html#method.keynav_failed

We also now embed the documentation for Class methods. See https://gtk-rs.org/gtk4-rs/stable/latest/docs/gtk4/subclass/widget/trait.WidgetClassExt.html#method.install_property_action

Last but not least, libraries depending on gtk-rs libraries can now have their documentation published in docs.rs by adding the following to your Cargo.toml.

[package.metadata.docs.rs]
all-features = true
rustc-args = ["--cfg", "docsrs"]
rustdoc-args = ["--cfg", "docsrs"]
features = []

Switch to bitflags 2.0

With this release we switched to version 2 of the bitflags crate. While we regularly update our dependencies to the latest version, this is of particular note since flag types are often used in glib and GTK API.

We also re-export bitflags and once_cell from the glib crate so you can use them without directly depending on them.

gtk-rs-core

New `glib::derived_properties` macro

With the glib::Properties derive macro added in the last release, you still had to write these blanket functions manually

impl ObjectImpl for T {
    fn properties() -> &'static [glib::ParamSpec] {
        Self::derived_properties()
    }
    fn set_property(&self, id: usize, value: &glib::Value, pspec: &glib::ParamSpec) {
        self.derived_set_property(id, value, pspec)
    }
    fn property(&self, id: usize, pspec: &glib::ParamSpec) -> glib::Value {
        self.derived_property(id, pspec)
    }
}

Now you can replace that code with

#[glib::derived_properties]
impl ObjectImpl for T {}

Replacement of `glib::Continue` / `glib::Inhibit`

These two types were a bit difficult to understand, as you had to pass a boolean glib::Continue(true) / glib::Inhibit(false). We replaced them with new enums

glib::Continue(true) -> glib::ControlFlow::Continue
glib::Continue(false) -> glib::ControlFlow::Break
glib::Inhibit(true) -> glib::Propagation::Stop
glib::Inhibit(false) -> glib::Propagation::Proceed

Making the meaning of each value clearer to the developer. This should be the most annoying change you need to do during the update to this release.

Typed constructors

In the past we had a bunch of constructors taking glib::Type as a parameter instead of T: impl StaticType / T: impl IsA<O>. For this release, we cleaned up several of those constructors.

let model = gio::ListStore::new(SomeObject::static_type()); // before
let model = gio::ListStore::new::<SomeObject>(); // after
let model = gio::ListStore::with_type(SomeObject::static_type()); // is available for specific use cases

Changed constructors:

glib::SignalGroup
glib::FlagsClass
glib::EnumClass

New `glib::ValueDelegate` macro

Let’s say you want to create a wrapper around some type, but you want to retain ToValue, FromValue, and HasParamSpec implementations, which are especially necessary when you want to use a type as a property. This is where the glib::ValueDelegate macro comes in. Instead of having to manually implement the following:

pub struct Uid(String);

impl glib::types::StaticType for Uid {
    fn static_type() -> glib::types::Type {
        <String as glib::types::StaticType>::static_type()
    }
}

impl glib::value::ToValue for Uid {
    fn to_value(&self) -> glib::value::Value {
        glib::value::ToValue::to_value(&self.0)
    }

    fn value_type(&self) -> glib::types::Type {
        glib::value::ToValue::value_type(&self.0)
    }
}

impl From<Uid> for glib::value::Value {
    fn from(uid: Uid) -> Self {
        glib::value::Value::from(uid.0)
    }
}

unsafe impl<'a> glib::value::FromValue<'a> for Uid {
    type Checker = <String as glib::value::FromValue<'a>>::Checker;
    unsafe fn from_value(value: &'a glib::value::Value) -> Self {
        Uid(<String as glib::value::FromValue<'a>>::from_value(value))
    }
}

impl glib::HasParamSpec for Uid {
    type ParamSpec = <String as glib::HasParamSpec>::ParamSpec;
    type SetValue = Self;
    type BuilderFn = <String as glib::HasParamSpec>::BuilderFn;
    fn param_spec_builder() -> Self::BuilderFn {
        <String as glib::HasParamSpec>::param_spec_builder()
    }
}

you can simply use the macro as follows:

#[derive(glib::ValueDelegate)]
pub struct Uid(String);

For more complex cases, see the documentation.

You could also achieve the same by using glib::Boxed, but glib::ValueDelegate provides a thinner wrapper as it only calls to the inner implementation instead of using GBoxed. Additionally, glib::ValueDelegate propagates the GType to the wrapper instead of creating a new GType.

gtk4-rs

The bindings now support GTK 4.12 with v4_12 feature flag. Other than that they didn’t see many user facing changes. The development mainly focused on various cleanups and bug fixes.

Blueprint support in `gtk::CompositeTemplate`

You can now use blueprint with both string and file attributes of the gtk::CompositeTemplate macro. This requires having the blueprint-compiler binary installed.

use gtk::{glib, prelude::*, subclass::prelude::*};

mod imp {
    use super::*;

    #[derive(Debug, Default, gtk::CompositeTemplate)]
    #[template(string = "
    template MyWidget : Widget {
        Label label {
            label: 'foobar';
        }

        Label my_label2 {
            label: 'foobaz';
        }
    }
    ")]
    pub struct MyWidget {
        #[template_child]
        pub label: TemplateChild<gtk::Label>,
        #[template_child(id = "my_label2")]
        pub label2: gtk::TemplateChild<gtk::Label>,
    }

    #[glib::object_subclass]
    impl ObjectSubclass for MyWidget {
        const NAME: &'static str = "MyWidget";
        type Type = super::MyWidget;
        type ParentType = gtk::Widget;
        fn class_init(klass: &mut Self::Class) {
            klass.bind_template();
        }
        fn instance_init(obj: &glib::subclass::InitializingObject<Self>) {
            obj.init_template();
        }
    }

    impl ObjectImpl for MyWidget {
        fn dispose(&self) {
            while let Some(child) = self.obj().first_child() {
                child.unparent();
            }
        }
    }
    impl WidgetImpl for MyWidget {}
}

glib::wrapper! {
    pub struct MyWidget(ObjectSubclass<imp::MyWidget>) @extends gtk::Widget;
}

Stop using deprecated StyleContext APIs

The gtk::StyleContext::add_provider_for_display / gtk::StyleContext::remove_provider_for_display functions were never supposed to be part of the gtk::StyleContext type. Since that type was deprecated upstream in GTK 4.10, the developers now annoyingly had to use #[allow(deprecated)], even though those two functions were not deprecated at all.

We have added gtk::style_context_add_provider_for_display / gtk::style_context_remove_provider_for_display as a replacement for them.

Detailed Changes

Here is the full list of the merged pull requests:

gtk-rs-core:

gtk3-rs:

gtk4-rs:

All this was possible thanks to the gtk-rs/gir project as well:

Thanks to all of our contributors for their (awesome!) work on this release:

New release

Fri, 10 Feb 2023 22:00:00 +0000

It’s now time for a new gtk-rs release!

As you might’ve noticed, the gtk3-rs projects are getting less and less attention and we intend to deprecate them in one of the future releases. Therefore, we recommend to anyone who didn’t upgrade to GTK4 to do it now. gtk3-rs will get further releases in the foreseeable future to keep up with gtk-rs-core, but no development effort is going to be directed towards it. This is already the de-facto situation for more than a year. Additionally, the GTK3 versions of various externally maintained bindings will most likely not get any further releases.

In addition to gtk-rs, various externally maintained bindings also had a new release. For gstreamer-rs you can find the CHANGELOG of the 0.20 release here. Most bindings maintained as part of GNOME were also updated.

On this note, time to go through the major changes of this release. Enjoy!

Increase of the minimum supported Rust version (MSRV)

With this release, Rust 1.64 is the minimum version required to compile and use the bindings.

New `#[properties]` macro to make using properties in `glib::Object` subclasses simpler

The glib::Properties macro is now available! It can be used to define object properties straight from the implementation struct definition. The macro will:

define all the necessary ParamSpecs, with the required flags
generate, for each property, a default getter/setter on the wrapper type
generate, for each property, a notify_$property method on the wrapper type
generate the methods derived_properties derived_property and derived_set_property, which can be directly called inside your overrides for ObjectImpl methods properties, property and set_property.

Quick example

#[derive(Properties)]
#[properties(wrapper_type = super::Author)]
pub struct Author {
    #[property(get, set)]
    name: RefCell<String>,
}

This is the result of months of work, and will greatly improve the gtk-rs ecosystem by reducing some of the most prevalent boilerplate and making the platform more welcoming.

Be sure to check out the documentation for more info.

Direct conversions to `glib::Value` and `glib::Variant` via `From`

Previously conversions required using the custom ToValue and ToVariant traits, which is not very intuitive. Now it’s possible to directly use the From trait, i.e. 123i32.to_value() could become 123i32.into().

In addition to improving usability this also avoids copies of the values in a few cases.

`gdk_pixbuf` subclassing support

Support for subclassing various gdk_pixbuf types was added. This allows writing custom pixbuf loaders in Rust and hopefully opens the way for replacing the old C-based PNG/JPEG/GIF pixbuf loaders with Rust versions to improve image loading in all GTK/GNOME applications.

New `glib::CastNone` convenience trait

In many cases casting failures of Optional values should be treated as None. For this purpose a new convenience trait was introduced, which provides an and_downcast() method.

let widget: Option<Widget> = list_item.child();

// Without using `CastNone`
let label = widget.unwrap().downcast::<gtk::Label>().unwrap();

// Using `CastNone` we can avoid the first `unwrap()` call
let label = widget.and_downcast::<gtk::Label>().unwrap();

New `glib::function_name!` macro

While a huge hack, until Rust supports this directly, this macro will allow to get the name of the current function as a &'static str. Or to be more exact, the whole path to the current function.

This is now used in the GLib structured logging API to provide the function name (in addition to the file name, line number and other metadata) and glib::BoolError to provide better location information.

`glib::GStr`, `glib::List`, `glib::PtrSlice`, `glib::Slice`, `glib::StrV` and related native GLib types

New API was added to all the aforementioned types to make dealing with them more natural in Rust. Using them instead of the native Rust types, e.g. Vec, allows for fewer copies when passing the FFI boundary.

Various bindings were also switched to these types for the same reason, and it is planned for the next release(s) to move even more API to it.

In addition two new traits were introduced for dealing with GLib strings and string arrays more efficiently: IntoGStr and IntoStrV. Both allow passing a plain &str or an already NUL-terminated &GStr, or a Vec<String> or an already NUL-terminated glib::StrV to functions and internally the function would either do a copy or directly pass the value to the C function. Up to a certain size the copy would by done on the stack, afterwards a temporary heap copy is made. Compared to the before, when temporary heap copies were made unconditionally, this allows for a lot fewer temporary heap allocations.

And lastly, glib::GString is now storing strings up to a certain size inline without requiring a heap allocation. New GStrings can be created via the gformat! macro similar to the format! macro from std.

Various code generation improvements

All over the bindings, various small code generation improvements were applied which reduced the size of the generated code and/or improved the performance.

For example:

Various trivial functions were explicitly marked as #[inline] to give the compiler yet another hint to actually inline them, and improve inlining across crate boundaries, which then causes the bindings to be completely optimized away in most cases.
In many places, where it made sense, assertions were converted to debug_assert!s to reduce the number of places where stack unwinding could happen in release builds.
The representation of various types was improved, e.g. by removing unnecessary Option wrapping around values or replacing unneeded references with PhantomData with the same lifetime.
Memory initialized by C functions was converted from using zero-initialization to MaybeUninit.
The number of redundant checks was reduced and unsafe variants of functions that skip the checks were added.
All object builder types were changed to use glib::Object::builder(), which reduces stack usage dramatically in addition to requiring fewer value copies.

New `glib::Object` constructors

The old Object::new() constructor that took a slice of property name / value pairs was removed. Instead, Object::new() takes no parameters and creates a new object with default property values.

For creating a new object with non-default property values, use Object::builder(). It provides a much nicer API and also allows for better code generation and fewer value copies.

// before
let obj = glib::Object::new::<MyObject>(&[("a", &123i32), ("b", &"some string")]);
// after
let obj = glib::Object::builder::<MyObject>()
    .property("a", 123i32)
    .property("b", "some string")
    .build();

`gio::Application::run()` returns an `ExitCode`

Instead of returning a plain i32, gio::Application::run() now returns an ExitCode type. This can be directly returned from the main() function as it implements the Termination trait, making it much easier to correctly propagate application exit codes.

GTK4 4.10 API additions

The GTK4 bindings were updated to include all the new APIs introduced by the upcoming GTK 4.10 release. These new APIs are available via the v4_10 feature flag. Note that they are not stable and are subject to change if the underlying C API happens to change before the 4.10.0 release.

The minimum supported GTK version stays at 4.0.0.

Add Blueprint UI definition support

Blueprint is a new markup language for defining GTK4 UIs. The #[template] macro can now accept Blueprint UI definitions in addition to the old XML-based UI definitions. Doing so requires blueprint-compiler to be available during compilation.

#[derive(Debug, Default, gtk::CompositeTemplate)]
#[template(string = "
template MyWidget : Widget {
    Label label {
        label: 'foobar';
    }
    Label my_label2 {
        label: 'foobaz';
    }
}
")]
pub struct MyWidget {
    #[template_child]
    pub label: TemplateChild<gtk::Label>,
    #[template_child(id = "my_label2")]
    pub label2: gtk::TemplateChild<gtk::Label>,
}

You can also copy the example from https://github.com/gtk-rs/gtk4-rs/releases/tag/0.6.0.

Better mapping of C ownership transfer

Previously various functions that took ownership of their parameters still used references in the bindings. This required an unnecessary copy to be made in the worst case, and in the best case made it less clear that ownership of the object is given away.

In this release, functions are taking various arguments by value in more places.

Spawning of blocking functions on the `glib::MainContext`

gio::spawn_blocking() was added, which allows to spawn blocking functions on an internal threadpool and retrieve their results as a Future from the glib::MainContext. This is useful for doing blocking / CPU intensive work in the background and when the results are available to handle them on the application’s main thread.

As part of this work, JoinHandle-style types were also added to glib::MainContext::spawn() and related functions for spawning Futures on the main context, and to glib::ThreadPool for spawning functions on a custom thread pool and collecting their results.

Changes

For those who are interested, here is the list of the merged pull requests:

gtk-rs-core:

gtk3-rs:

gtk4-rs:

All this was possible thanks to the gtk-rs/gir project as well:

Thanks to all of our contributors for their (awesome!) work on this release:

New release

Tue, 18 Oct 2022 12:00:00 +0000

It’s now time for a new Gtk-rs release! As usual, a lot of improvements in a lot of places but subclasses in particular got a lot of updates. Time to dive in on some improvements. Enjoy!

Update of minimum supported versions

The minimum supported version of the C library of various crates was updated to the versions available in Ubuntu 18.04:

GLib/GIO requires at least version 2.56 now and supports API up to version 2.74
gdk-pixbuf requires at least version 2.36.8 and supports API up to version 2.42
Pango requires at least version 1.40 and supports API up to version 1.52
GTK3 requires at least version 3.22.30 and supports API up to version 3.24.30
GTK4 requires at least version 4.0.0 and supports API up to version 4.8

The minimum supported Rust version by all crates was updated to version 1.63.

More async support

A couple of futures helper functions were added with this release that should make futures usage easier in GTK applications.

Timeouts: glib::future_with_timeout(Duration::from_millis(20), fut) will resolve to the result of fut if it takes less than 20ms or otherwise to an error
Cancellation: gio::CancellableFuture::new(fut, cancellable) will resolve to the future unless the cancellable is cancelled before that

GTK 4

Along with plenty of bugfixes and small improvements, the 0.5 release of gtk4-rs brings a couple of useful features

gsk::Transform

Most of the C functions return NULL which represents an identity transformation. The Rust API nowadays returns an identity transformation instead of None

#[gtk::CompositeTemplate] runtime validation

If used with #[template(string=...)] or #[template(file=...)] and the xml_validation feature is enabled, the XML content will be validated to ensure the child widgets that the code is trying to retrieve exists.

#[gtk::test]

As GTK is single-threaded, using it in your tests is problematic as you can’t initialize GTK multiple times. The new attribute macro helps with that as it runs the tests in a thread pool instead of in parallel.

Details at https://gtk-rs.org/gtk4-rs/stable/latest/docs/gtk4_macros/attr.test.html

WidgetClassSubclassExt::install_action_async

In a lot of use cases, people used to do

klass.install_action("some_group.action", None, |widget, _, _| {
    let ctx = glib::MainContext::default();
    ctx.spawn_local(clone!(@weak widget => async move {
        /// call some async function
        widget.async_function().await;
    }));
})

The new helper function allows you to write the code above like

klass.install_action_async("some_group.action", None, |widget, _, _| async move {
    /// call some async function
    widget.async_function().await;
})

Which helps avoiding the usage of the clone macro in some cases.

GTK 4.8 API additions which can be enabled with v4_8
Various fixes for the gdk-wayland & wayland-rs integration requiring wayland-client v0.30
Plenty of new examples:
- Gif Paintable for rendering Gifs
- ColumnView for displaying data in a table-like format
- Confetti animation
- Rotation / Squeezer example

`glib::Object` now has a more convenient object builder

In addition to dynamic objects construction, or e.g. when implementing new GObject subclasses, via glib::Object::new() and related API, there is also a more convenient object builder available.

let obj = glib::Object::builder::<MyObject>()
    .property("prop1", 123)
    .property("prop2", "test")
    .property("prop3", false)
    .build();

This allows for slightly more idiomatic Rust code.

GIO objects completion closure doesn’t need to be `Send` anymore

Asynchronous operations on GIO objects previously required the completion closure to be Send. This is not required anymore as the objects themselves are not Send-able either and the operation will be completed on the current thread via the thread’s own main context. This should make usage of the asynchronous operations easier from GTK applications, where all UI objects are not Send.

As a result of this, also futures provided by GIO objects based on these asynchronous operations do not implement the Send trait anymore, which was wrong to begin with and caused panics at runtime in any situation where the future was actually used on different threads.

Added support for `#[derive(glib::Variant)]` for enums

Starting with the previous release it was possible to derive the required trait implementations for (de)serializing Rust structs from/to glib::Variants. With this release, support for enums is also added with different options for how the enum is going to be represented. Both C-style enums as well as enums with values in the variants are supported.

#[derive(Debug, PartialEq, Eq, glib::Variant)]
enum Foo {
    MyA,
    MyB(i32),
    MyC { some_int: u32, some_string: String }
}
let v = Foo::MyC { some_int: 1, some_string: String::from("bar") };
let var = v.to_variant();
assert_eq!(var.child_value(0).str(), Some("my-c"));
assert_eq!(var.get::<Foo>(), Some(v));

No need to implement `Send` and `Sync` for subclasses anymore

In the past it was necessary to manually implement the Send and Sync traits via an unsafe impl block for the object types of GObject subclasses defined in Rust.

glib::wrapper! {
    pub struct MyObject(ObjectSubclass<imp::MyObject>);
}

unsafe impl Send for MyObject {}
unsafe impl Sync for MyObject {}

This is not necessary anymore and happens automatically if the implementation struct implements both traits. Like this it is also harder to accidentally implement the traits manually although the requirements of them are not fulfilled.

Simpler subclassing for virtual methods

Previously when creating a GObject subclass, all virtual methods passed the implementation struct and the object itself as arguments, e.g.

pub trait ObjectImpl {
    fn constructed(&self, obj: &Self::Type);
}

This caused a lot of confusion and was also redundant. Instead, starting with this release only the implementation struct is passed by reference, e.g.

pub trait ObjectImpl {
    fn constructed(&self);
}

In most contexts the object itself was not actually needed, so this also simplifies the code. For the cases when the object is needed, it can be retrieved via the obj() method on the implementation struct

impl ObjectImpl for MyObject {
    fn constructed(&self) {
        self.parent_constructed();
        let obj = self.obj();
        obj.do_something();
    }
}

In a similar way it is also possible to retrieve the implementation struct from the instance via the imp() method. Both methods are cheap and only involve some pointer arithmetic.

Additionally, to make it easy to pass around the implementation struct into e.g. closures, there is now also a reference counted wrapper around it available (ObjectImplRef) that can be retrieved via imp.to_owned() or imp.ref_counted(), and a weak reference variant that can be retrieved via imp.downgrade(). Both are working in combination with the glib::clone! macro, too.

impl ObjectImpl for MyObject {
    fn constructed(&self) {
        self.parent_constructed();
        // for a strong reference
        self.button.connect_clicked(glib::clone!(@to-owned self as imp => move |button| {
            imp.do_something();
        }));

        // for a weak reference
        self.button.connect_clicked(glib::clone!(@weak self as imp => move |button| {
            imp.do_something();
        }));
    }
}

Simpler subclassing for properties

When creating properties for GObject subclasses they need to be declared beforehand via a glib::ParamSpec. Previously these had simple new() functions with lots of parameters. These still exist but it’s usually more convenient to use the builder pattern to construct them, especially as most of the parameters have sensible defaults.

// Now
let pspec = glib::ParamSpecUInt::builder("name")
    .maximum(1000)
    .construct()
    .build();

// Previously
let pspec = glib::ParamSpecUInt::new("name", None, None, 0, 1000, 0, glib::ParamFlags::READWRITE | glib::ParamFlags::CONSTRUCT);

In a similar spirit, signal definitions are available via a builder. This was available in the previous already but usage was simplified, for example by defaulting to no signal arguments and () signal return type.

// Now
let signal = glib::subclass::Signal::builder("closed").build();

// Before
let signal = glib::subclass::Signal::builder("closed", &[], glib::Type::UNIT).build();

Removing `Result<>` wrapping in some functions returned values

glib::Object::new() returned a Result in previous versions. However, the only way how this could potentially fail was via a programming error: properties that don’t exist were tried to be passed, or values of the wrong type were set for a property. By returning a Result, the impression was given that this can also fail in a normal way that is supposed to be handled by the caller.

As this is not the case, glib::Object::new() always panics if the arguments passed to it are invalid and no longer returns a Result.

In the same spirit, object.try_set_property(), object.try_property(), object.try_emit() and object.try_connect() do not exist any longer and only the panicking variants are left as the only way they could fail was if invalid arguments are provided.

Transform functions for property bindings are now supported

Object property bindings allow for transform functions to be defined, which convert the property value to something else for the other object whenever it changes. Previously these were defined on the generic glib::Value type, but as the types are generally fixed and known in advance it is now possible to define them directly with the correct types.

source
    .bind_property("name", &target, "name")
    .flags(crate::BindingFlags::SYNC_CREATE)
    .transform_to(|_binding, value: &str| Some(format!("{} World", value)))
    .transform_from(|_binding, value: &str| Some(format!("{} World", value)))
    .build();

If the types don’t match then this is considered a programming error and will panic at runtime.

The old way of defining transform functions via glib::Value is still available via new functions

source
    .bind_property("name", &target, "name")
    .flags(crate::BindingFlags::SYNC_CREATE)
    .transform_to_with_values(|_binding, value| {
        let value = value.get::<&str>().unwrap();
        Some(format!("{} World", value).to_value())
    })
    .transform_from_with_values(|_binding, value| {
        let value = value.get::<&str>().unwrap();
        Some(format!("{} World", value).to_value())
    })
    .build();

Construct `SimpleAction` with `ActionEntryBuilder`

It is now possible to use gio::ActionEntryBuilder to construct a gio::SimpleAction, the advantage of using that is the gio::ActionMap type is passed as a first parameter to the activate callback and so avoids the usage of the clone! macro.

Before:

let action = gio::SimpleAction::new("some_action", None);
action.connect_activate(clone!(@weak some_obj => move |_, _| {
     // Do something
});
actions_group.add_action(&action);

After

let action = gio::ActionEntry::builder("some_action").activate(move |some_obj: &SomeType, _, _| {
    // Do something
}).build();
// It is safe to `unwrap` as we don't pass any parameter type that requires validation
actions_group.add_action_entries([action]).unwrap();

Changes

For the interested ones, here is the list of the merged pull requests:

gtk-rs-core:

gtk3-rs:

gtk4-rs:

All this was possible thanks to the gtk-rs/gir project as well:

Thanks to all of our contributors for their (awesome!) work on this release:

New year, new release!

Sun, 16 Jan 2022 17:00:00 +0000

Hi everyone! Happy new year!

With this new year comes a new gtk-rs release! As usual, a lot of improvements have been made. Let’s check them out!

One important change: the minimum supported rust version is now 1.56.

Minimum and latest supported versions of the underlying C libraries

The minimum supported versions of the underlying C libraries have not changed compared to last release but support for newer versions was added:

GLib/GObject/GIO: minimum 2.48, latest 2.72
Pango/PangoCairo: minimum 1.38, latest 1.52
gdk-pixbuf: minimum 2.32, latest 2.42
cairo: minimum 1.14, latest 1.16
graphene: minimum 1.10
ATK: minimum 2.18, latest 2.38
GTK3: minimum 3.18, latest, 3.24.9
GTK4: minimum 4.0, latest 4.6

Changes to derive macro names

All derive and attribute macros are named more consistently now. Instead of e.g. glib::GBoxed, the new name is just glib::Boxed and misses the additional G, which would be redundant namespacing.

GLib Variant API improvements and derive macro

The glib::Variant API was improved a lot in this release. Variant is a type that allows to store structured data built from basic types in a way that can be serialized into binary data efficiently.

A lot of API that was missing in previous releases was added, including API for efficient conversion from/to slices of basic types, strings and other container types. The existing conversion APIs were optimized and cleaned up.

To make it easier to handle custom structs (and soon enums), a derive macro was added that allows to directly convert between a custom Rust type and a Variant and back.

use glib::prelude::*;

#[derive(Debug, PartialEq, Eq, glib::Variant)]
struct Foo {
    some_string: String,
    some_int: i32,
}

let v = Foo { some_string: String::from("bar"), some_int: 1 };
let var = v.to_variant();
assert_eq!(var.get::<Foo>(), Some(v));

By using the derive macro, structured data can be handled automatically instead of manually accessing each of the individual parts of the data. This can be helpful for sending structured data over DBus via the gio DBus API, or for dealing with gio::Settings or for more complex states/values used in gio::Action.

Stack allocated types and reducing heap allocations

Various types that are usually stack-allocated in C were previously heap-allocated in the Rust bindings. With this release, these values are also stack-allocated when used from Rust unless explicitly heap-allocated, e.g. by explicitly placing them into a Box.

Examples for this are all the graphene types (vectors, matrices, etc), which should make calculations considerably more efficient, types like gdk::Rectangle and gdk::RGBA, and gtk::TreeIter.

Overall this brings performance of applications using the Rust bindings even closer to the same code in C.

Main context API improvements

When spawning non-Send futures or closures, or attaching the main context channel to the glib::MainContext, it is not necessary anymore to have the main context acquired before. This was a common cause of confusion and this constraint was relaxed now. Instead it is only required that that thread default main context is not owned by a different thread yet, and if ownership is moved to a different thread at some point then it will panic at runtime.

Additionally the API for pushing a main context as the thread default was refactored to reduce the risk of misusage. Instead of returning a guard value, it can only be used via a closure now to ensure proper nesting of thread default main contexts.

let ctx = glib::MainContext::new();
ctx.with_thread_default(|| {
    // do something with `ctx` being the thread default main context.
}).expect("Main context already owned by another thread");

GLib string builder

glib::String was renamed to glib::GStringBuilder to avoid confusion with glib::GString and to make it clearer that this is meant for building NUL-terminated C strings.

In addition the API was simplified considerably:

All APIs that allowed to create invalid UTF-8 were removed, leaving only safe APIs to build UTF-8 strings.
GStringBuilder directly dereferences into &str, so all &str API can be used on it.
GStringBuilder implements the std::fmt::Write trait, which allows making use of various std Rust API. For example write!(&mut builder, "some format string {}", some_value) can be used directly to write formatted strings into the string builder.

Multiple improvements on `glib::ObjectExt`

ObjectExt::property now return the type T directly instead of a glib::Value and panics in case the property is not readable or the wrong type is provided.
ObjectExt::set_property now panics in case the property is not writeable or doesn’t exists
ObjectExt::emit_by_name expects you to pass in the type T for the returned value by the signal. If the signal doesn’t return anything, you can use some_obj.emit_by_name::<()>("some_signal", &[]); and also panics if the signal doesn’t exists.

Before:

object.property("some_property").unwrap().get::<T>().unwrap();
object.set_property("some_property", &some_value).unwrap();
// signal that returns nothing
object.emit_by_name("some_signal").unwrap();
// signal that returns T
let some_value = object.emit_by_name("some_signal").unwrap().unwrap().get::<T>().unwrap();

After:

object.property::<T>("some_property");
object.set_property("some_property", &some_value);
object.emit_by_name::<()>("some_signal");
let some_value = object.emit_by_name::<T>("some_signal");

A ObjectExt::try_* variant exists if you want the old behaviour. As most of the application code unwraps the returned results, this should be one of the slight but nice improvements of the overall API.

Bindings wrapper types memory representation optimization

All heap-allocated bindings types do now have a memory representation that is equivalent to the underlying raw C pointer. In addition to reducing memory usage compared to before, this also allows for other optimizations and e.g allows to borrow values from C storage in a few places instead of creating copies or increasing their reference count (e.g. in glib::PtrSlice).

GLib collection types

While not used widely yet, a new glib::collections module was added that provides more efficient access to slices, pointer slices and linked lists allocated from C. This is similar to the older glib::GString type, which represents an UTF-8 encoded, NUL-terminated C string allocated with the GLib allocator.

Previously (and still for most API), these were converted from/to native Rust types at the FFI boundary, which often caused unnecessary re-allocations and memory copies. In the next release we’re trying to move even more API to these new collection types for further performance improvements, and for only doing conversions between Rust and C types when actually necessary.

Cancelling futures spawned on the GLib main context

Spawning futures on the main context now returns the source id. This allows to get access to the underlying glib::Source and to cancel the future before completion.

Cancelling the future by this, or by other API that drops it (e.g. by selecting on two futures and only processing the first that resolves), will cancel all asynchronous operations performed by them at the next opportunity.

Dynamic signal connections

A new glib::closure and glib::closure_local was added that allows to create a glib::Closure from a Rust closure while automatically unpacking argument glib::Values to their native Rust types and packing the return value.

While this doesn’t sound too exciting, it makes connecting to signals that have no static bindings more convenient.

Before:

obj.connect(
    "notify", false,
    |args| {
        let _obj = args[0].get::<glib::Object>().unwrap();
        let pspec = args[1].get::<glib::ParamSpec>().unwrap();
        println!("property notify: {}", pspec.name());
    });

After:

obj.connect_closure(
    "notify", false,
    glib::closure_local!(|_obj: glib::Object, pspec: glib::ParamSpec| {
        println!("property notify: {}", pspec.name());
    }));

The macros support the same syntax as the glib::clone macro for creating strong/weak references, plus a watch feature that automatically disconnects the closure once the watched object disappears.

Object subclassing improvements

glib::ParamSpecOverride has now two helper constructors to create an override of a class property or an interface property. For example, overriding the hadjustment property of the gtk::Scrollable interface can be done with ParamSpecOverride::for_interface::<gtk::Scrollable>("hadjustment").

Passing Cairo image surfaces to other threads and getting owned access to its data

Cairo image surfaces can now be converted to an owned value that behaves like an &mut [u8] and that can be safely sent to different threads. This allows both sending Cairo image surfaces to other threads safely as well as their underlying data, e.g. to fill an image surface from a compressed image via the image crate or saving the contents of an image surface to compressed data from a different thread.

let surface =  cairo::ImageSurface::create(cairo::Format:ARgb32, 320, 240).except("Failed to allocate memory");
// Use Cairo API on the `surface`.
// [...]
let data = surface.take_data().expect("Not the unique owner of the surface");
// Send `data` to another thread or otherwise treat it as a `&mut [u8]`.
// [...]
let surface = data.into_inner();
// Use the `surface` with Cairo APIs again.

This solves one of the common problems when using Cairo in multi-threaded applications.

GIO bindings improvements

The gio bindings saw many additions and improvements. Among other things it is now possible to implement the gio::Initable interface, the gio::IOExtension API is now available, and the gio::Task bindings have been reworked to address soundness issues. More improvements to the gio::Task bindings are necessary for them to become nice to use from Rust.

Gdkwayland

In this release, we generated the bindings for gdkwayland. You can now use the brand new gdkwayland crate!

GTK3 child properties

The GTK3 bindings had API added for generically setting and getting child properties.

This allows to access child properties for which no static bindings are available and performs all checks at runtime instead of at compile time. The API works the same as the API for setting and getting object properties.

gtk4-rs and `BuilderScope`

The most important feature that landed on this release is a Rust BuilderScope implementation thanks to one of the awesome contributions of @jf2048. This will allow applications to set callbacks/functions names in the UI file and define those in your Rust code. This only works with the CompositeTemplate macro. See the documentations for how to make use of this new feature.

We also added:

Trust upstream return nullability: in other words, gtk4 crates trust the nullable annotations provided in the GIR file which replaces a bunch of returned Option and returns only T nowadays. Please open an issue if you find any regressions.
GTK 4.6 support, use v4_6 feature to unlock the new APIs.
Functions that return a glib::Value have now a corresponding function that gets you inner value T directly. Note those will panic if you provide the wrong type.

GtkExpression helpers to make their usage nicer from Rust:

let button = gtk::Button::new();
button.set_label("Label property");

let label_expression = button.property_expression("label");

A bunch of fixed issues, documentation improvements and new book chapters!

Other crates

Other than the classic gtk-rs crates, we have also worked on ensuring the ones in https://gitlab.gnome.org/World/Rust and the broader ecosystem received an update:

gstreamer-rs: release 0.18
libadwaita-rs: release 0.1 following up the release of the first stable version 1.0
sourceview5-rs: updated to 0.4, with subclassing support
libshumate-rs: released an alpha for the GTK4 Map widgetery library
sourceview4-rs/libhandy-rs/libdazzle-rs/gspell-rs/poppler-rs
libflatpak-rs: first release of the libflatpak bindings
Relm4: release 0.4, with many new features and improvements

Changes

For the interested ones, here is the list of the merged pull requests:

gtk-rs-core:

gtk3-rs:

gtk4-rs:

All this was possible thanks to the gtk-rs/gir project as well:

Thanks to all of our contributors for their (awesome!) work on this release:

Here comes the 4

Tue, 22 Jun 2021 21:00:00 +0000

It’s been a long time since the last release, and, as you can guess, a lot of things happened in this span of time. Let’s start with the most important one:

gtk-rs now provides bindings for GTK4 libraries!

They are all available in the gtk4-rs repository.

We also wrote an introductory book to teach users how to use gtk4-rs. You can read it here. A more detailed blog post about GTK4 will follow in the next days.

New website and new logo

We used this occasion to completely re-design the website and also make a logo. Since you’re already here, don’t hesitate to go take a look around!

GNOME Circle

gtk-rs is now part of the GNOME Circle! It allows our contributors to join the GNOME foundation if they want to in addition to some other benefits. Check the website for more details.

Repositories changes

This release also saw changes to the gtk-rs repositories structure. We now have three main repositories:

gtk-rs-core: It contains crates which are considered “core” because they are used by both GTK3 and GTK4, but also by other projects such as gstreamer-rs:
- cairo
- gdk-pixbuf
- gio
- glib
- glib-macros
- graphene
- pango
- pangocairo
gtk3-rs: Contains crates which are part of the GTK3 ecosystem:
- atk
- gdk
- gdkx11
- gtk3-macros
gtk4-rs: Contains crates which are part of the GTK4 ecosystem:
- gdk4
- gdk4-wayland
- gdk4-x11
- gsk4
- gtk4
- gtk4-macros

Another important point about this: all crates in one repository share the same version number now. Before it was a bit of a mess so we decided to simplify it. So here are the version numbers for each repository:

gtk-rs-core: 0.14
gtk3-rs: 0.14
gtk4-rs: 0.1

Documentation improvements

gtk-rs crates use the C documentation, however we improved its rendering a bit to make it even more useful for Rust developers:

The items’ links are now correctly generated.
If code examples are not written in Rust, we now add warnings to avoid confusion.
We added doc aliases, so you can now search signal names and even C function names directly.
Global functions, builder patterns, constants and statics are now documented as well.
Arguments which are C specific and therefore not used in the Rust bindings are not rendered anymore.

Dependencies are re-exported

Instead of a long explanation, let’s take an example. You have a GTK application and you also use Cairo and GDK. Before this release, you would add all the 3 dependencies to your Cargo.toml file to be able to use them. Now, you only need to import GTK and then you can do:

use gtk::{cairo, gdk};

And that’s it! It’ll make your management of dependencies much simpler. To be noted, relevant traits are also re-exported in the prelude, so importing it will give you access to them:

use gtk::gdk;
use gtk::prelude::*;

// ...
// This uses the `gdk::prelude::WindowExtManual` trait, through the prelude.
let w = gdk::Window::default_root_window();

Last note about the re-exports: the -sys crates are also re-exported under the name ffi:

use gtk::ffi;

// You now have access to all raw C-functions of GTK.

The `Value` trait was refactored

The main change is that for non-nullable types Value::get() will never ever return None, replacing the previous confusing Value::get_some().

In addition it is now possible to Value::get() a nullable type directly without Option wrapping. If the value was actually None this would return an Err. In cases where the value being None was unexpected this avoids one layer of unwrapping.

There is also a new generic ValueType trait that is implemented by all types that can be used inside a Value and that allows storing/retrieving types of this value into/from a Value.

Added GTK composite template support

For constructing widgets from a UI file, you can either use gtk::Builder or composite templates. With the former, you have to keep an instance of gtk::Builder around. While with composite templates, you make your custom widget (a subclass of gtk::Widget) use the template internally and with the difference of being able to use your CustomWidget in a different UI file by defining:

<object class="CustomWidget">
  <property name="some-property">some-value</property>
</object>

You can now make your CustomWidget use the #[CompositeTemplate] derive macro. The work was done initially for GTK4 Rust bindings, but was backported to GTK3 as well. See here or here for examples.

Composite templates also allow you to use methods defined on your CustomWidget as a callback to a signal directly from the UI file, even though the macro doesn’t support that for now for both GTK3/GTK4 bindings… But don’t worry, we’re working on it!

New and improved macros

In addition to the glib::object_subclass attribute macro (see link to paragraph about subclassing improvements), glib provides a couple of other macros now for making application development easier and with less boilerplate:

glib::clone!: This macro allows automatic cloning or creation of weak references plus upgrading for closures and greatly simplifies creation of signal handler closures. The documentation contains a couple of examples. While this macro existed in the last release already, it was completely rewritten and made more powerful and got a companion derive macro glib::Downgrade that extends custom types with the required machinery to be used for weak references in the context of the clone! macro.
glib::GBoxed and glib::GSharedBoxed: These derive macros allow using custom Rust types inside glib::Values, which is required for example for GObject properties and signal parameters/return values or the content of GTK tree views. The first macro always clones the underlying value when necessary while the second makes use of reference counting instead of normal cloning.
glib::gflags! and glib::GEnum: These macros allow using Rust enums and bitflags to be used inside glib::Values. See the subclassing docs for examples.
glib::GErrorDomain: This derive macro allows using a suitable Rust enum to be used as an error domain for glib::Errors.

See also the subclassing docs for more examples about the glib::GBoxed, glib::gflags and glib::GEnum macros.

Improvements to subclassing

Implementing a GObject is simpler, thanks to the introduction of the glib::object_subclass derive macro. Additionally registering properties and signals now requires less boiler plate. Refer to this page for a complete example but a minimal example would look as follows now:

mod imp {
    #[derive(Default)]
    pub struct MyObject;

    #[glib::object_subclass]
    impl ObjectSubclass for MyObject {
        const NAME: &'static str = "MyObject";

        type Type = super::MyObject;
        type ParentType = glib::Object;
    }

    impl ObjectImpl for MyObject {}
}

glib::wrapper! {
    pub struct MyObject(ObjectSubclass<imp::MyObject>);
}

impl MyObject {
    pub fn new() -> Self {
        glib::Object::new(&[]).unwrap()
    }
}

Better cairo error handling

Using cairo is now more ergonomic: functions like fill() or stroke() return a Result instead of requiring to manually check the Context::status(). Additionally, all internal calls to expect() on the cairo status were removed, enabling the caller to handle error conditions, rather than causing a panic.

Gir tutorial

gtk-rs crates are mostly generated automatically thanks to the gir project. If you also want to generate your own GObject-based crate bindings, you can use it as well! To help you, we started a tutorial book that is available here.

Naming improvements

We renamed a lot of functions/methods in order to make them more Rust-compliant. Specifically, getter functions were renamed from get_something() to just something() or is_something() while the setters stayed as set_something(). In addition GObject property getters/setters lost their property designation from the name (i.e. set_property_something() was replaced by set_something()).

On this note:

Note to applications developers

Applications developers should use fix-getters-calls to ease migration of their applications. Use fix-getters-def if you also want your get functions definition to comply with the API standards applied in this release.

Minimum supported versions

Rust minimum supported version is now 1.51.

ATK: 2.18
Cairo: 1.14
GDK3: 3.18
GDK4: 4.0
GDK4-Wayland: 4.0
GDKX11: 3.18
GDK4-X11: 4.0
GDK-Pixbuf: 2.32
Gio: 2.48
GLib: 2.48
Graphene: 1.10
GSK4: 4.0
GTK3: 3.20
GTK4: 4.0
Pango: 1.38
PangoCairo: 1.38

Migration to the Rust 2018 edition

The gtk-rs crates all migrated to the Rust 2018 edition. Just in time because the 2021 edition is getting close!

Changes

For the interested ones, here is the list of the merged pull requests:

gtk-rs-core:

gtk3-rs:

gtk4-rs:

All this was possible thanks to the gir project as well:

Thanks to all of our contributors for their (awesome!) work on this release:

New crates, better APIs

Sat, 04 Jul 2020 17:30:00 +0000

Hi everyone, time for a new release!

Today, it’s all about improving APIs and providing the GdkX11 bindings. Let’s see it more in details!

Change of minimum supported Rust version

The minimum supported Rust version is now 1.40. All the enums provided by the gtk-rs crates now make use of the #[non_exhaustive] attribute to indicate that there might be more values being added in the future.

Updated library versions

All the crates were updated to the latest library versions, that is, APIs that are newly available since GNOME 3.36 are provided by the bindings.

No more `new_from_...()` and `new_with_...()`

In GLib-based APIs, a common pattern for constructors is to call them new_from_...() or new_with_...(). In Rust the new_ prefix is usually omitted, so all bindings were changed according to that too.

There might still be a few new_...() functions in the bindings. If you find one and think a different name would be better, please create an issue.

`glib-macros`

There’s a new crate glib-macros now, which is re-exported by the glib crate and provides a couple of proc-macros

#[derive(GBoxed) for easily deriving a boxed type for any Rust type the implements the Clone trait. This can be used to store values of that type in e.g. in glib::Value.
#[derive(GEnum)] for integer representation Rust enums, which registers GLib type for them and allows to use them e.g. in a glib::Value.
#[gflags], which registers a GLib type for bitflags and wraps around the bitflags crate. Same as above this can then be used e.g. in a glib::Value.

Check the documentation for details about the above.

GdkX11

GTK and its companion library GDK provide various API for interoperability with platform interfaces, like X11 or Wayland or the equivalent APIs on Windows and macOS.

With this release a crate for the X11 integration API for GDK is included.

`glib::ThreadPool`

GLib provides a thread-pool API, which is now included in the bindings. There are many crates that provide similar functionality but nothing that is part of std yet, as such the addition seemed useful unlike adding bindings for the threading primitives in GLib.

The ThreadPool bindings allow to create shared or exclusive thread pools, where the shared thread pools are sharing their threads with other shared ones. The maximum number of threads and various other parameters can be configured on each thread pool, see the docs.

After creation, new tasks can be pushed on the thread pool as a closure. Optionally a Future can be returned to get notified about the completion of the task.

let pool = ThreadPool::new_exclusive(1)?;

// Runs `do_something()` on the thread pool and doesn't wait
pool.push(|| {
    do_something();
});

// Runs `do_something_else()` on the thread pool and returns its
// return value via a `Future`
let fut = pool.push_future(|| {
    let res = do_something_else();
    res
});

// Asynchronously await the result of `do_something_else()`
let res = fut.await;

Storage of arbitrary data in `glib::Object`s

In C, GObject provides the ability to store arbitrary data on any object. Until this release this was not provided by the bindings as it generally is used as a workaround for a suboptimal architecture, and most importantly because all type information for the stored data is lost.

In this release unsafe API for making use of this is provided but it’s the caller’s responsibility to ensure that the types are matching.

let button = gtk::Button::with_label("test");

unsafe {
    button.set_data("my-data", String::new("my-data-value"));
    let my_data = button.get_data("my-data");
}

Before using this please make sure there is no better solution for what you’re trying to achieve.

`cairo::Error` instead of `cairo::Status`

Previously all cairo functions that could fail were returning a Status enum in one way or another. This lead to unidiomatic error handling in Rust applications.

In this release the Status enum was replaced by an Error enum that only includes errors cases and is returned as part of the error case of Results. This allows doing normal Rust error handling via the ? operator, for example.

cairo features

The FreeType and script features of the cairo bindings are now optional with this release. It was already possible to compile the cairo C library without them but the bindings assumed these features to always exist.

If you make use of these features you now need to enable them when depending on the cairo crate.

GDBus

GLib comes with its own DBus IPC implementation. Starting with this release big parts of the API are included in the bindings and it is for example possible to create DBus services or use existing DBus services.

The API is very close to the C API and as such not very convenient to use yet, but more convenient APIs can be built on top of this in external crates or maybe in future versions of the bindings. More to see later!

No more `Widget::destroy()`

The gtk::Widget::destroy() function is marked as unsafe starting from this release. Calling it on arbitrary widgets can cause all kinds of negative side-effects and should be prevented.

Most usages of destroy() were related to dialogs or other windows. Instead of destroy() the safer close() can be used now, which also allows the window to handle the event.

More subclassing support in `gtk`

This new release features subclassing support for many additional types: IconView, CellRenderers (Pixbuf, Text, Spinner, Progress, Toggle, Accel, Combo, Spin), DrawingArea, Plug, Socket and Fixed.

Together with all the ones that existed in previous releases, the most commonly used types in GTK where subclassing is useful should be covered. If some are missing, please open issues so we can add them.

Conclusion

This release took us a lot of time but as you can see, it was definitely worth it. We expect to provide even more tools to make gtk-rs development as fun as possible and to continue to improve the bindings. More to come soon!

Changes

For the interested ones, here is the list of the merged pull requests:

sys:

glib:

cairo:

sourceview:

atk:

gio:

pango:

gdk-pixbuf:

gdk:

gtk:

pangocairo:

gtk-test:

All this was possible thanks to the gtk-rs/gir project as well:

Thanks to all of our contributors for their (awesome!) work on this release:

Sponsoring gtk-rs development

Thu, 02 Apr 2020 18:00:00 +0000

Hi everyone!

The gtk-rs organization has been created in 2015. The original goal was to bring GTK library and other libraries from the GNOME platform to the Rust language. We now provide 19 bindings and that number will certainly increase even more in the future.

As this number continues to increase, our needs are increasing as well. At the same time, various people were asking in the past how they could support us but we could never give a useful answer to that. To solve this problem we decided to open a “collective” on opencollective. The goal is to raise money to fulfill the project’s needs such as:

Sponsoring hackfests (happening twice a year) would be great, but paying a dinner for everyone or a round of drinks would be a great start!
Remunerating contributors

It would also allow to start improving the project itself more directly:

Pay for a better CI (it’s becoming a huge issue)
Renting a server to run bots and such to make repositories handling easier
Etc…

If you’re using gtk-rs and want/can support us, any donation is very welcome and can be done here.

Simplification and more of everything

Sun, 15 Dec 2019 19:00:00 +0000

Hello everyone, time for a new release!

This time, this is mostly about stabilization and simplification. It means that gtk-rs is now simpler to use and more complete than ever. Let’s take a tour of what’s new(er)!

Macro to make gtk-rs usage far simpler

A big productivity killer when using gtk-rs in the past was the requirement to pass cloned references to objects, or even worse, weak references into signal handler closures. This is still required but to make it more ergonomic, a new clone! macro is provided as part of glib.

See the documentation for various examples on how to use it. The big advantage of the macro is that you don’t have to manually declare new local variables with a different name that are then moved into the closure, but simply have to provide the name of the variable you want to make available in the closure and whether it should be passed as a strong or weak reference. Inside the closure it can then be used as-is and for example upgrading any weak references manually is not necessary. In case of failure of upgrading a weak reference, an optional default return value for the closure can be provided or the closure can be configured to panic.

The macro works on any glib::Object as well as on any Arc and Rc.

As a side-note, it is important to know the difference between strong and weak references and not simply clone (strong reference) everything. By using strong references everywhere, many GTK applications (not only in Rust) currently create reference cycles and therefore have memory leaks. If, for example, you want to pass a reference to your Window into a Button’s clicked signal, you would create a reference cycle between the window, button, signal handler and again the window. This would lead to the whole cycle to be kept alive forever and leaked. The solution to this is to make one of the references a weak reference, in this case the reference to the window that is passed into the clicked signal handler. See also the Rc documentation about reference cycles.

Subclass

The “subclass” cargo feature was removed from all crates and is instead enabled by default with this release. The GObject subclassing support matured a lot over the last months and is ready for wider usage. A basic example for subclassing gtk::Application and gtk::ApplicationWindow can be found here, another example using custom glib::Object subclasses as part of a gtk::ListBox model can be found here and various examples for creating GStreamer elements here.

While there are still subclassing bindings missing for many types, various basic types in the gio, gtk and gstreamer crates are covered already. If something is missing for you, please let us know with an issue or, even better, a pull request.

Thanks to subclassing being a first-class citizen of the bindings, there is also an adapter available for making any std::io::Read available as gio::InputStream and any std::io::Write as gio::OutputStream: gio::ReadInputStream and gio::WriteOutputStream. Adapters in the other direction are available as gio::InputStream::into_read() and gio::OutputStream::into_write().

Futures

The futures support was ported to std Futures and futures 0.3, and as async/await is stabilized now it was also enabled by default. The “futures” feature is not needed anymore.

With the futures support in gio and other modules it is now possible to write applications making use of asynchronous I/O with async/await, which allows writing asynchronous code in a much simpler way that looks close to the equivalent synchronous code. Check async/await stable on the official Rust blog for more details.

An example making use of this with gio’s asynchronous file reading support can be found here. While it is not as streamlined as with native Rust crates like async-std or tokio because of how the gio API works, it nonetheless much more convenient to work with than the previous (but still available) callback-based approach.

Another example that shows integration of gio with generic Rust futures crates can be found here . Each gio::PollableInputStream and gio::PollableOutputStream can be converted into an AsyncRead / AsyncWrite, and by this allows integration with the wider Rust async ecosystem. In this case a gio TCP connection is wrapped in a TLS connection provided by the async-tls crate, which uses rustls as underlying TLS implementation.

GTK4

We have initial GTK4 bindings now, which are the result of @sfanxiang’s GSoC project this year. While not part of this release because GTK4 itself is still not API stable, you can also try it from git. The GTK4 bindings can be found here. Once there are release candidates of GTK4 we will also do alpha releases of the bindings.

Cairo improvements

The cairo bindings now consistently return Results for various functions instead of sometimes Options, sometimes silently failing. Many cairo operations return an actual Surface in an error state if something goes wrong, and this surface will then (usually silently) fail any future operations on it. Instead of returning the surface, an Err is returned now as it should.

GTK Builder improvements

In gtk::Builder UI description files it is possible to declare signal handlers for the widgets. While it’s not possible to connect them automatically to functions in Rust in a safe way, it is now possible for applications to implement the connection logic themselves based on the information from the UI description. gtk::Builder::connect_signals_full() allows to provide closures for each signal handler name that is given in the UI description.

`glib::Value::get` improvements

glib::Value::get() was changed to allow distinguishing between the value containing a None and trying to get a value of the wrong type out of it. This means that it now returns a Result, and also that for types that can’t possibly be None (e.g. integer types), Value::get_some() is provided as a helper to not require unwrapping the returned Option from the normal Value::get().

That’s it for biggest changes. A lot of other small ones are in as well. So enjoy!

Changes

For the interested ones, here is the list of the merged pull requests:

sys:

glib:

cairo:

sourceview:

atk:

gio:

pango:

gdk-pixbuf:

gdk:

gtk:

pangocairo:

gtk-test:

Update to last versions

All this was possible thanks to the gtk-rs/gir project as well:

Thanks to all of our contributors for their (awesome!) work on this release:

gtk-rs blog

New Release

gtk-rs-core

New syntax for glib::clone! and glib::closure!

GLib 2.82 APIs

Trait re-organization for defining new GObject interfaces

Safer borrowing of GObjects and other types from FFI code

gtk4-rs

GTK 4.16 APIs

Changes

New Release

gtk3

gtk-rs-core

Removal of glib channels

Removal of re-exported once_cell crate, use std::cell::OnceCell / std::sync::OnceLock

Re-organized traits in glib

Dynamic types support

gtk4-rs

New Release

Increase of the minimum supported Rust version (MSRV)

Supported versions

Documentation improvements

Switch to bitflags 2.0

gtk-rs-core

New glib::derived_properties macro

Replacement of glib::Continue / glib::Inhibit

Typed constructors

New glib::ValueDelegate macro

gtk4-rs

Blueprint support in gtk::CompositeTemplate

Stop using deprecated StyleContext APIs

Detailed Changes

New release

Increase of the minimum supported Rust version (MSRV)

New #[properties] macro to make using properties in glib::Object subclasses simpler

Quick example

Direct conversions to glib::Value and glib::Variant via From

gdk_pixbuf subclassing support

New glib::CastNone convenience trait

New glib::function_name! macro

glib::GStr, glib::List, glib::PtrSlice, glib::Slice, glib::StrV and related native GLib types

Various code generation improvements

New glib::Object constructors

gio::Application::run() returns an ExitCode

GTK4 4.10 API additions

Add Blueprint UI definition support

Better mapping of C ownership transfer

Spawning of blocking functions on the glib::MainContext

Changes

New release

Update of minimum supported versions

More async support

GTK 4

glib::Object now has a more convenient object builder

GIO objects completion closure doesn’t need to be Send anymore

Added support for #[derive(glib::Variant)] for enums

No need to implement Send and Sync for subclasses anymore

Simpler subclassing for virtual methods

Simpler subclassing for properties

Removing Result<> wrapping in some functions returned values

Transform functions for property bindings are now supported

Construct SimpleAction with ActionEntryBuilder

Changes

New year, new release!

Minimum and latest supported versions of the underlying C libraries

Changes to derive macro names

GLib Variant API improvements and derive macro

Stack allocated types and reducing heap allocations

Main context API improvements

GLib string builder

Multiple improvements on glib::ObjectExt

Bindings wrapper types memory representation optimization

GLib collection types

Cancelling futures spawned on the GLib main context

Dynamic signal connections

Object subclassing improvements

Passing Cairo image surfaces to other threads and getting owned access to its data

GIO bindings improvements

Gdkwayland

GTK3 child properties

New syntax for `glib::clone!` and `glib::closure!`

Removal of re-exported once_cell crate, use `std::cell::OnceCell` / `std::sync::OnceLock`

New `glib::derived_properties` macro

Replacement of `glib::Continue` / `glib::Inhibit`

New `glib::ValueDelegate` macro

Blueprint support in `gtk::CompositeTemplate`

New `#[properties]` macro to make using properties in `glib::Object` subclasses simpler

Direct conversions to `glib::Value` and `glib::Variant` via `From`

`gdk_pixbuf` subclassing support

New `glib::CastNone` convenience trait

New `glib::function_name!` macro

`glib::GStr`, `glib::List`, `glib::PtrSlice`, `glib::Slice`, `glib::StrV` and related native GLib types

New `glib::Object` constructors

`gio::Application::run()` returns an `ExitCode`

Spawning of blocking functions on the `glib::MainContext`

`glib::Object` now has a more convenient object builder

GIO objects completion closure doesn’t need to be `Send` anymore

Added support for `#[derive(glib::Variant)]` for enums

No need to implement `Send` and `Sync` for subclasses anymore

Removing `Result<>` wrapping in some functions returned values

Construct `SimpleAction` with `ActionEntryBuilder`

Multiple improvements on `glib::ObjectExt`

gtk4-rs and `BuilderScope`

The `Value` trait was refactored

No more `new_from_...()` and `new_with_...()`

`glib-macros`

`glib::ThreadPool`

Storage of arbitrary data in `glib::Object`s

`cairo::Error` instead of `cairo::Status`

No more `Widget::destroy()`

More subclassing support in `gtk`

`glib::Value::get` improvements