orbtk/book
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

ch02-09-crate-widgets: behavior modules update

Browse Source 
* alignment update
* explain submodules handling behavior classes

Signed-off-by: Ralf Zerres <ralf.zerres@networkx.de>
This commit is contained in:
Ralf Zerres
2020-10-23 19:39:54 +02:00
parent 504225631a
commit f4e580638d
1 changed files with 68 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
src/ch02-09-crate-widgets.md
View File

@@ -1,24 +1,35 @@
# The Widgets Crate # The Widgets Crates
As an UI developer consuming OrbTK, you most probably will get in touch with As an UI developer consuming OrbTK, you most probably will get in
the `widget` crate. If you get comfortable with the terminology of `views` and touch with the `widget` crate. If you get comfortable with the
their `states`, it's quite easy to implement even complex structures. The GUI terminology of `views` and their `states`, it's quite easy to
components are declarative and you will code them inside the `view` blocks. All implement even complex structures. The GUI components are declarative
callbacks that will handle the functional processing are coded inside the and you will code them inside the `view` blocks. All callbacks that
`state` blocks. User input (e.g. mouse events, keyboard input) as well as event will handle the functional processing are coded inside the `state`
handler generated feedback is handled and processed from methods of the blocks. User input (e.g. mouse events, keyboard input) as well as
associated `state` blocks. event handler generated feedback is handled and processed from methods
of the associated `state` blocks.
The `behavior modules` are separated to handle specialized cases. If
an event is emitted that belongs to a behavior class, the associated
action is handled by a behavior method. In particular you will
recognize modules for the following behaviors:
* focus
* mouse
* selection
* text
## Views ## Views
When you create a `view` block inside an OrbTK application, it is required to insert When you create a `view` block inside an OrbTK application, it is
definitions that declare what elements are going to be present inside the user required to insert definitions that declare what elements are going to
interface. be present inside the user interface.
### What is a View ### What is a View
If you take the Rust code that makes a `view` in a structural way, it will If you take the Rust code that makes a `view` in a structural way, it
answers to the following questions: will answers to the following questions:
* Which entities are used? * Which entities are used?
* What is the entities tree formed? * What is the entities tree formed?
@@ -27,40 +38,43 @@ answers to the following questions:
### What is the code structure of a View ### What is the code structure of a View
First, the inside the source code that takes your `view` needs to call the First, the inside the source code that takes your `view` needs to call
`widget!` macro. This macro automatically implements the `Widget` trait. When the `widget!` macro. This macro automatically implements the `Widget`
instantiated, it will inherits all default properties from a base widget, trait. When instantiated, it will inherits all default properties from
which gets you started with consistent preset values. a base widget, which gets you started with consistent preset values.
The syntax of this macro call will require you, to select The syntax of this macro call will require you, to select
* the desired `view-name` (e.g: "NavigationView") * the desired `view-name` (e.g: "NavigationView")
* optional: the name of the associated `state-structure` (e.g: "<NavigationState>") * 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 If you like to assign property names inside the view, go ahead and
an extensible list of the property-variables. Each variable will take a name introduce an extensible list of the property-variables. Each variable
and define its associated type. will take a name and define its associated type.
In a next step you enhance the `Template` trait with an implementation 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`. of your new widget. You are required to code a function called
The syntax of this function will take the following arguments `template`. The syntax of this function will take the following
arguments
* `self`, the implementation of your view-name * `self`, the implementation of your view-name
* the `Id` of the entity * the `Id` of the entity
* the `Context`, as a mutual reference to the BuildContext * the `Context`, as a mutual reference to the BuildContext
All the widget structures you are going to use inside of `template` will be All the widget structures you are going to use inside of `template`
coded as child's of `self`. will be coded as child's of `self`.
## States ## States
When you create a `state` block inside an OrbTK application, it is required to When you create a `state` block inside an OrbTK application, it is
define the structures you want to work on in the `State` implementation. required to define the structures you want to work on in the `State`
implementation.
### What is a State ### What is a State
The Rust code that makes a `state` is associated to the `view` block of your The Rust code that makes a `state` is associated to the `view` block
widget. Go and ask yourself: of your widget. Go and ask yourself:
* What actions should be processed on a given event? * What actions should be processed on a given event?
* How should we handled user input? * How should we handled user input?
@@ -69,23 +83,24 @@ widget. Go and ask yourself:
### What is the structure of a State ### What is the structure of a State
First, inside the source code that takes your `state`, you will go and 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 declare its structure name. This name corresponds to the parameter
choose inside the `widget!` macro call of your widgets view (e.g value you did choose inside the `widget!` macro call of your widgets
"NavigationState"). view (e.g "NavigationState").
In a next step you enhance the `State` trait with an implementation of your state In a next step you enhance the `State` trait with an implementation of
structure. Most probable, you create and adapt the following functions: your state structure. Most probable, you create and adapt the
following functions:
#### The `init` function #### The `init` function
This function is called to initialize the widget state. You can preset attributes This function is called to initialize the widget state. You can preset
**before** the view is activated and presented to the user. attributes **before** the view is activated and presented to the user.
#### The `message` function #### The `message` function
The `message subsystem` is offering methods to chain events, that can be The `message subsystem` is offering methods to chain events, that can
interchanged and accessed from any defined `state`. You will code a `message` be interchanged and accessed from any defined `state`. You will code a
function to take advantage of this functionality. `message` function to take advantage of this functionality.
The syntax of this function will take the following arguments The syntax of this function will take the following arguments
@@ -93,21 +108,22 @@ The syntax of this function will take the following arguments
* the mutable `messages` variable, referencing the MessageReader * the mutable `messages` variable, referencing the MessageReader
* the `Context`, as a mutual reference to the BuildContext * the `Context`, as a mutual reference to the BuildContext
As already explained, you should define an action enumeration, As already explained, you should define an action enumeration, (e.g
(e.g "NavigationAction"), that will code the values that are possible or "NavigationAction"), that will code the values that are possible or
desired (e.g "SaveSettings", "LoadSettings"). Inside the `message` function desired (e.g "SaveSettings", "LoadSettings"). Inside the `message`
you will loop through the `messages` and match the action values you are function you will loop through the `messages` and match the action
interested in. values you are interested in.
#### The `update` function #### The `update` function
Whenever the attribute of an entity is changed, OrbTK will render it dirty. The Whenever the attribute of an entity is changed, OrbTK will render it
`update` function is taking care to react on any triggered dirty state. You will dirty. The `update` function is taking care to react on any triggered
probably define an `Action` enumeration that will name and list all action states dirty state. You will probably define an `Action` enumeration that
you are interested in. Now, if you match an `action` in the `update` function, will name and list all action states you are interested in. Now, if
you can react on this with all the Rust syntax flexibility. you match an `action` in the `update` function, you can react on this
with all the Rust syntax flexibility.
#### The `update_post_layout` function #### The `update_post_layout` function
OrbTK will run this function **after** the rendering crate has processed the new OrbTK will run this function **after** the rendering crate has
layout for your view. processed the new layout for your view.