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 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347
/* LICENSE BEGIN This file is part of the SixtyFPS Project -- https://sixtyfps.io Copyright (c) 2020 Olivier Goffart <olivier.goffart@sixtyfps.io> Copyright (c) 2020 Simon Hausmann <simon.hausmann@sixtyfps.io> SPDX-License-Identifier: GPL-3.0-only This file is also available under commercial licensing terms. Please contact info@sixtyfps.io for more information. LICENSE END */ /*! # SixtyFPS This crate is the main entry point for embedding user interfaces designed with [SixtyFPS UI](https://www.sixtyfps.io/) in Rust programs. Included in this documentation is also the [language reference](langref/index.html). ## How to use: The user interfaces are described in the `.60` design markup language. There are two ways of including the design in Rust: - The `.60` code is inline in a macro. - The `.60` code in external files compiled with `build.rs` This markup code is translated to Rust code and each component is turned into a Rust struct with functions to instantiated, show or access properties. This documentation includes an [example][`generated_code::SampleComponent`] of how the API looks like. ### The .60 code in a macro This method combines your Rust code with the `.60` design markup in one file, using a macro: ```rust sixtyfps::sixtyfps!{ HelloWorld := Text { text: "hello world"; color: green; } } fn main() { # return; // Don't run a window in an example HelloWorld::new().run() } ``` ### The .60 file in external files compiled with `build.rs` This method allows you to a separate `.60` file on the file system, which works well if your design becomes bigger and you split it up across multiple files. You need to use a so-called [build script](https://doc.rust-lang.org/cargo/reference/build-scripts.html) to trigger the compilation of the `.60` file. In your Cargo.toml: FIXME! set the version ```toml [package] ... build = "build.rs" [dependencies] sixtyfps = "*" ... [build-dependencies] sixtyfps-build = "*" ``` In the `build.rs` file: ```ignore fn main() { sixtyfps_build::compile("ui/hello.60"); } ``` Then in your main file ```ignore sixtyfps::include_modules!(); fn main() { HelloWorld::new().run() } ``` ### Types The types used for properties in `.60` design markup each translate to specific types in Rust. The follow table summarizes the entire mapping: | `.60` Type | Rust Type | Note | | --- | --- | --- | | `int` | `i32` | | | `float` | `f32` | | | `string` | [`SharedString`] | A reference-counted string type that can be easily converted to a str reference. | | `color` | [`Color`] | | | `length` | `f32` | The unit are physical pixels. | | `logical_length` | `f32` | At run-time, logical lengths are automatically translated to physical pixels using the device pixel ratio. | | `duration` | `i64` | At run-time, durations are always represented as signed 64-bit integers with milisecond precision. | | structure | `struct` of the same name | | */ #![cfg_attr(nightly, feature(doc_cfg, external_doc))] #![warn(missing_docs)] #![deny(unsafe_code)] pub use sixtyfps_macros::sixtyfps; pub use sixtyfps_corelib::model::{ Model, ModelHandle, ModelNotify, ModelPeer, StandardListViewItem, VecModel, }; pub use sixtyfps_corelib::sharedarray::SharedArray; pub use sixtyfps_corelib::string::SharedString; pub use sixtyfps_corelib::{ARGBColor, Color}; /// internal re_exports used by the macro generated #[doc(hidden)] pub mod re_exports { pub use const_field_offset::{self, FieldOffsets, PinnedDrop}; pub use core::iter::FromIterator; pub use once_cell::sync::Lazy; pub use once_cell::unsync::OnceCell; pub use pin_weak::rc::*; pub use sixtyfps_corelib::animations::EasingCurve; pub use sixtyfps_corelib::component::{ init_component_items, Component, ComponentRefPin, ComponentVTable, }; pub use sixtyfps_corelib::eventloop::ComponentWindow; pub use sixtyfps_corelib::graphics::{ PathArcTo, PathData, PathElement, PathEvent, PathLineTo, Point, Rect, Size, }; pub use sixtyfps_corelib::input::{ locate_and_activate_focus_item, process_ungrabbed_mouse_event, FocusEvent, FocusEventResult, InputEventResult, KeyCode, KeyEvent, KeyEventResult, KeyboardModifiers, MouseEvent, ALT_MODIFIER, CONTROL_MODIFIER, COPY_PASTE_MODIFIER, LOGO_MODIFIER, NO_MODIFIER, SHIFT_MODIFIER, }; pub use sixtyfps_corelib::item_tree::{ item_offset, visit_item_tree, ItemTreeNode, ItemVisitorRefMut, ItemVisitorVTable, TraversalOrder, VisitChildrenResult, }; pub use sixtyfps_corelib::items::*; pub use sixtyfps_corelib::layout::LayoutInfo; pub use sixtyfps_corelib::layout::{ grid_layout_info, solve_grid_layout, solve_path_layout, GridLayoutCellData, GridLayoutData, Padding, PathLayoutData, PathLayoutItemData, }; pub use sixtyfps_corelib::model::*; pub use sixtyfps_corelib::properties::{Property, PropertyTracker}; pub use sixtyfps_corelib::signals::Signal; pub use sixtyfps_corelib::slice::Slice; pub use sixtyfps_corelib::Color; pub use sixtyfps_corelib::ComponentVTable_static; pub use sixtyfps_corelib::Resource; pub use sixtyfps_corelib::SharedArray; pub use sixtyfps_corelib::SharedString; pub use sixtyfps_rendering_backend_default::native_widgets::*; pub use vtable::{self, *}; } /// Creates a new window to render components in. #[doc(hidden)] pub fn create_window() -> re_exports::ComponentWindow { sixtyfps_rendering_backend_default::create_window() } /// This module contains functions useful for unit tests pub mod testing { /// This trait gives access to the underyling Window of a component for the /// purposes of testing. pub trait HasWindow { /// Returns a reference to the component's window. fn component_window(&self) -> &super::re_exports::ComponentWindow; } pub use sixtyfps_corelib::tests::sixtyfps_mock_elapsed_time as mock_elapsed_time; /// Simulate a mouse click pub fn send_mouse_click< X: vtable::HasStaticVTable<sixtyfps_corelib::component::ComponentVTable> + HasWindow, >( component: core::pin::Pin<&X>, x: f32, y: f32, ) { sixtyfps_corelib::tests::sixtyfps_send_mouse_click( vtable::VRef::new_pin(component), x, y, component.component_window(), ); } /// Simulate a change in keyboard modifiers being pressed pub fn set_current_keyboard_modifiers<X: HasWindow>( component: core::pin::Pin<&X>, modifiers: crate::re_exports::KeyboardModifiers, ) { sixtyfps_corelib::tests::sixtyfps_set_keyboard_modifiers( component.component_window(), modifiers, ) } /// Simulate a series of key press and release event pub fn send_key_clicks< X: vtable::HasStaticVTable<sixtyfps_corelib::component::ComponentVTable> + HasWindow, >( component: core::pin::Pin<&X>, key_codes: &[crate::re_exports::KeyCode], ) { sixtyfps_corelib::tests::sixtyfps_send_key_clicks( vtable::VRef::new_pin(component), &crate::re_exports::Slice::from_slice(key_codes), component.component_window(), ) } /// Simulate entering a sequence of ascii characters key by key. pub fn send_keyboard_string_sequence< X: vtable::HasStaticVTable<sixtyfps_corelib::component::ComponentVTable> + HasWindow, >( component: core::pin::Pin<&X>, sequence: &str, ) { sixtyfps_corelib::tests::send_keyboard_string_sequence( vtable::VRef::new_pin(component), &super::SharedString::from(sequence), component.component_window(), ) } } /// Include the code generated with the sixtyfps-build crate from the build script. After calling `sixtyfps_build::compile` /// in your `build.rs` build script, the use of this macro includes the generated Rust code and makes the exported types /// available for you to instantiate. #[macro_export] macro_rules! include_modules { () => { include!(env!("SIXTYFPS_INCLUDE_GENERATED")); }; } /// Helper type that helps checking that the generated code is generated for the right version #[doc(hidden)] #[allow(non_camel_case_types)] pub struct VersionCheck_0_0_1; #[cfg(doctest)] mod compile_fail_tests; #[cfg(all(doc, nightly))] pub mod langref { #![doc(include = "docs/langref.md")] #![doc = ""] } #[cfg(all(doc, nightly))] pub mod builtin_elements { #![doc(include = "docs/builtin_elements.md")] #![doc = ""] } #[cfg(all(doc, nightly))] pub mod widgets { #![doc(include = "docs/widgets.md")] #![doc = ""] } /// This module exists only to explain the API of the code generated from `.60` design markup. Its described structure /// is not really contained in the compiled crate. #[cfg(doc)] pub mod generated_code { /// This an example of the API that is generated for a component in `.60` design markup. This may help you understand /// what functions you can call and how you can pass data in and out. /// This is the source code: /// ```60 /// SampleComponent := Window { /// property<int> counter; /// property<string> user_name; /// signal hello; /// /// ... maybe more elements here /// } /// ``` pub struct SampleComponent {} impl SampleComponent { /// Creates a new instance that is reference counted and pinned in memory. pub fn new() -> core::pin::Pin<std::rc::Rc<Self>> { unimplemented!() } /// Creates a window on the screen, renders this component in it and spins an event loop to react /// to user input. A typical sequence of creating an instance and showing it may look like this: /// ```ignore /// fn main() { /// let sample = SampleComponent::new(); /// /// other setup code here, connect to signal handlers, set property values /// sample.run(); /// } /// ``` pub fn run(self: core::pin::Pin<std::rc::Rc<Self>>) {} /// Returns a weak pointer for an instance of this component. You can use this to in captures of /// closures, for example signal handlers, to access the component later. pub fn as_weak( self: core::pin::Pin<std::rc::Rc<Self>>, ) -> super::re_exports::PinWeak<Self> { unimplemented!() } /// A getter is generated for each property declared at the root of the component. /// In this case, this is the getter that returns the value of the `counter` /// property declared in the `.60` design markup. pub fn get_counter(self: ::core::pin::Pin<&Self>) -> i32 { unimplemented!() } /// A setter is generated for each property declared at the root of the component, /// In this case, this is the setter that sets the value of the `counter` property /// declared in the `.60` design markup. pub fn set_counter(&self, value: i32) {} /// Returns the value of the `user_name` property declared in the `.60` design markup. pub fn get_user_name(self: ::core::pin::Pin<&Self>) -> super::re_exports::SharedString { unimplemented!() } /// Assigns a new value to the `user_name` property. pub fn set_user_name(&self, value: super::re_exports::SharedString) {} /// For each signal declared at the root of the component, a function to emit that /// signal is generated. This is the function that emits the `hello` signal declared /// in the `.60` design markup. pub fn emit_hello(self: ::core::pin::Pin<&Self>) {} /// For each signal declared at the root of the component, a function connect to that signal /// is generated. This is the function that registers the function f as callback when the /// signal `hello` is emitted. In order to access /// the component in the callback, you'd typically capture a weak reference obtained using /// [`SampleComponent::as_weak`] /// and then upgrade it to a strong reference when the callback is run: /// ```ignore /// let sample = SampleComponent::new(); /// let sample_weak = sample.clone().as_weak(); /// sample.as_ref().on_hello(move || { /// let sample = sample_weak.upgrade().unwrap(); /// sample.as_ref().set_counter(42); /// }); /// ``` pub fn on_hello(self: ::core::pin::Pin<&Self>, f: impl Fn() + 'static) {} } }