From 947cc808c25dba957e5d16f6fbd31f830a87e192 Mon Sep 17 00:00:00 2001 From: Ralf Zerres Date: Thu, 8 Oct 2020 19:10:48 +0200 Subject: [PATCH] initial chapter 2: crates * move old chapter 2 (examples) to be named chapter 9 * create sub-chapters for all existing crates (v0.3.1-alpha4) Signed-off-by: Ralf Zerres --- src/SUMMARY.md | 18 ++- src/ch02-00-crates.md | 24 ++++ src/ch02-01-crate-api.md | 3 + src/ch02-02-crate-localization.md | 3 + src/ch02-03-crate-proc-macros.md | 3 + src/ch02-04-crate-render.md | 3 + src/ch02-05-crate-shell.md | 3 + src/ch02-06-crate-theme.md | 3 + src/ch02-07-crate-theming.md | 3 + src/ch02-08-crate-tree.md | 3 + src/ch02-09-crate-utils.md | 0 src/ch02-09-crate-widgets.md | 113 ++++++++++++++++++ ...-examples.md => ch09-00-orbtk-examples.md} | 0 ...{ch02-01-widgets.md => ch09-01-widgets.md} | 0 ...h02-02-showcase.md => ch09-02-showcase.md} | 0 15 files changed, 176 insertions(+), 3 deletions(-) create mode 100644 src/ch02-00-crates.md create mode 100644 src/ch02-01-crate-api.md create mode 100644 src/ch02-02-crate-localization.md create mode 100644 src/ch02-03-crate-proc-macros.md create mode 100644 src/ch02-04-crate-render.md create mode 100644 src/ch02-05-crate-shell.md create mode 100644 src/ch02-06-crate-theme.md create mode 100644 src/ch02-07-crate-theming.md create mode 100644 src/ch02-08-crate-tree.md create mode 100644 src/ch02-09-crate-utils.md create mode 100644 src/ch02-09-crate-widgets.md rename src/{ch02-00-orbtk-examples.md => ch09-00-orbtk-examples.md} (100%) rename src/{ch02-01-widgets.md => ch09-01-widgets.md} (100%) rename src/{ch02-02-showcase.md => ch09-02-showcase.md} (100%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index e56c839..fa6f585 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -10,9 +10,21 @@ - [Installation](ch01-01-installation.md) - [Hello OrbTK!](ch01-02-hello-orbtk.md) -- [OrbTK examples](ch02-00-orbtk-examples.md) - - [Widgets](ch02-01-widgets.md) - - [Showcase](ch02-02-showcase.md) +- [OrbTK The Structure](ch02-00-crates.md) + - [Crate: API](ch02-01-crate-api.md) + - [Crate: Localization](ch02-02-crate-localization.md) + - [Crate: Procedural Macros](ch02-03-crate-proc-macros.md) + - [Crate: Render](ch02-04-crate-render.md) + - [Crate: Shell](ch02-05-crate-shell.md) + - [Crate: Theme](ch02-06-crate-theme.md) + - [Crate: Theming](ch02-07-crate-theming.md) + - [Crate: Tree](ch02-08-crate-tree.md) + - [Crate: Utils](ch02-09-crate-utils.md) + - [Crate: Widgets](ch02-09-crate-widgets.md) + +- [OrbTK Examples](ch09-00-orbtk-examples.md) + - [Widgets](ch09-01-widgets.md) + - [Showcase](ch09-02-showcase.md) - [Appendix](appendix-00.md) - [A - Keywords](appendix-01-keywords.md) diff --git a/src/ch02-00-crates.md b/src/ch02-00-crates.md new file mode 100644 index 0000000..d25bd4e --- /dev/null +++ b/src/ch02-00-crates.md @@ -0,0 +1,24 @@ +# OrbTK Crate Structure + +While developing OrbTK, we try to take care of some basic principles + +* modularity +* extensibility +* multiplatfom awareness + +Within the Rust ecosystem, `crates` are a natural way to distinct those code +blocks, that define a logical entity. + +By the time writing this overview, OrbTK will provide the following crate: + +* api +* localization +* render +* shell +* theme +* theming +* tree +* utils +* widget + +We will discuss their meanings step by step in the following chapters diff --git a/src/ch02-01-crate-api.md b/src/ch02-01-crate-api.md new file mode 100644 index 0000000..06e2774 --- /dev/null +++ b/src/ch02-01-crate-api.md @@ -0,0 +1,3 @@ +# The API Crate + +WIP: all about the OrbTK API diff --git a/src/ch02-02-crate-localization.md b/src/ch02-02-crate-localization.md new file mode 100644 index 0000000..37511ed --- /dev/null +++ b/src/ch02-02-crate-localization.md @@ -0,0 +1,3 @@ +# The Localization Crate + +WIP: all about the OrbTK localization diff --git a/src/ch02-03-crate-proc-macros.md b/src/ch02-03-crate-proc-macros.md new file mode 100644 index 0000000..ce9a427 --- /dev/null +++ b/src/ch02-03-crate-proc-macros.md @@ -0,0 +1,3 @@ +# The Procedural Macros Crate + +WIP: all about the OrbTK procedural macros diff --git a/src/ch02-04-crate-render.md b/src/ch02-04-crate-render.md new file mode 100644 index 0000000..20a6a78 --- /dev/null +++ b/src/ch02-04-crate-render.md @@ -0,0 +1,3 @@ +# The Render Crate + +WIP: all about the OrbTK rendering services diff --git a/src/ch02-05-crate-shell.md b/src/ch02-05-crate-shell.md new file mode 100644 index 0000000..e349cb7 --- /dev/null +++ b/src/ch02-05-crate-shell.md @@ -0,0 +1,3 @@ +# The Shell Crate + +WIP: all about the OrbTK shell services diff --git a/src/ch02-06-crate-theme.md b/src/ch02-06-crate-theme.md new file mode 100644 index 0000000..e840614 --- /dev/null +++ b/src/ch02-06-crate-theme.md @@ -0,0 +1,3 @@ +# The Theme Crate + +WIP: all about the OrbTK theme services diff --git a/src/ch02-07-crate-theming.md b/src/ch02-07-crate-theming.md new file mode 100644 index 0000000..09ed6d7 --- /dev/null +++ b/src/ch02-07-crate-theming.md @@ -0,0 +1,3 @@ +# The Theming Crate + +WIP: all about the OrbTK theming services diff --git a/src/ch02-08-crate-tree.md b/src/ch02-08-crate-tree.md new file mode 100644 index 0000000..e562ea6 --- /dev/null +++ b/src/ch02-08-crate-tree.md @@ -0,0 +1,3 @@ +# The Tree Crate + +WIP: all about the OrbTK tree services diff --git a/src/ch02-09-crate-utils.md b/src/ch02-09-crate-utils.md new file mode 100644 index 0000000..e69de29 diff --git a/src/ch02-09-crate-widgets.md b/src/ch02-09-crate-widgets.md new file mode 100644 index 0000000..8ccdd77 --- /dev/null +++ b/src/ch02-09-crate-widgets.md @@ -0,0 +1,113 @@ +# The Widgets Crate + +As an UI developer consuming OrbTK, you most probably will get in touch with +the `widget` crate. If you get comfortable with the terminology of `views` and +their `states`, it's quite easy to implement even complex structures. The GUI +components are declarative and you will code them inside the `view` blocks. All +callbacks that will handle the functional processing are coded inside the +`state` blocks. User input (e.g. mouse events, keyboard input) as well as event +handler generated feedback is handled and processed from methods of the +associated `state` blocks. + +## Views + +When you create a `view` block inside an OrbTK application, it is required to insert +definitions that declare what elements are going to be present inside the user +interface. + +### What is a View + +If you take the Rust code that makes a `view` in a structural way, it will +answers to the following questions: + +* Which entities are used? +* What is the entities tree formed? +* What attributes are coupled with the given entity? +* What handlers should take care when a given event is emitted? + +### What is the code structure of a View + +First, the inside the source code that takes your `view` needs to call the +`widget!` macro. This macro automatically implements the `Widget` trait. When +instantiated, it will inherits all default properties from a base widget, +which gets you started with consistent preset values. + +The syntax of this macro call will require you, to select + +* the desired `view-name` (e.g: "NavigationView") +* optional: the name of the associated `state-structure` (e.g: "") + +If you like to assign property names inside the view, go ahead and introduce +an extensible list of the property-variables. Each variable will take a name +and define its associated type. + +In a next step you enhance the `Template` trait with an implementation +of your new widget. You are required to code a function called `template`. +The syntax of this function will take the following arguments + +* `self`, the implementation of your view-name +* the `Id` of the entity +* the `Context`, as a mutual reference to the BuildContext + +All the widget structures you are going to use inside of `template` will be +coded as child's of `self`. + +## States + +When you create a `state` block inside an OrbTK application, it is required to +define the structures you want to work on in the `State` implementation. + +### What is a State + +The Rust code that makes a `state` is associated to the `view` block of your +widget. Go and ask yourself: + +* What actions should be processed on a given event? +* How should we handled user input? +* What happens, if an entity attribute is changed and gets dirty? + +### What is the structure of a State + +First, inside the source code that takes your `state`, you will go and +declare its structure name. This name corresponds to the parameter value you did +choose inside the `widget!` macro call of your widgets view (e.g +"NavigationState"). + +In a next step you enhance the `State` trait with an implementation of your state +structure. Most probable, you create and adapt the following functions: + +#### The `init` function + +This function is called to initialize the widget state. You can preset attributes +**before** the view is activated and presented to the user. + +#### The `message` function + +The `message subsystem` is offering methods to chain events, that can be +interchanged and accessed from any defined `state`. You will code a `message` +function to take advantage of this functionality. + +The syntax of this function will take the following arguments + +* `self`, the implementation of your message function +* the mutable `messages` variable, referencing the MessageReader +* the `Context`, as a mutual reference to the BuildContext + +As already explained, you should define an action enumeration, +(e.g "NavigationAction"), that will code the values that are possible or +desired (e.g "SaveSettings", "LoadSettings"). Inside the `message` function +you will loop through the `messages` and match the action values you are +interested in. + +#### The `update` function + +Whenever the attribute of an entity is changed, OrbTK will render it dirty. The +`update` function is taking care to react on any triggered dirty state. You will +probably define an `Action` enumeration that will name and list all action states +you are interested in. Now, if you match an `action` in the `update` function, +you can react on this with all the Rust syntax flexibility. + +#### The `update_post_layout` function + +OrbTK will run this function **after** the rendering crate has processed the new +layout for your view. diff --git a/src/ch02-00-orbtk-examples.md b/src/ch09-00-orbtk-examples.md similarity index 100% rename from src/ch02-00-orbtk-examples.md rename to src/ch09-00-orbtk-examples.md diff --git a/src/ch02-01-widgets.md b/src/ch09-01-widgets.md similarity index 100% rename from src/ch02-01-widgets.md rename to src/ch09-01-widgets.md diff --git a/src/ch02-02-showcase.md b/src/ch09-02-showcase.md similarity index 100% rename from src/ch02-02-showcase.md rename to src/ch09-02-showcase.md