gtk/
lib.rs

1// Copyright 2013-2018, The Gtk-rs Project Developers.
2// See the COPYRIGHT file at the top-level directory of this distribution.
3// Licensed under the MIT license, see the LICENSE file or <http://opensource.org/licenses/MIT>
4
5//! # GTK+ 3 bindings
6//!
7//! This library contains safe Rust bindings for [GTK+ 3](http://www.gtk.org), a
8//! multi-platform GUI toolkit. It's a part of [Gtk-rs](http://gtk-rs.org/).
9//!
10//! The library is a work in progress: expect missing bindings and breaking
11//! changes. A steadily increasing share of the code is machine-generated from
12//! `GObject` introspection metadata. The API docs were converted from the
13//! upstream ones so until they've all been reviewed there will be incongruities
14//! with actual Rust APIs.
15//!
16//! See also:
17//!
18//! - [Gtk-rs documentation overview](http://gtk-rs.org/docs/)
19//!
20//! - [General `GLib` family types and object system overview](../glib/index.html)
21//!
22//! - [GTK+ documentation](http://www.gtk.org/documentation.php)
23//!
24//! # Hello World
25//!
26//! ```no_run
27//! extern crate gtk;
28//! use gtk::prelude::*;
29//! use gtk::{ButtonsType, DialogFlags, MessageType, MessageDialog, Window};
30//!
31//! fn main() {
32//!     if gtk::init().is_err() {
33//!         println!("Failed to initialize GTK.");
34//!         return;
35//!     }
36//!     MessageDialog::new(None::<&Window>,
37//!                        DialogFlags::empty(),
38//!                        MessageType::Info,
39//!                        ButtonsType::Ok,
40//!                        "Hello World").run();
41//! }
42//! ```
43//!
44//! # Initialization
45//!
46//! GTK+ needs to be initialized before use by calling [`init`](fn.init.html) or
47//! [`Application::new`](struct.Application.html#method.new). You only need to
48//! do it once and there is no 'finalize'.
49//!
50//! # The main loop
51//!
52//! In a typical GTK+ application you set up the UI, assign signal handlers
53//! and run the main event loop:
54//!
55//! ```no_run
56//! extern crate gtk;
57//! extern crate gio;
58//!
59//! // To import all needed traits.
60//! use gtk::prelude::*;
61//! use gio::prelude::*;
62//!
63//! use std::env;
64//!
65//! fn main() {
66//!     let uiapp = gtk::Application::new(Some("org.gtkrsnotes.demo"),
67//!                                       gio::ApplicationFlags::FLAGS_NONE)
68//!                                  .expect("Application::new failed");
69//!     uiapp.connect_activate(|app| {
70//!         // We create the main window.
71//!         let win = gtk::ApplicationWindow::new(app);
72//!
73//!         // Then we set its size and a title.
74//!         win.set_default_size(320, 200);
75//!         win.set_title("Basic example");
76//!
77//!         // Don't forget to make all widgets visible.
78//!         win.show_all();
79//!     });
80//!     uiapp.run(&env::args().collect::<Vec<_>>());
81//! }
82//! ```
83//!
84//! # Threads
85//!
86//! GTK+ is not thread-safe. Accordingly, none of this crate's structs implement
87//! `Send` or `Sync`.
88//!
89//! The thread where `init` was called is considered the main thread. OS X has
90//! its own notion of the main thread and `init` must be called on that thread.
91//! After successful initialization, calling any `gtk` or `gdk` functions
92//! (including `init`) from other threads will `panic`.
93//!
94//! Any thread can schedule a closure to be run by the main loop on the main
95//! thread via [`glib::idle_add`](../glib/source/fn.idle_add.html) or
96//! [`glib::timeout_add`](../glib/source/fn.timeout_add.html). This crate has
97//! versions of those functions without the `Send` bound, which may only be
98//! called from the main thread: [`idle_add`](fn.idle_add.html),
99//! [`timeout_add`](fn.timeout_add.html).
100//!
101//! # Panics
102//!
103//! This and the `gdk` crate have some run-time safety and contract checks:
104//!
105//! - Any constructor or free function will panic if called before `init` or on
106//! a non-main thread.
107//!
108//! - Any `&str` or `&Path` parameter with an interior null (`\0`) character will
109//! cause a panic.
110//!
111//! - Some functions will panic if supplied out-of-range integer parameters. All
112//! such cases will be documented individually but they're not yet.
113//!
114//! **A panic in a closure will abort the process.**
115//!
116//! # Crate features
117//!
118//! ## Library versions
119//!
120//! By default this crate provides only GTK+ 3.14 APIs. You can access more
121//! modern APIs by selecting one of the following features: `v3_14`, `v3_16`, etc.
122//!
123//! `Cargo.toml` example:
124//!
125//! ```toml
126//! [dependencies.gtk]
127//! version = "0.x.y"
128//! features = ["v3_16"]
129//! ```
130//!
131//! **Take care when choosing the version to target: some of your users might
132//! not have easy access to the latest ones.** The higher the version, the fewer
133//! users will have it installed.
134//!
135//! ## Lgpl-docs
136//!
137//! The Gtk-rs crates come with API docs missing because of licensing
138//! incompatibilty. You can embed those docs locally via the `embed-lgpl-docs`
139//! feature, e.g.
140//!
141//! ```shell
142//! > cargo doc --features embed-lgpl-docs
143//! ```
144//!
145//! Its counterpart `purge-lgpl-docs` removes those docs regardless of edits.
146//!
147//! These features **rewrite the crate sources** so it's sufficient to enable
148//! them once. **Omitting them in the following cargo invocations will not undo
149//! their effects!**
150
151#![cfg_attr(feature = "cargo-clippy", allow(let_unit_value))]
152#![cfg_attr(feature = "cargo-clippy", allow(new_without_default))]
153#![cfg_attr(feature = "cargo-clippy", allow(type_complexity))]
154#![cfg_attr(feature = "cargo-clippy", allow(transmute_ptr_to_ref))]
155#![cfg_attr(feature = "cargo-clippy", allow(trivially_copy_pass_by_ref))]
156#![cfg_attr(feature = "cargo-clippy", allow(derive_hash_xor_eq))]
157#![allow(deprecated)]
158
159extern crate libc;
160#[macro_use]
161extern crate bitflags;
162#[macro_use]
163extern crate lazy_static;
164
165extern crate cairo_sys;
166extern crate gdk_pixbuf_sys;
167extern crate gdk_sys;
168extern crate gio_sys;
169extern crate glib_sys;
170extern crate gobject_sys;
171extern crate gtk_sys;
172extern crate pango_sys;
173#[macro_use]
174extern crate glib;
175extern crate atk;
176extern crate cairo;
177extern crate gdk;
178extern crate gdk_pixbuf;
179extern crate gio;
180extern crate pango;
181
182#[cfg(feature = "futures")]
183extern crate fragile;
184#[cfg(feature = "futures")]
185extern crate futures;
186
187pub use glib::{Cast, Continue, Error, IsA, Object, StaticType, ToValue, Type, TypedValue, Value};
188
189pub mod xlib;
190
191pub const STYLE_PROVIDER_PRIORITY_FALLBACK: u32 =
192    gtk_sys::GTK_STYLE_PROVIDER_PRIORITY_FALLBACK as u32;
193pub const STYLE_PROVIDER_PRIORITY_THEME: u32 = gtk_sys::GTK_STYLE_PROVIDER_PRIORITY_THEME as u32;
194pub const STYLE_PROVIDER_PRIORITY_SETTINGS: u32 =
195    gtk_sys::GTK_STYLE_PROVIDER_PRIORITY_SETTINGS as u32;
196pub const STYLE_PROVIDER_PRIORITY_APPLICATION: u32 =
197    gtk_sys::GTK_STYLE_PROVIDER_PRIORITY_APPLICATION as u32;
198pub const STYLE_PROVIDER_PRIORITY_USER: u32 = gtk_sys::GTK_STYLE_PROVIDER_PRIORITY_USER as u32;
199
200#[macro_use]
201mod rt;
202
203#[cfg_attr(feature = "cargo-clippy", allow(too_many_arguments))]
204#[cfg_attr(feature = "cargo-clippy", allow(match_same_arms))]
205#[cfg_attr(feature = "cargo-clippy", allow(let_and_return))]
206#[cfg_attr(feature = "cargo-clippy", allow(many_single_char_names))]
207#[cfg_attr(feature = "cargo-clippy", allow(wrong_self_convention))]
208mod auto;
209
210mod app_chooser;
211mod application;
212mod application_window;
213mod border;
214mod buildable;
215mod builder;
216mod cell_renderer_pixbuf;
217mod clipboard;
218mod color_button;
219mod color_chooser;
220mod combo_box;
221mod dialog;
222mod drag_context;
223mod entry_buffer;
224mod entry_completion;
225mod enums;
226mod file_chooser_dialog;
227mod fixed;
228#[cfg(any(feature = "v3_18", feature = "dox"))]
229mod flow_box;
230mod im_context_simple;
231mod invisible;
232#[cfg(any(feature = "v3_16", feature = "dox"))]
233mod list_box;
234mod list_store;
235mod menu;
236mod message_dialog;
237mod notebook;
238#[cfg(any(feature = "v3_22", feature = "dox"))]
239mod pad_action_entry;
240#[cfg(any(feature = "v3_22", feature = "dox"))]
241mod pad_controller;
242mod page_range;
243mod print_settings;
244mod radio_button;
245mod radio_menu_item;
246mod radio_tool_button;
247mod recent_chooser_dialog;
248mod recent_data;
249mod requisition;
250mod response_type;
251mod selection_data;
252mod signal;
253mod switch;
254mod target_entry;
255mod target_list;
256mod text_buffer;
257mod text_iter;
258mod tree_model_filter;
259mod tree_model_sort;
260mod tree_path;
261mod tree_row_reference;
262mod tree_sortable;
263mod tree_store;
264mod widget;
265mod window;
266
267#[macro_use]
268#[cfg(feature = "subclassing")]
269pub mod subclass;
270
271pub mod prelude;
272
273pub use auto::functions::*;
274pub use auto::*;
275pub use prelude::*;
276pub use rt::*;
277pub use signal::*;
278
279pub use gdk::Rectangle as Allocation;
280pub use gdk::Rectangle;
281
282pub use app_chooser::AppChooser;
283pub use border::Border;
284pub use entry_buffer::EntryBuffer;
285#[cfg(any(feature = "v3_22", feature = "dox"))]
286pub use pad_action_entry::PadActionEntry;
287pub use page_range::PageRange;
288pub use recent_data::RecentData;
289pub use requisition::Requisition;
290pub use response_type::ResponseType;
291pub use target_entry::TargetEntry;
292pub use tree_sortable::SortColumn;
293pub use widget::TickCallbackId;