Expand description
§Rust GTK 4 bindings
The project website is here.
Rust bindings of GTK 4, part of gtk4-rs.
This library contains safe Rust bindings for GTK 4, a multi-platform GUI toolkit. It is a part of gtk-rs.
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.
For a gentle introduction to gtk-rs we recommend the online book GUI development with Rust and GTK 4.
See also:
- gtk-rs project overview
- General
GLibfamily types and object system overview - GTK documentation
- GTK Visual Index
§Minimum supported Rust version
Currently, the minimum supported Rust version is 1.70.
§“Hello, World!” example program
GTK needs to be initialized before use by calling init. Creating an
Application will call init for you.
The gtk4 crate is usually renamed to gtk. You can find an example in
the features section for how to do this globally in your Cargo.toml.
use gtk4 as gtk;
use gtk::prelude::*;
use gtk::{glib, Application, ApplicationWindow};
fn main() -> glib::ExitCode {
let app = Application::builder()
.application_id("org.example.HelloWorld")
.build();
app.connect_activate(|app| {
// We create the main window.
let window = ApplicationWindow::builder()
.application(app)
.default_width(320)
.default_height(200)
.title("Hello, World!")
.build();
// Show the window.
window.present();
});
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 gtk4 as gtk;
use gtk::prelude::*;
use gtk::{glib, Application, ApplicationWindow, Button};
fn main() -> glib::ExitCode {
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.set_child(Some(&button));
window.present();
});
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
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 are not yet.
-
A panic in a closure that handles signals or in any other closure passed to a
gtkfunction will abort the process.
§Features
§Library versions
By default this crate provides only GTK 4.0 APIs. You can access additional
functionality by selecting one of the v4_2, v4_4, etc. features.
Cargo.toml example:
[dependencies.gtk]
package = "gtk4"
version = "0.x.y"
features = ["v4_2"]
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
- The Rust API Stable/Development
- Book Stable/Development
- Examples
- The C API
- GTK Installation Instructions
§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/gtk4-rs.git", package = "gtk4" }
Avoid mixing versioned and git crates like this:
# This will not compile
[dependencies]
gdk = {version = "0.1", package = "gdk4"}
gtk = { git = "https://github.com/gtk-rs/gtk4-rs.git", package = "gtk4" }
§Features
| Feature | Description |
|---|---|
v4_16 | Enable the new APIs part of GTK 4.16 |
v4_14 | Enable the new APIs part of GTK 4.14 |
v4_12 | Enable the new APIs part of GTK 4.12 |
v4_10 | Enable the new APIs part of GTK 4.10 |
v4_8 | Enable the new APIs part of GTK 4.8 |
v4_6 | Enable the new APIs part of GTK 4.6 |
v4_4 | Enable the new APIs part of GTK 4.4 |
v4_2 | Enable the new APIs part of GTK 4.2 |
gnome_47 | Enable all version feature flags of this crate and its dependencies to match the GNOME 47 SDK |
gnome_46 | Enable all version feature flags of this crate and its dependencies to match the GNOME 46 SDK |
gnome_45 | Enable all version feature flags of this crate and its dependencies to match the GNOME 45 SDK |
gnome_44 | Enable all version feature flags of this crate and its dependencies to match the GNOME 44 SDK |
gnome_43 | Enable all version feature flags of this crate and its dependencies to match the GNOME 43 SDK |
gnome_42 | Enable all version feature flags of this crate and its dependencies to match the GNOME 42 SDK |
unsafe-assume-initialized | Disable checks that gtk is initialized, for use in C ABI libraries |
xml_validation | Enable xml_validation feature of gtk4-macros |
blueprint | Enable blueprint feature of gtk4-macros |
§See Also
§License
The Rust bindings of gtk4 are available under the MIT License, please refer to it.
Re-exports§
pub use subclass::widget::TemplateChild;pub use cairo;pub use gdk;pub use gdk_pixbuf;pub use gio;pub use glib;pub use graphene;pub use gsk;pub use gtk4_sys as ffi;pub use pango;
Modules§
- Builder pattern types.
- Traits intended for blanket imports.
- Traits intended for creating custom types.
Structs§
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Accessible
List v4_14GLib type: Boxed type with copy-on-clone semantics. - Accessible
Range v4_10GLib type: GObject with reference counted clone semantics. - Accessible
Text v4_14GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Alert
Dialog v4_10GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- AppChooser
Deprecated GLib type: GObject with reference counted clone semantics. - AppChooser
Button Deprecated GLib type: GObject with reference counted clone semantics. - AppChooser
Dialog Deprecated GLib type: GObject with reference counted clone semantics. - AppChooser
Widget Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Assistant
Deprecated GLib type: GObject with reference counted clone semantics. - Assistant
Page Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Inline allocated boxed type with stack copy semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- An implementation of
BuilderScopethat can bind Rust callbacks. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Cell
Area Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Area Box Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Area Context Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Editable Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Layout Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Renderer Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Renderer Accel Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Renderer Combo Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Renderer Pixbuf Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Renderer Progress Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Renderer Spin Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Renderer Spinner Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Renderer Text Deprecated GLib type: GObject with reference counted clone semantics. - Cell
Renderer Toggle Deprecated GLib type: GObject with reference counted clone semantics. - Cell
View Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- Color
Button Deprecated GLib type: GObject with reference counted clone semantics. - Color
Chooser Deprecated GLib type: GObject with reference counted clone semantics. - Color
Chooser Dialog Deprecated GLib type: GObject with reference counted clone semantics. - Color
Chooser Widget Deprecated GLib type: GObject with reference counted clone semantics. - Color
Dialog v4_10GLib type: GObject with reference counted clone semantics. - Color
Dialog Button v4_10GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- Column
View Cell v4_12GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- Column
View Row v4_12GLib type: GObject with reference counted clone semantics. - Column
View Sorter v4_10GLib type: GObject with reference counted clone semantics. - Combo
Box Deprecated GLib type: GObject with reference counted clone semantics. - Combo
BoxText Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Inline allocated boxed type with stack copy semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Dialog
Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Entry
Completion Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- File
Chooser Deprecated GLib type: GObject with reference counted clone semantics. - File
Chooser Dialog Deprecated GLib type: GObject with reference counted clone semantics. - File
Chooser Native Deprecated GLib type: GObject with reference counted clone semantics. - File
Chooser Widget Deprecated GLib type: GObject with reference counted clone semantics. - File
Dialog v4_10GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- File
Launcher v4_10GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Font
Button Deprecated GLib type: GObject with reference counted clone semantics. - Font
Chooser Deprecated GLib type: GObject with reference counted clone semantics. - Font
Chooser Dialog Deprecated GLib type: GObject with reference counted clone semantics. - Font
Chooser Widget Deprecated GLib type: GObject with reference counted clone semantics. - Font
Dialog v4_10GLib type: GObject with reference counted clone semantics. - Font
Dialog Button v4_10GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Graphics
Offload v4_14GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Icon
View Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- InfoBar
Deprecated GLib type: GObject with reference counted clone semantics. - Inscription
v4_8GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- List
Header v4_12GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- List
Scroll Flags v4_12 - List
Store Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- Lock
Button Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Message
Dialog Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Inline allocated boxed type with stack copy semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Inline allocated boxed type with stack copy semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Boxed type with copy-on-clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Print
Dialog v4_14GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Print
Setup v4_14GLib type: Shared boxed type with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Inline allocated boxed type with stack copy semantics.
- GLib type: Shared boxed type with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Inline allocated boxed type with stack copy semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Scroll
Info v4_12GLib type: Shared boxed type with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Section
Model v4_12GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Statusbar
Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Style
Context Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: Inline allocated boxed type with stack copy semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Tree
Drag Dest Deprecated GLib type: GObject with reference counted clone semantics. - Tree
Drag Source Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: Inline allocated boxed type with stack copy semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Tree
Model Deprecated GLib type: GObject with reference counted clone semantics. - Tree
Model Filter Deprecated GLib type: GObject with reference counted clone semantics. - Tree
Model Flags Deprecated - Tree
Model Sort Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: Boxed type with copy-on-clone semantics.
- GLib type: Boxed type with copy-on-clone semantics.
- Tree
Selection Deprecated GLib type: GObject with reference counted clone semantics. - Tree
Sortable Deprecated GLib type: GObject with reference counted clone semantics. - Tree
Store Deprecated GLib type: GObject with reference counted clone semantics. - Tree
View Deprecated GLib type: GObject with reference counted clone semantics. - Tree
View Column Deprecated GLib type: GObject with reference counted clone semantics. - UriLauncher
v4_10GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- Volume
Button Deprecated GLib type: GObject with reference counted clone semantics. - GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
- GLib type: GObject with reference counted clone semantics.
Enums§
- Collation
v4_10 - Content
Fit v4_8 - Dialog
Error v4_10 - Font
Level v4_10 - Font
Rendering v4_16 - List
TabBehavior v4_12 - Natural
Wrap Mode v4_6 - Sort
Column Deprecated - Symbolic
Color v4_6
Constants§
Statics§
Functions§
- Tries to initialize GTK.
- Returns
trueif GTK has been initialized. - Returns
trueif GTK has been initialized and this is the main thread. - render_
activity Deprecated - render_
arrow Deprecated - render_
background Deprecated - render_
check Deprecated - render_
expander Deprecated - render_
focus Deprecated - render_
frame Deprecated - render_
handle Deprecated - render_
icon Deprecated - render_
layout Deprecated - render_
line Deprecated - render_
option Deprecated - Informs this crate that GTK has been initialized and the current thread is the main one.
- show_
uri Deprecated - show_
uri_ full Deprecated - show_
uri_ full_ future Deprecated - tree_
create_ row_ drag_ content Deprecated - tree_
get_ row_ drag_ data Deprecated