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 <ralf.zerres@networkx.de>

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)

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

src/ch02-01-crate-api.md

@@ -0,0 +1,3 @@
+# The API Crate
+
+WIP: all about the OrbTK API

src/ch02-02-crate-localization.md

@@ -0,0 +1,3 @@
+# The Localization Crate
+
+WIP: all about the OrbTK localization

src/ch02-03-crate-proc-macros.md

@@ -0,0 +1,3 @@
+# The Procedural Macros Crate
+
+WIP: all about the OrbTK procedural macros

src/ch02-04-crate-render.md

@@ -0,0 +1,3 @@
+# The Render Crate
+
+WIP: all about the OrbTK rendering services

src/ch02-05-crate-shell.md

@@ -0,0 +1,3 @@
+# The Shell Crate
+
+WIP: all about the OrbTK shell services

src/ch02-06-crate-theme.md

@@ -0,0 +1,3 @@
+# The Theme Crate
+
+WIP: all about the OrbTK theme services

src/ch02-07-crate-theming.md

@@ -0,0 +1,3 @@
+# The Theming Crate
+
+WIP: all about the OrbTK theming services

src/ch02-08-crate-tree.md

@@ -0,0 +1,3 @@
+# The Tree Crate
+
+WIP: all about the OrbTK tree services

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: "<NavigationState>")
+
+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.