language-servers/slint
1
0
Fork 0
mirror of https://github.com/slint-ui/slint.git synced 2025-10-02 22:54:36 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Some changes in the rust documentation and its README

Browse source
This commit is contained in:
Olivier Goffart 2020-10-20 18:01:30 +02:00
parent 1436402999
commit 0c253efb0d
6 changed files with 219 additions and 108 deletions
Download patch file Download diff file Expand all files Collapse all files

39
api/sixtyfps-rs/README.md
View file

@ -12,12 +12,43 @@ The complete Rust documentation can be viewed online at https://www.sixtyfps.io/
## Getting Started
The [crate documentation](https://www.sixtyfps.io/docs/rust/sixtyfps/) shows to be used.
The [crate documentation](https://www.sixtyfps.io/docs/rust/sixtyfps/) shows how to use this crate.
You can quickly try out the [examples](/examples) by cloning this repo and running the following command:
### Hello World
The most basic "Hello world" application can easily be achieve in a few lines of code:
In your `Cargo.toml` add:
```toml
[dependencies]
sixtyfps = "0.0.1"
```
And in your `main.rs`:
```rust
sixtyfps::sixtyfps!{
HelloWorld := Window {
Text {
text: "hello world";
color: green;
}
}
}
fn main() {
HelloWorld::new().run()
}
```
The [`sixtyfps` crate documentation](https://www.sixtyfps.io/docs/rust/sixtyfps/)
contains more advanced examples and alternative ways to use this crate.
## More examples
You can quickly try out the [examples](/examples) by cloning this repo and running them with `cargo run`
```sh
# Runs the "printerdemo" example
cargo run --release --bin printerdemo
cargo run --release --bin printerdem
```

105
api/sixtyfps-rs/docs.rs Normal file
View file

@ -0,0 +1,105 @@
#![cfg(doc)]
/*!
This is a pseudo module which only exist for documentation purposes as a way to show
the SixtyFPS documentation as part of rustdoc.
- The [`generated_code`] module contains an [commented example](generated_code::SampleComponent)
of what is generated from the `.60` file
- The [`langref`] module is the reference documentation for the `.60` language.
- The [`widgets`] and [`builtin_elements`] modules contains the documentation of elements usable
within the `.60` files
*/
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.
pub mod generated_code {
use crate::re_exports;
/// 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>>) -> 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>) -> re_exports::SharedString {
unimplemented!()
}
/// Assigns a new value to the `user_name` property.
pub fn set_user_name(&self, value: 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) {}
}
}

105
api/sixtyfps-rs/lib.rs
View file

@ -13,7 +13,7 @@ LICENSE END */
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).
Included in this documentation is also the [language reference](docs::langref).
## How to use:
@ -25,7 +25,7 @@ of including the design in Rust:
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
includes an [example](docs::generated_code::SampleComponent) of how the API looks
like.
### The .60 code in a macro
@ -34,10 +34,12 @@ This method combines your Rust code with the `.60` design markup in one file, us
```rust
sixtyfps::sixtyfps!{
HelloWorld := Text {
HelloWorld := Window {
Text {
text: "hello world";
color: green;
}
}
}
fn main() {
# return; // Don't run a window in an example
@ -71,7 +73,7 @@ In the `build.rs` file:
```ignore
fn main() {
sixtyfps_build::compile("ui/hello.60");
sixtyfps_build::compile("ui/hello.60").unwrap();
}
```
@ -235,6 +237,8 @@ pub mod testing {
/// 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.
///
/// Check the documentation of the `sixtyfps-build` crate for more information.
#[macro_export]
macro_rules! include_modules {
() => {
@ -251,95 +255,4 @@ pub struct VersionCheck_0_0_1;
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) {}
}
}
pub mod docs;

56
api/sixtyfps-rs/sixtyfps-build/lib.rs
View file

@ -8,10 +8,44 @@
Please contact info@sixtyfps.io for more information.
LICENSE END */
/*!
This crate serves as a companion crate for the sixtyfps crate.
It is meant to allow you to compile the `.60` files from your `build.rs`script.
This crate serves as a companion crate for the sixtyfps crate.
It is meant to allow you to compile the `.60` files from your `build.rs`script.
The main entry point of this crate is the [`compile()`] function
The main entry point of this crate is the [`compile()`] function
## Example
In your Cargo.toml:
```toml
[package]
...
build = "build.rs"
[dependencies]
sixtyfps = "0.0.1"
...
[build-dependencies]
sixtyfps-build = "0.0.1"
```
In the `build.rs` file:
```ignore
fn main() {
sixtyfps_build::compile("ui/hello.60").unwrap();
}
```
Then in your main file
```ignore
sixtyfps::include_modules!();
fn main() {
HelloWorld::new().run()
}
```
*/
#![warn(missing_docs)]
@ -87,12 +121,24 @@ impl<Sink: Write> Write for CodeFormatter<Sink> {
/// Compile the `.60` file and generate rust code for it.
///
/// The path is relative to the `CARGO_MANIFEST_DIR`.
/// The generated code code will be created in the directory specified by
/// the `OUT` environment variable as it is expected for build script.
///
/// The following line need to be added within your crate to include the generated code.
/// The following line need to be added within your crate in order to include
/// the generated code.
/// ```ignore
/// sixtyfps::include_modules!();
/// ```
///
/// The path is relative to the `CARGO_MANIFEST_DIR`.
///
/// In case of compilation error, the errors are shown in `stderr`, the error
/// are also returned in the [`CompileError`] enum. You must `unwrap` the returned
/// result to make sure that cargo make the compilation fail in case there were
/// errors when generating the code.
///
/// Please check out the documentation of the `sixtyfps` crate for more information
/// about how to use the generated code.
pub fn compile(path: impl AsRef<std::path::Path>) -> Result<(), CompileError> {
compile_with_config(path, Default::default())
}

4
api/sixtyfps-rs/sixtyfps-docs-integration.html
View file

@ -1,3 +1,7 @@
<!--
This file is used to add preview of the `.60` snippets in the generated rustdoc documentation.
It can be injected via the `--html-in-header sixtyfps-docs-integration.html` option of rustdoc.
-->
<script type="module">
"use strict";
import * as sixtyfps from 'https://www.sixtyfps.io/wasm-interpreter/sixtyfps_wasm_interpreter.js';

12
api/sixtyfps-rs/sixtyfps-macros/lib.rs
View file

@ -7,6 +7,15 @@
This file is also available under commercial licensing terms.
Please contact info@sixtyfps.io for more information.
LICENSE END */
/*!
*NOTE*: This library is an internal crate for the [SixtyFPS project](https://sixtyfps.io).
This crate should not be used directly by application using SixtyFPS.
You should use the `sixtyfps` crate instead.
*/
extern crate proc_macro;
use proc_macro::{Spacing, TokenStream, TokenTree};
use quote::ToTokens;
@ -222,6 +231,9 @@ fn extract_include_paths(
/// This macro allows you to use the `.60` design markup language inline in Rust code. Within the braces of the macro
/// you can use place `.60` code and the named exported components will be available for instantiation.
///
/// [The documentation of the `sixtyfps`](./index.html) crate contains more information about the language specification and
/// how to use the generated code.
#[proc_macro]
pub fn sixtyfps(stream: TokenStream) -> TokenStream {
let token_iter = stream.into_iter();