Crate gtk [−] [src]
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.
See also:
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:
fn main() { gtk::init().unwrap(); // Create the main window. let window = Window::new(WindowType::Toplevel); // UI initialization. // ... // Don't forget to make all widgets visible. window.show_all(); // Handle closing of the window. window.connect_delete_event(|_, _| { // Stop the main loop. gtk::main_quit(); // Let the default handler destroy the window. Inhibit(false) }); // Run the main loop. gtk::main(); }
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.4 APIs. You can access more
modern APIs by selecting one of the following features: v3_6
, v3_8
,
v3_10
, v3_12
, v3_14
, v3_16
.
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!
Reexports
pub use prelude::*; |
Modules
functions | |
prelude |
Traits and essential types inteded for blanket imports. |