Crate gtk

Expand description

GTK+ 3 bindings

This library contains safe Rust bindings for GTK+ 3, a multi-platform GUI toolkit. It’s a part of Gtk-rs.

The library is a work in progress: expect missing bindings and breaking changes. A steadily increasing share of the code is machine-generated from GObject introspection metadata. The API docs were converted from the upstream ones so until they’ve all been reviewed there will be incongruities with actual Rust APIs.

Hello World

extern crate gtk;
use gtk::prelude::*;
use gtk::{ButtonsType, DialogFlags, MessageType, MessageDialog, Window};

fn main() {
    if gtk::init().is_err() {
        println!("Failed to initialize GTK.");
        return;
    }
    MessageDialog::new(None::<&Window>,
                       DialogFlags::empty(),
                       MessageType::Info,
                       ButtonsType::Ok,
                       "Hello World").run();
}

Initialization

GTK+ needs to be initialized before use by calling init or Application::new. You only need to do it once and there is no ‘finalize’.

The main loop

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

extern crate gtk;
extern crate gio;

// To import all needed traits.
use gtk::prelude::*;
use gio::prelude::*;

use std::env;

fn main() {
    let uiapp = gtk::Application::new(Some("org.gtkrsnotes.demo"),
                                      gio::ApplicationFlags::FLAGS_NONE)
                                 .expect("Application::new failed");
    uiapp.connect_activate(|app| {
        // We create the main window.
        let win = gtk::ApplicationWindow::new(app);

        // Then we set its size and a title.
        win.set_default_size(320, 200);
        win.set_title("Basic example");

        // Don't forget to make all widgets visible.
        win.show_all();
    });
    uiapp.run(&env::args().collect::<Vec<_>>());
}

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. This crate has versions of those functions without the Send bound, which may only be called from the main thread: idle_add, timeout_add.

Panics

This and the gdk crate 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’re not yet.

A panic in a closure will abort the process.

Crate features

Library versions

By default this crate provides only GTK+ 3.14 APIs. You can access more modern APIs by selecting one of the following features: v3_14, v3_16, etc.

Cargo.toml example:

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

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.

Lgpl-docs

The Gtk-rs crates come with API docs missing because of licensing incompatibilty. You can embed those docs locally via the embed-lgpl-docs feature, e.g.

> cargo doc --features embed-lgpl-docs

Its counterpart purge-lgpl-docs removes those docs regardless of edits.

These features rewrite the crate sources so it’s sufficient to enable them once. Omitting them in the following cargo invocations will not undo their effects!