slint/docs.rs
1// Copyright © SixtyFPS GmbH <[email protected]>
2// SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-Royalty-free-2.0 OR LicenseRef-Slint-Software-3.0
3
4#![cfg(doc)]
5/*!
6 This is a pseudo module which only exist for documentation purposes as a way to show
7 the Slint documentation as part of rustdoc.
8
9 - The [`generated_code`] module contains an [commented example](generated_code::SampleComponent)
10 of what is generated from the `.slint` file
11*/
12
13// cSpell: ignore rustdoc
14
15/// This module exists only to explain the API of the code generated from `.slint` design markup. Its described structure
16/// is not really contained in the compiled crate.
17pub mod generated_code {
18
19 use crate::ComponentHandle;
20 use crate::Global;
21 use crate::StrongHandle;
22 use crate::Weak;
23 use crate::Window;
24
25 /// This an example of the API that is generated for a component in `.slint` design markup. This may help you understand
26 /// what functions you can call and how you can pass data in and out.
27 ///
28 /// This is the source code:
29 ///
30 /// ```slint,no-preview
31 /// export component SampleComponent inherits Window {
32 /// in-out property<int> counter;
33 /// // note that dashes will be replaced by underscores in the generated code
34 /// in-out property<string> user-name;
35 /// callback hello;
36 /// public function do-something(x: int) -> bool { return x > 0; }
37 /// // ... maybe more elements here
38 /// }
39 /// ```
40 #[derive(Clone)]
41 pub struct SampleComponent {
42 _marker: core::marker::PhantomData<*mut ()>,
43 }
44 impl SampleComponent {
45 /// Creates a new instance that is reference counted and pinned in memory.
46 pub fn new() -> Result<Self, crate::PlatformError> {
47 unimplemented!()
48 }
49
50 /// A getter is generated for each property declared at the root of the component.
51 /// In this case, this is the getter that returns the value of the `counter`
52 /// property declared in the `.slint` design markup.
53 pub fn get_counter(&self) -> i32 {
54 unimplemented!()
55 }
56 /// A setter is generated for each property declared at the root of the component.
57 /// In this case, this is the setter that sets the value of the `counter` property
58 /// declared in the `.slint` design markup.
59 pub fn set_counter(&self, value: i32) {}
60 /// Returns the value of the `user_name` property declared in the `.slint` design markup.
61 pub fn get_user_name(&self) -> crate::SharedString {
62 unimplemented!()
63 }
64 /// Assigns a new value to the `user_name` property.
65 pub fn set_user_name(&self, value: crate::SharedString) {}
66
67 /// For each callback declared at the root of the component, a function to synchronously call that
68 /// callback is generated. This is the function that calls the `hello` callback declared
69 /// in the `.slint` design markup.
70 pub fn invoke_hello(&self) {}
71 /// For each callback declared at the root of the component, a function connect to that callback
72 /// is generated. This is the function that registers the function f as callback when the
73 /// callback `hello` is emitted. In order to access
74 /// the component in the callback, you'd typically capture a weak reference obtained using
75 /// [`ComponentHandle::as_weak`]
76 /// and then upgrade it to a strong reference when the callback is run:
77 /// ```ignore
78 /// let sample = SampleComponent::new().unwrap();
79 /// let sample_weak = sample.as_weak();
80 /// sample.on_hello(move || {
81 /// let sample = sample_weak.unwrap();
82 /// sample.set_counter(42);
83 /// });
84 /// ```
85 pub fn on_hello(&self, f: impl Fn() + 'static) {}
86
87 /// For each public function declared at the root of the component, a function to synchronously call
88 /// that function is generated. This is the function that calls the `do-something` function
89 /// declared in the `.slint` design markup.
90 pub fn invoke_do_something(&self, d: i32) -> bool {
91 unimplemented!()
92 }
93 }
94
95 /// The `StrongHandle` trait is implemented for each component.
96 /// It marks this component as holding a strong reference to the Slint element tree
97 /// and allows using this component with a Weak reference.
98 impl StrongHandle for SampleComponent {
99 #[doc(hidden)]
100 type WeakInner = ();
101
102 #[doc(hidden)]
103 fn upgrade_from_weak_inner(_: &Self::WeakInner) -> Option<Self> {
104 unimplemented!();
105 }
106 }
107
108 impl ComponentHandle for SampleComponent {
109 /// Returns a new weak pointer.
110 fn as_weak(&self) -> Weak<Self> {
111 unimplemented!()
112 }
113
114 /// Returns a clone of this handle that's a strong reference.
115 fn clone_strong(&self) -> Self {
116 unimplemented!();
117 }
118
119 /// Convenience function for [`crate::Window::show()`]. This shows the window on the screen
120 /// and maintains an extra strong reference while the window is visible. To react
121 /// to events from the windowing system, such as draw requests or mouse/touch input, it is
122 /// still necessary to spin the event loop, using [`crate::run_event_loop`].
123 fn show(&self) -> Result<(), crate::PlatformError> {
124 unimplemented!();
125 }
126
127 /// Convenience function for [`crate::Window::hide()`]. Hides the window, so that it is not
128 /// visible anymore. The additional strong reference on the associated component, that was
129 /// created when show() was called, is dropped.
130 fn hide(&self) -> Result<(), crate::PlatformError> {
131 unimplemented!();
132 }
133
134 /// Returns the Window associated with this component. The window API can be used
135 /// to control different aspects of the integration into the windowing system,
136 /// such as the position on the screen.
137 fn window(&self) -> &Window {
138 unimplemented!()
139 }
140
141 /// This is a convenience function that first calls [`Self::show`], followed by [`crate::run_event_loop()`]
142 /// and [`Self::hide`].
143 fn run(&self) -> Result<(), crate::PlatformError> {
144 unimplemented!();
145 }
146
147 /// This function provides access to instances of global singletons exported in `.slint`.
148 fn global<'a, T: Global<'a, Self>>(&'a self) -> T {
149 unimplemented!()
150 }
151 }
152
153 /// This an example of the API that is generated for a global in `.slint` design markup. This may help you understand
154 /// what functions you can call and how you can pass data in and out.
155 ///
156 /// This is the source code:
157 ///
158 /// ```slint,no-preview
159 /// export global SampleGlobal {
160 /// in-out property<int> value;
161 /// // ... maybe more callbacks or public functions here
162 /// }
163 /// ```
164 ///
165 /// **Note**: Globals are only accessible in Rust if they are exported from the root file or
166 /// the [`slint!`](crate::slint) macro!
167 pub struct SampleGlobal<'a> {
168 _marker: core::marker::PhantomData<&'a mut ()>,
169 }
170
171 impl<'a> SampleGlobal<'a> {
172 /// A getter is generated for each property declared in the global.
173 /// In this case, this is the getter that sets the value of the `value` property
174 /// declared in the `.slint` design markup.
175 pub fn get_value(&self) -> i32 {
176 unimplemented!()
177 }
178
179 /// A setter is generated for each property declared in the global.
180 /// In this case, this is the setter that sets the value of the `counter` property
181 /// declared in the `.slint` design markup.
182 pub fn set_value(&self, value: i32) {
183 unimplemented!()
184 }
185 }
186
187 /// The `StrongHandle` trait is implemented for each global.
188 /// It marks this component as holding a strong reference to the Slint element tree
189 /// and allows using this component with a Weak reference.
190 impl StrongHandle for SampleGlobal<'static> {
191 #[doc(hidden)]
192 type WeakInner = ();
193
194 #[doc(hidden)]
195 fn upgrade_from_weak_inner(_: &Self::WeakInner) -> Option<Self> {
196 unimplemented!();
197 }
198 }
199
200 /// The `Global` trait is implemented for each global.
201 /// This allows accessing the global from its corresponding component (in this case [`SampleComponent`])
202 /// using the [`Global::get`] or [`ComponentHandle::global`] functions.
203 impl<'a> Global<'a, SampleComponent> for SampleGlobal<'a> {
204 type StaticSelf = SampleGlobal<'static>;
205
206 fn get(component: &'a SampleComponent) -> Self {
207 unimplemented!()
208 }
209
210 fn as_weak(&self) -> Weak<Self::StaticSelf> {
211 unimplemented!()
212 }
213 }
214}
215
216pub mod mcu {
217 #![doc = include_str!("mcu.md")]
218 #[cfg(feature = "renderer-software")]
219 use crate::platform::software_renderer::*;
220 use crate::platform::*;
221 mod slint {
222 pub use crate::*;
223 }
224}
225
226#[i_slint_core_macros::slint_doc]
227pub mod cargo_features {
228 //! # Feature flags and backend selection.
229 //! Use the following feature flags in your Cargo.toml to enable additional features.
230 //!
231 #![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
232 //!
233 //! More information about the backend and renderers is available in the
234 //")]
235 use crate::*;
236}
237
238pub mod type_mappings {
239 #![doc = include_str!("type-mappings.md")]
240 use crate::*;
241}