[−][src]Crate gtk
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:
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("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
initor on a non-main thread. -
Any
&stror&Pathparameter 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!
Re-exports
pub use prelude::*; |
Modules
| functions | |
| prelude | Traits and essential types intended for blanket imports. |
| xlib |