Crate gtk

source ·

Expand description

Rust GTK 3 bindings

Project site

Rust bindings and wrappers for GTK 3, part of gtk3-rs, a multi-platform GUI toolkit. It is a part of gtk-rs.

GTK 3.22.30 is the lowest supported version for the underlying library.

Minimum supported Rust version

Currently, the minimum supported Rust version is 1.70.0.

Building

gtk expects GTK, GLib and Cairo development files to be installed on your system. See the GTK installation page.

Using

We recommend using crates from crates.io, as demonstrated here.

If you want to track the bleeding edge, use the git dependency instead:

[dependencies]
gtk = { git = "https://github.com/gtk-rs/gtk3-rs.git" }

Avoid mixing versioned and git crates like this:

# This will not compile
[dependencies]
gtk = "0.13"
gtk = { git = "https://github.com/gtk-rs/gtk3-rs.git" }

“Hello, World!” example program

//! GTK needs to be initialized before use by calling init. Creating an Application will call init for you.

use gtk::prelude::*;
use gtk::{Application, ApplicationWindow};

fn main() {
    let app = Application::builder()
        .application_id("org.example.HelloWorld")
        .build();

    app.connect_activate(|app| {
        // We create the main window.
        let win = ApplicationWindow::builder()
            .application(app)
            .default_width(320)
            .default_height(200)
            .title("Hello, World!")
            .build();

        // Don't forget to make all widgets visible.
        win.show_all();
    });

    app.run();
}

The main loop

In a typical GTK application you set up the UI, assign signal handlers and run the main event loop.


use gtk::prelude::*;
use gtk::{Application, ApplicationWindow, Button};

fn main() {
    let application = Application::builder()
        .application_id("com.example.FirstGtkApp")
        .build();

    application.connect_activate(|app| {
        let window = ApplicationWindow::builder()
            .application(app)
            .title("First GTK Program")
            .default_width(350)
            .default_height(70)
            .build();

        let button = Button::with_label("Click me!");
        button.connect_clicked(|_| {
            eprintln!("Clicked!");
        });
        window.add(&button);

        window.show_all();
    });

    application.run();
}

Threads

GTK is not thread-safe. Accordingly, none of this crate’s structs implement Send or Sync.

The thread where init was called is considered the main thread. OS X has its own notion of the main thread and init must be called on that thread. After successful initialization, calling any gtk or gdk functions (including init) from other threads will panic.

Any thread can schedule a closure to be run by the main loop on the main thread via glib::idle_add or glib::timeout_add. While working with GTK you might need the glib::idle_add_local or glib::timeout_add_local version without the Send bound. Those may only be called from the main thread.

Panics

The gtk and gdk crates have some run-time safety and contract checks.

Any constructor or free function will panic if called before init or on a non-main thread.
Any &str or &Path parameter with an interior null (\0) character will cause a panic.
Some functions will panic if supplied out-of-range integer parameters. All such cases will be documented individually but they are not yet.
A panic in a closure that handles signals or in any other closure passed to a gtk function will abort the process.

Features

Library versions

By default this crate provides only GTK 3.22.30 APIs. You can access additional functionality by selecting one of the v3_24, etc. features.

Cargo.toml example:

[dependencies.gtk]
version = "0.x.y"
features = ["v3_24"]

Take care when choosing the version to target: some of your users might not have easy access to the latest ones. The higher the version, the fewer users will have it installed.