# Rust GTK 3 bindings

[Project site](http://gtk-rs.org/)

__Rust__ bindings and wrappers for __GTK 3__, part of [gtk3-rs](https://github.com/gtk-rs/gtk3-rs),
a multi-platform GUI toolkit. It is a part of [gtk-rs](http://gtk-rs.org/).

GTK __3.18__ is the lowest supported version for the underlying library.

## Minimum supported Rust version

Currently, the minimum supported Rust version is `1.56.0`.

## Building

__gtk__ expects __GTK__, __GLib__ and __Cairo__ development files to be installed on your system.
See the [GTK installation page](https://www.gtk.org/docs/installations/).

## Using

We recommend using [crates from crates.io](https://crates.io/keywords/gtk-rs),
as [demonstrated here](http://gtk-rs.org/#using).

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

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

Avoid mixing versioned and git crates like this:

```toml
# 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 [`fn@init`]. Creating an
[`struct@Application`] will call [`fn@init`] for you.

```rust,no_run
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.

```rust,no_run

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 [`fn@init`] was called is considered the main thread. OS X has
its own notion of the main thread and [`fn@init`] must be called on that thread.
After successful initialization, calling any [`gtk`](mod@crate) or [`mod@gdk`] functions
(including [`fn@init`]) from other threads will `panic`.

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

# Panics

The [`gtk`](mod@crate) and [`mod@gdk`] crates have some run-time safety and contract checks.

- Any constructor or free function will panic if called before [`fn@init`] or on
a non-main thread.

- Any [`&str`] or [`&Path`](std::path::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`](mod@crate) function will abort the process.

# Features

## Library versions

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

`Cargo.toml` example:

```toml
[dependencies.gtk]
version = "0.x.y"
features = ["v3_20"]
```

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.

## Documentation

Most of this documentation is generated from the C API.

Until all parts of the documentation have been reviewed there will be incongruities
with the actual Rust API.

 * [Rust API - Stable](https://gtk-rs.org/gtk3-rs/stable/latest/docs/gtk/)
 * [Rust API - Development](https://gtk-rs.org/gtk3-rs/git/docs/gtk)
 * [C API](https://developer.gnome.org/gtk/stable/)
 * [GTK Installation instructions](https://www.gtk.org/docs/installations/)

Generate the docs:

```shell
> cargo doc --features dox
```

(if the installed GTK+ version is lower than 3.16, adjust the feature name accordingly).

## Contribute

Contributor you're welcome!

See the general [bindings documentation](https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/).

Most of the bindings ([`src/auto`](src/auto)) are generated by [gir](https://github.com/gtk-rs/gir) using [this configuration file](Gir.toml). After editing `Gir.toml` the sources can be regenerated with

```shell
> make gir
```

When opening a PR please put the changes to the `src/auto` directory in a separate commit.

You may also wish to run `cargo clippy -- -D warnings` and check that you're clean because
otherwise you may be surprised when CI fails.

## See Also

 * [atk](https://crates.io/crates/atk)
 * [cairo](https://crates.io/crates/cairo-rs)
 * [gdk](https://crates.io/crates/gdk)
 * [gdk-pixbuf](https://crates.io/crates/gdk-pixbuf)
 * [gio](https://crates.io/crates/gio)
 * [glib](https://crates.io/crates/glib)
 * [pango](https://crates.io/crates/pango)

But also:

 * [gtk-rs project overview](https://gtk-rs.org)
 * [General `GLib` family types and object system overview](mod@glib)
 * [GTK documentation](https://www.gtk.org/docs/)

## License

__gtk__ is available under the MIT License, please refer to it.