qtrs 0.2.5

qtrs - A type-safe, builder-pattern-driven Qt6 GUI library for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196

//! # qtrs — Rust-style Qt6 bindings
//!
//! A type-safe, builder-pattern-driven Qt6 GUI library for Rust.
//! Built on [`cxx`] for C++ interop, with RAII memory management,
//! signal/callback bridging, and a fluent builder API.
//!
//! ## Installation
//!
//! Add to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! qtrs = "0.2.5"
//! ```
//!
//! ## Features
//!
//! - **`ui`** — enables `.ui` file loading via `QUiLoader`.
//!   Requires `qt6-tools-dev` (Debian) or equivalent.
//!
//! ### Enable features:
//!
//! ```toml
//! [dependencies]
//! qtrs = { version = "0.2.5", features = ["ui"] }
//! ```
//!
//! ## Design principles
//!
//! - Builder pattern everywhere — chain `.title("X").size(800, 600).show()`
//! - RAII cleanup — widgets are automatically deleted on `Drop`, with
//!   parent-child awareness (widgets with a Qt parent skip C++ deletion to
//!   avoid double-free).
//! - Type-safe layout ownership — adding a widget to a layout transfers
//!   ownership; the layout drops its children when it goes out of scope.
//! - Zero-cost signal bridging — Qt signals invoke Rust closures via a
//!   single global trampoline; context tokens are plain `u64` values.
//!
//! ## Architecture
//!
//! | Layer | Crate module | What it does |
//! |---|---|---|
//! | C++ glue | *(internal)* | Inline wrappers around Qt6 API |
//! | cxx bridge | [`ffi`] | Opaque C++ types + `extern "C++"` signatures |
//! | Safe wrappers | [`app`], [`widget`], [`button`], [`label`], [`input`], [`layout`] | Builder patterns, RAII, signals |
//! | Public API | *(this module)* | Re-exports of all safe types |
//!
//! ## Widget gallery
//!
//! | Type | Qt class | Signals |
//! |---|---|---|
//! | [`Application`] | `QApplication` | — |
//! | [`Widget`] | `QWidget` | — |
//! | [`PushButton`] | `QPushButton` | `on_clicked` |
//! | [`Label`] | `QLabel` | — |
//! | [`LineEdit`] | `QLineEdit` | `on_return_pressed` |
//! | [`CheckBox`] | `QCheckBox` | `on_toggled(bool)` |
//! | [`ComboBox`] | `QComboBox` | `on_current_text_changed`<br>`on_current_index_changed(i32)` |
//! | [`TextEdit`] | `QTextEdit` | `on_text_changed` |
//! | [`Slider`] | `QSlider` | `on_value_changed(i32)` |
//! | [`ProgressBar`] | `QProgressBar` | — |
//! | [`RadioButton`] | `QRadioButton` | `on_toggled(bool)` |
//! | [`GroupBox`] | `QGroupBox` | — |
//! | [`TabWidget`] | `QTabWidget` | `on_current_changed(i32)` |
//! | [`SpinBox`] | `QSpinBox` | `on_value_changed(i32)` |
//! | [`Menu`] | `QMenu` | — |
//! | [`MenuBar`] | `QMenuBar` | — |
//! | [`Timer`] | `QTimer` | `on_timeout`<br>`single_shot(ms, fn)` |
//! | [`VBoxLayout`] | `QVBoxLayout` | — |
//! | [`HBoxLayout`] | `QHBoxLayout` | — |
//! | [`GridLayout`] | `QGridLayout` | — |
//! | [`FileDialog`] | `QFileDialog` | `open_file`, `save_file`, `select_directory` (static) |
//! | `dialog` | `QMessageBox` | `information`, `warning`, `critical`, `question` |
//!
//! ## Quick example
//!
//! ```no_run
//! use qtrs::prelude::*;
//!
//! fn main() {
//!     let app = Application::new();
//!
//!     let mut window = Widget::new()
//!         .title("Hello, qtrs!")
//!         .size(400, 300)
//!         .build();
//!
//!     let mut layout = VBoxLayout::with_parent(&window);
//!
//!     let btn = PushButton::new("Click me")
//!         .on_clicked(|| println!("clicked!"))
//!         .build();
//!     let label = Label::new("Welcome!").build();
//!
//!     layout.add_widget(Box::new(btn));
//!     layout.add_widget(Box::new(label));
//!
//!     window.set_vlayout(layout.layout_ptr());
//!     window.show();
//!
//!     app.exec();
//! }
//! ```
//!
//! ## Thread safety
//!
//! Qt GUI classes are **not thread-safe**. All widget creation, mutation,
//! and the event loop must happen on the main thread. This library does
//! not add any synchronisation — you are responsible for staying on the
//! right thread, just as in C++ Qt.
//!
//! ## Linking
//!
//! Qt6 (Core, Gui, Widgets) must be installed with development headers.
//! The build script uses `qmake` to locate them. If you see
//! `Qt not found!`, install the `qt6-base-dev` package
//! (or equivalent) for your distribution.

pub mod app;
pub mod button;
pub mod checkbox;
pub mod combobox;
pub mod conn;
pub mod dialog;
pub mod ffi;
pub mod grid;
pub mod groupbox;
pub mod input;
pub mod label;
pub mod layout;
pub mod menu;
pub mod progressbar;
pub mod radiobutton;
pub mod signals;
pub mod slider;
pub mod spinbox;
pub mod tabwidget;
pub mod textedit;
pub mod timer;
mod signal;
pub mod widget;
pub mod filedialog;
pub mod point;


#[cfg(feature = "ui")]
pub mod loader;

// ================================================
// Re-Exports
// ================================================

pub use app::Application;
pub use button::PushButton;
pub use checkbox::CheckBox;
pub use combobox::ComboBox;
pub use grid::GridLayout;
pub use input::LineEdit;
pub use label::Label;
pub use layout::{AsLayout, HBoxLayout, VBoxLayout};
pub use slider::Slider;
pub use textedit::TextEdit;
pub use timer::Timer;
pub use widget::{AsWidget, FoundWidget, Widget, WidgetKind};
pub use progressbar::ProgressBar;
pub use radiobutton::RadioButton;
pub use groupbox::GroupBox;
pub use tabwidget::TabWidget;
pub use spinbox::SpinBox;
pub use menu::{Menu, MenuBar};
pub use conn::{ConnectExt, ConnType, SignalMeta, SlotMeta};
pub use filedialog::FileDialog;
pub use point::Point;


#[cfg(feature = "ui")]
pub use loader::UiLoader;


// ============================================================
// Prelude
// ============================================================

/// Prelude: commonly used types and traits.
pub mod prelude {
    pub use super::{
        Application, AsLayout, AsWidget, CheckBox, ComboBox, FoundWidget,
        GridLayout, HBoxLayout, Label, LineEdit, PushButton, Slider,
        TextEdit, Timer, VBoxLayout, Widget, WidgetKind,
        ProgressBar, RadioButton, GroupBox, TabWidget, SpinBox, Menu, MenuBar,
        ConnectExt, ConnType, signals, FileDialog, Point
    };
    
    #[cfg(feature = "ui")]
    pub use super::UiLoader;
}