atria-soft/ewol
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[DOC] update done for doxygen over doxy

Browse Source
This commit is contained in:
Edouard DUPIN 2016-09-16 22:35:06 +02:00
parent 980220eb8c
commit e6cab1e0cb
20 changed files with 864 additions and 744 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
doc/001_bases.md
View File

@ -1,44 +1,53 @@
EWOL: Bases {#page_bases} EWOL: Bases {#ewol_page_bases}
=========== ===========
Overview: @tableofcontents
Overview: {#ewol_page_bases_overview}
========= =========
EWOL is an OpenGL library for creating graphical user interfaces. EWOL is an OpenGL library for creating graphical user interfaces.
It works on many UNIX-like platforms, Windows, and OS X and some mobile platforms Android, iOs(soon). It works on many UNIX-like platforms, Windows, and OS X and some mobile platforms Android, iOs.
EWOL is released under the APACHE-2 license, which allows for very flexible licensing of client applications. EWOL is released under the APACHE-2 license, which allows for very flexible licensing of client applications.
EWOL has a C++ architecture that allows for maximum flexibility. EWOL has a C++ architecture that allows for maximum flexibility.
**APACHE-2 license limitation:** I limit myself to use only Apache2 / MIT / BSD / PNG licencing to permit to release binary on IOs.
This I a big point, because it need to rewrite many libraries (like SVG...).
The main idea of EWOL is to create a complete abstraction of the platforms. The main idea of EWOL is to create a complete abstraction of the platforms.
This generate some restriction that you will see an overwiew in the under section. This generate some restriction that you will see an overwiew in the under section.
User requires: User requires: {#ewol_page_bases_require}
============== ==============
To use ewol you need to know only C++ language. It could be usefull to know: To use ewol you need to know only C++ language. It could be usefull to know:
- **Python** for all build tool. - **Python** for [lutin](http://HeeroYui.github.io/lutin) build tool.
- **git** and **repo** for all version management. - **git** and **repo** for all version management.
- **OpenGL-ES2** if you want to create custum advenced widget. - **OpenGL-ES2** if you want to create custum advanced widget.
If you just want to have an interface of the openGl just refer to the [lib[gale|Gale library]]. If you just want to have an interface of the openGl just refer to the [gale library](http://atria-soft.github.io/gale)
Ewol does not manage the Audio but it is full integrated in [lib[audio-river|River library]]. Ewol does not manage the Audio but it is full integrated in [audio-river library](http://musicdsp.github.io/audio-river).
Architecture: Architecture: {#ewol_page_bases_architecture}
============= =============
One of the important point to know in this framwork is some of absurd things came from the multiple architecture type.
One of the important point to know in this framework is some of absurd things came from the multiple architecture type.
I will Explain the main points: I will Explain the main points:
- IOs does [b]NOT[/b] simply support the shared object sub lib, this force ewol to be APACHE-2, and depend on some sub-library with small license restriction. - IOs does **NOT** simply support the shared object sub lib, this force ewol to be APACHE-2, and depend on some sub-library with small license restriction.
- Android have a JAVA main, then the application main will not be used with this platform - Android have a JAVA main, then the application main will not be used with this platform
- Android event (keyboard, mouse, touch-screen and ...) will arrive in asynchron mode ==> need to be resynchronyse in one thread - Android event (keyboard, mouse, touch-screen and ...) will arrive in asynchron mode ==> need to be resynchronyse in one thread
- Only one graphyc framework is availlable on all platform. This is OpenGL (nned check for windows phone) - Only one graphyc framework is availlable on all platform. This is OpenGL (windows phone is not supported (moribund archi))
- Main interesting point is packaging of the application data: - Main interesting point is packaging of the application data:
* Linux store it in /usr/share/applName/* * Linux store it in /usr/share/applName/*
* MacOs store it in applName.app/subFolder/* * MacOs store it in applName.app/subFolder/*
* Android store it in the .pkg that is a renamed .zip that the name is dynamic * Android store it in the .pkg that is a renamed .zip that the name is dynamic
* Windows (TODO : Never done a pakage) * Windows (TODO : Never done a pakage)
This will generate a complex result of data access... This will generate a complex result of data access...
- Sub lib Change on all the platform, the I will use the idea of Apple, that incluse in a package all needed libs. This could be a problem for small platform, but this framwork need to have a OpenGL-ES2 instance then the memory problem, is not really a problem. - Sub lib Change on all the platform, then I will use the idea of Apple, that incluse in a package all needed libs.
This could be a problem for small platform, but this framwork need to have a OpenGL-ES2 instance then the memory problem,
is not really a problem.

210
doc/build.md
View File

@ -1,13 +1,14 @@
=?=Ewol extract and build examples=?= Build lib & build sample {#ewol_build}
__________________________________________________ ========================
[left][doc[001_bases | Previous: Doc]][/left] [right][tutorial[001_HelloWord | Next: Hello-Word]][/right]
All developpement software will start by getting the dependency and the sources. @tableofcontents
Linux dependency packages {#ewol_build_dependency}
=========================
=== Linux dependency packages === Ubuntu or Debian {#ewol_build_dependency_debian}
----------------
==== Ubuntu or Debian ==== ```{.sh}
[code style=shell]
sudo apt-get install g++ libgl1-mesa-dev zlib1g-dev libasound2-dev sudo apt-get install g++ libgl1-mesa-dev zlib1g-dev libasound2-dev
# Compile with Clang: # Compile with Clang:
sudo apt-get install clang sudo apt-get install clang
@ -20,10 +21,11 @@ All developpement software will start by getting the dependency and the sources.
# On 64 bits processor for compatibility: # On 64 bits processor for compatibility:
sudo apt-get install ia32-libs sudo apt-get install ia32-libs
sudo apt-get install g++-multilib libc6-dev-i386 sudo apt-get install g++-multilib libc6-dev-i386
[/code] ```
==== Arch-linux ==== Arch-linux {#ewol_build_dependency_archlinux}
[code style=shell] ----------
```{.sh}
# Cross compile for windows: # Cross compile for windows:
pacman -S mingw-w64-gcc pacman -S mingw-w64-gcc
@ -39,104 +41,148 @@ All developpement software will start by getting the dependency and the sources.
pacman -S jdk7-openjdk pacman -S jdk7-openjdk
# connect adb: (and you can do a "android/sdk/platform-tools/adb shell" to enable computer key on device) # connect adb: (and you can do a "android/sdk/platform-tools/adb shell" to enable computer key on device)
pacman -S android-udev pacman -S android-udev
[/code] ```
=== Download instructions === Download: {#ewol_build_download}
=========
==== download Build system: ==== ewol use some tools to manage source and build it:
[code style=shell] need google repo: {#ewol_build_download_repo}
sudo pip install lutin -----------------
sudo pip install pillow
[/code]
==== need google repo: ====
see: http://source.android.com/source/downloading.html#installing-repo see: http://source.android.com/source/downloading.html#installing-repo
[code style=shell] On all platform:
```{.sh}
mkdir ~/.bin mkdir ~/.bin
PATH=~/.bin:$PATH PATH=~/.bin:$PATH
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo
chmod a+x ~/.bin/repo chmod a+x ~/.bin/repo
[/code] ```
==== download the software: ====
[code style=shell] On ubuntu
mkdir WORKING_DIRECTORY ```{.sh}
cd WORKING_DIRECTORY sudo apt-get install repo
```
On archlinux
```{.sh}
sudo pacman -S repo
```
lutin (build-system): {#ewol_build_download_lutin}
---------------------
```{.sh}
pip install lutin --user
# optionnal dependency of lutin (manage image changing size for application release)
pip install pillow --user
```
The full build tool documentation is availlable here : [lutin](http://heeroyui.github.io/lutin/)
dependency: {#ewol_build_download_dependency}
-----------
```{.sh}
mkdir -p WORKING_DIRECTORY/framework
cd WORKING_DIRECTORY/framework
repo init -u git://github.com/atria-soft/manifest.git repo init -u git://github.com/atria-soft/manifest.git
repo sync -j8 repo sync -j8
[/code] cd ../..
```
==== Compile software and test: ==== sources: {#ewol_build_download_sources}
--------
[code style=shell] They are already download in the repo manifest in:
lutin ewol-*
[/code]
[note] ```{.sh}
The full build tool documentation is availlable here : [[http://heeroyui.github.io/lutin/ | lutin]] cd WORKING_DIRECTORY/framework/atria-soft/ewol
[/note] ```
=== Common build instructions === Build: {#ewol_build_build}
======
Compile software in debug for the curent platform : you must stay in zour working directory...
[code style=shell] ```{.sh}
lutin -mdebug cd WORKING_DIRECTORY
[/code] ```
You can specify the platform with: library: {#ewol_build_build_library}
[code style=shell] --------
lutin -tAndroid -mdebug
[/code]
It coud be usefull to disable the package generation in local debug: ```{.sh}
[code style=shell] lutin -mdebug ewol
lutin -mdebug -p ```
[/code]
Build with clang instead of gcc: Sample: {#ewol_build_build_sample}
[code style=shell] -------
lutin -cclang
[/code]
Display the build in color : ```{.sh}
[code style=shell] lutin -mdebug ewol-sample-*
lutin -C -mdebug -p ```
[/code]
Build in realease and install the program named 'ewol-sample-HelloWord'. Note the install will install it in user mode in the ~/.local/application/ in a stand-alone mode Run sample: {#ewol_build_run_sample}
[code style=shell] -----------
lutin -C ewol-sample-HelloWord?install
#or
lutin -C ewol-sample-HelloWord@install
[/code]
To run an application you will find it directly on the out 'staging' tree or execute the command: Basic way
[code style=shell]
lutin -C ewol-sample-HelloWord@run
#or (with better log level
lutin -C ewol-sample-HelloWord@run:--elog-level=5
# or specify the lib
lutin -C ewol-sample-HelloWord@run:--elog-lib=etk:6
[/code]
== Simple explanation : == ```{.sh}
lutin -mdebug ewol-sample-*?run
```
With some option: (set global log leval at 2 (print, error, warning), and "appl" library at log level 6
```{.sh}
lutin -mdebug ewol-sample-*?run:--elog-level=2:--elog-lib=appl:6
```
Build for Android and install: {#ewol_build_android}
==============================
Sample: {#ewol_build_android_sample}
-------
```{.sh}
lutin -tAndroid -mdebug ewol-sample-*
```
Sample: {#ewol_build_android_install_sample}
-------
```{.sh}
lutin -tAndroid -mdebug ewol-sample-*?install
```
Worktree explanation: {#ewol_build_workspace}
=====================
The workspace is a simple folder that contain all the modules ans sub module availlable for build. The workspace is a simple folder that contain all the modules ans sub module availlable for build.
It will create a tree like this : It will create a tree like this :
:** workspace - **workspace**
::** application * **application:** set your application here, it is a good position
:::** Application clone application area. * **framework:** framework download by repo
::** framework + **atria-soft:** graphic framework
:::** atria-soft + **generic-library:** open sources library that is wrapped on lutin builder
::::** Graphic interface + **musicdsp:** Common library for audio interfacing
:::** generic-library + **tools:** build tools (now only the IOs flasher)
::::** common untuch library (just wrap in lutin mode) * **out:**
:::** HeeroYui + Android_arm_32
::::** unstable stuff + Android_arm_64
:::** musicdsp + Windows_x86_32
::::** Common library for audio interfacing + Windows_x86_64
:::** tools + Linux_x86_32
+ Linux_x86_64
+ MacOs_x86_32
+ MacOs_x86_64
+ IOs_x86_32
+ IOs_x86_64
All the build object are set in the out path, then to restart with a clean build simply remove this folder

140
doc/codingStyle.md
View File

@ -1,51 +1,53 @@
Ewol coding style {#ewol_coding_style} Ewol coding style {#ewol_coding_style}
================= =================
@tableofcontents
Comments
-------- Comments {#ewol_coding_style_comment}
========
- One line comment: (never in #define xxx ==> too dangerous) - One line comment: (never in #define xxx ==> too dangerous)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
// //
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- Multiple line comment - Multiple line comment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
/* /*
* xxxx yyyy * xxxx yyyy
* zzzz * zzzz
*/ */
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- Documentation : doxygen (do not set un-nneded field) - Documentation : doxygen (do not set un-nneded field)
@verbatim @verbatim
/** /**
* @brief my summery * @brief my summery
* @param[in,out] _xxxx Comment on the variable * @param[in,out] _xxxx Comment on the variable
* @return my return explanation * @return my return explanation
*/ */
@endverbatim @endverbatim
- one line documlentation: - one line documlentation:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
xxxxx, //!< my comment xxxxx, //!< my comment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
number of colomn Number of colomn {#ewol_coding_style_number_of_colomn}
---------------- ================
I do not linit the number of colomn, but it could be good to limit at 150 char. Many screen have the main display like this I do not linit the number of colomn, but it could be good to limit at 150 char. Many screen have the main display like this
Indentation & braces Indentation & braces {#ewol_coding_style_indent}
-------------------- ====================
Tab size is a personal choice then, when you write code, you might be Tab size is a personal choice then, when you write code, you might be
tab proof. If someone want to have the golden number for theire tabs, tab proof. If someone want to have the golden number for theire tabs,
he will be able to do it. he will be able to do it.
@ -54,15 +56,16 @@ stop brace '}' you need to remove a tab
To be simple : (tab stop at the 'if' start) To be simple : (tab stop at the 'if' start)
- if: - if:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
if ( xxx == yyy if ( xxx == yyy
&& xxx == kkk) { && ( xxx == kkk
your action ...; || xxx == zzz )) {
//your action ...;
} }
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- switch: - switch:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
switch (suffix) { switch (suffix) {
case 'G': case 'G':
case 'g': case 'g':
@ -79,17 +82,17 @@ To be simple : (tab stop at the 'if' start)
default: default:
break; break;
} }
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- function: - function:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
void myFunction(void) { void myFunction(void) {
actions ...; actions ...;
} }
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- classes: - classes:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
class MyClass { class MyClass {
public: public:
MyClass(void); MyClass(void);
@ -97,36 +100,36 @@ To be simple : (tab stop at the 'if' start)
private: private:
const char* getName(void); const char* getName(void);
}; };
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- namespace: - namespace:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
namespace appl { namespace appl {
void get(void); void get(void);
} }
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- For special element like : you might add a tabulation too - For special element like : you might add a tabulation too
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
case xxx: case xxx:
actions... actions...
public: public:
definition ... definition ...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- An exception for the inline function inside c++ header: - An exception for the inline function inside c++ header:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
class Plop { class Plop {
private: private:
int32_t m_value; //!< my value of money gain int32_t m_value; //!< my value of money gain
public: public:
int32_t getValue(void) const { return m_value; }; int32_t getValue(void) const { return m_value; };
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
types Types {#ewol_coding_style_type}
----- =====
the element 'typedef' must not be use, like this it is not needed to add the element 'typedef' must not be use, like this it is not needed to add
special element like '_te' or '_ts' to say respectively 'tpedef enum' and special element like '_te' or '_ts' to say respectively 'tpedef enum' and
@ -135,21 +138,21 @@ Structure is not availlable in c++, just use normal class, this is the same.
Star position Star position {#ewol_coding_style_star}
------------- =============
The star will be near the type : The star will be near the type :
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
void* myVariableName; void* myVariableName;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
C and c++ C and c++ {#ewol_coding_style_c_and_cpp}
--------- =========
All C header files might have : All C header files might have :
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
@ -159,71 +162,72 @@ All C header files might have :
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
Naming Naming {#ewol_coding_style_naming}
------ ======
- Fonction/Methods: - Fonction/Methods:
Camel case with first letter in lower case. Camel case with first letter in lower case.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
void myExampleFontionName(void); void myExampleFontionName(void);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- Variable: - Variable:
Camel case with first letter in lower case. Camel case with first letter in lower case.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
nt32_t myVariableExample; nt32_t myVariableExample;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- namespace: - namespace:
one world in lower case one world in lower case
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
namspace ewol { namspace ewol {
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- Class: - Class:
Camel case with first letter in upper case. Camel case with first letter in upper case.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
class MyClass; class MyClass;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- Members fields: - Members fields:
Put a 'm' prefix and then a normal Variable name Put a 'm' prefix and then a normal Variable name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
int32_t m_memberField; int32_t m_memberField;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- enum: - enum:
Camel case with first letter in lower case. Camel case with first letter in lower case.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
enum myEnum { enum myEnum {
myEnum_def1, myEnum_def1,
myEnum_def2, myEnum_def2,
myEnum_def3, myEnum_def3,
}; };
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
- structure (C only) - structure (C only)
use naming like Classes (and for mamber too) use naming like Classes (and for mamber too)
- minimum size : Do not use variable with size <3, the for a iterator - minimum size : Do not use variable with size <3, the for a iterator
for a 'for' : for a 'for' :
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
for (int32_t iii=0; iii<xxx; ++iii) { for (int32_t iii=0; iii<xxx; ++iii) {
// actions ... // actions ...
} }
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
Types Types {#ewol_coding_style_types}
----- =====
Une stanndard Type : Une stanndard Type :
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} ```{.cpp}
bool bool
int8_t / uint8_t int8_t / uint8_t
int16_t / uint16_t int16_t / uint16_t
@ -233,13 +237,13 @@ Une stanndard Type :
int (some case needed) int (some case needed)
float / double float / double
float_t to automatic match whith the compilation choice between float or double float_t to automatic match whith the compilation choice between float or double
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ```
C++ specificity C++ specificity {#ewol_coding_style_specific}
--------------- ===============
- STL - STL
You can use the Stl, but the porting and the result can be You can use the Stl, but the porting and the result can be

101
doc/mainpage.md
View File

@ -32,15 +32,15 @@ EWOL is **FREE software** and _all sub-library are FREE and staticly linkable !!
That allow you to use it for every program you want, including those developing proprietary software, without any license fees or royalties. That allow you to use it for every program you want, including those developing proprietary software, without any license fees or royalties.
The static support is important for some platform like IOs, and this limit the external library use at some license like: The static support is important for some platform like IOs, and this limit the external library use at some license like:
- BSD* - BSD*
- MIT - MIT
- APPACHE-2 - APPACHE-2
- PNG - PNG
- ZLIB - ZLIB
This exclude the classical extern library with licence: This exclude the classical extern library with licence:
- L-GPL - L-GPL
- GPL - GPL
License (APACHE 2) {#ewol_mainpage_license} License (APACHE 2) {#ewol_mainpage_license}
================== ==================
@ -65,22 +65,25 @@ Sub library: {#ewol_mainpage_sub}
License: License:
- [**etk**](http://atria-soft.github.io/etk) : APACHE-2 - [**etk**](http://atria-soft.github.io/etk) : APACHE-2
- [**elog**](http://atria-soft.github.io/elog) : APACHE-2 - [**elog**](http://atria-soft.github.io/elog) : APACHE-2
+ **linearmath** : z-lib (subset of bullet lib) + **linearmath** : z-lib (subset of bullet lib)
+ [**earchive**](http://atria-soft.github.io/earchive) : APACHE-2 + [**earchive**](http://atria-soft.github.io/earchive) : APACHE-2
* **zlib** : z-lib * **zlib** : z-lib
- [**egami**](http://atria-soft.github.io/egami) : APACHE-2 - [**egami**](http://atria-soft.github.io/egami) : APACHE-2
+ [**esvg**](http://atria-soft.github.io/esvg) : APACHE-2 + [**esvg**](http://atria-soft.github.io/esvg) : APACHE-2
+ **libpng** : PNG + **libpng** : PNG
- **libogg** : BSD-like - **libogg** : BSD-like
- **libfreetype** : BSD-like - **libfreetype** : BSD-like
- [**e-json**](http://atria-soft.github.io/ejson) : APACHE-2 - [**e-json**](http://atria-soft.github.io/ejson) : APACHE-2
- [**e-xml**](http://atria-soft.github.io/exml) : APACHE-2 - [**e-xml**](http://atria-soft.github.io/exml) : APACHE-2
- [**audio**](http://musicdsp.github.io/audio) : APACHE-2 - [**audio**](http://musicdsp.github.io/audio) : APACHE-2
- [**audio-orchestra**](http://musicdsp.github.io/audio-orchestra) : APACHE-2 - [**audio-orchestra**](http://musicdsp.github.io/audio-orchestra) : MIT
- [**audio-river**](http://musicdsp.github.io/audio-river) : APACHE-2 - [**audio-drain**](http://musicdsp.github.io/audio-drain) : APACHE-2
- [**audio-river**](http://musicdsp.github.io/audio-river) : APACHE-2
- [**audio-ess**](http://musicdsp.github.io/audio-ess) : APACHE-2
- [**ege**](http://atria-soft.github.io/ege) : APACHE-2
- [**dollar**](http://atria-soft.github.io/dollar) : APACHE-2
... ...
Description: {#ewol_mainpage_desc} Description: {#ewol_mainpage_desc}
@ -88,41 +91,45 @@ Description: {#ewol_mainpage_desc}
Internal: Internal:
- [**elog**](http://atria-soft.github.io/elog) : Generic Log interface (for Android and MacOs) ... - [**elog**](http://atria-soft.github.io/elog) : Generic Log interface (for Android and MacOs) ...
- [**etk**](http://atria-soft.github.io/etk) : Generic toolkit to acces on file, standardize acces on string (for Android and MacOs) ... - [**etk**](http://atria-soft.github.io/etk) : Generic toolkit to acces on file, standardize acces on string (for Android and MacOs) ...
- [**earchive**](http://atria-soft.github.io/earchive) : Generic access to a zip file (used to access on file on Android) - [**earchive**](http://atria-soft.github.io/earchive) : Generic access to a zip file (used to access on file on Android)
- [**egami**](http://atria-soft.github.io/egami) : generic image accessor for PNG, svg and bmp image (might add some other type ...) - [**egami**](http://atria-soft.github.io/egami) : generic image accessor for PNG, svg and bmp image (might add some other type ...)
- [**esvg**](http://atria-soft.github.io/esvg) : Generic SVG image parser and displayer - [**e-svg**](http://atria-soft.github.io/esvg) : Generic SVG image parser and displayer
- [**e-json**](http://atria-soft.github.io/ejson) : JSON file access (read and write) - [**e-json**](http://atria-soft.github.io/ejson) : JSON file access (read and write)
- [**e-xml**](http://atria-soft.github.io/exml) : XML file access (read and write) - [**e-xml**](http://atria-soft.github.io/exml) : XML file access (read and write)
- [**audio**](http://musicdsp.github.io/audio) : Basic audio format - [**audio**](http://musicdsp.github.io/audio) : Basic audio format
- [**audio-orchestra**](http://musicdsp.github.io/audio-orchestra) : Low level wrapper of audio interface (Linux/Windows/MacOs/IOs/Android) - [**audio-orchestra**](http://musicdsp.github.io/audio-orchestra) : Low level wrapper of audio interface (Linux/Windows/MacOs/IOs/Android)
- [**audio-river**](http://musicdsp.github.io/audio-river) : High level audio abstraction - [**audio-drain**](http://musicdsp.github.io/audio-drain) : single stream audio processing
- [**ege**](http://musicdsp.github.io/ege) : Ewol Game engine is a wrapper on the the bullet physical engine and ewol renderer engin. This is in developpement for now (the simple objective is to produce game to make profitable all my work) - [**audio-river**](http://musicdsp.github.io/audio-river) : High level audio abstraction
- [**audio-ess**](http://musicdsp.github.io/audio-ess) : basic sound set manager
- [**ege**](http://musicdsp.github.io/ege) : Ewol Game engine is a wrapper on the the bullet physical engine and ewol renderer engin. This is in developpement for now (the simple objective is to produce game to make profitable all my work)
- [**zeus**](http://atria-soft.github.io/zeus) : RPC over websocket
- [**dollar**](http://atria-soft.github.io/dollar) : $1 $n $p and $p+
External: {#ewol_mainpage_ext} External: {#ewol_mainpage_ext}
--------- ---------
- **linearmath** : bullet mathamatical sub lib (for using same vec3). - **linearmath** : bullet mathamatical sub lib (for using same vec3).
- **Z lib** : Clkassical zlib lib. - **Z lib** : Clkassical zlib lib.
- **libPNG** : the classical png display lib. - **libPNG** : the classical png display lib.
- **ogg** : The classical Ogg coder reader lib. - **ogg** : The classical Ogg coder reader lib.
- **freetype** : The classicle true-type reader lib. - **freetype** : The classicle true-type reader lib.
- **bulletlib** : the classical bullet library physical engine. (dependence by ege) - **bulletlib** : the classical bullet library physical engine. (dependence by ege)
- **openSSL** : generic SSL library. (dependence by zeus)
Program Using EWOL {#ewol_mainpage_using} Program Using EWOL {#ewol_mainpage_using}
------------------ ------------------
- [**edn**](http://musicdsp.github.io/edn): (Application in GPLv3) Edn is the main application using this lib and designed for (in the first time). This is a "Code editor". - [**edn**](http://github.com/HeeroYui/edn): (Application in GPLv3) Edn is the main application using this lib and designed for (in the first time). This is a "Code editor".
- [**worddown**](http://play.google.com/store/apps/details?id=com.edouarddupin.worddown): (Proprietary) Worddown is a simple word game. - [**worddown**](http://play.google.com/store/apps/details?id=com.edouarddupin.worddown): (Proprietary) Worddown is a simple word game.
Main documentation: {#ewol_mainpage_sub_doc} Main documentation: {#ewol_mainpage_sub_doc}
=================== ===================
[page_bases] - @ref ewol_build
[page_FAQ] - @ref ewol_page_bases
[doc[001_bases | Global Documantation]] - @ref ewol_tutorials
- @ref ewol_coding_style
[tutorial[000_Build | Tutorials]]

383
doc/tutorial/001_HelloWord.md
View File

@ -1,71 +1,62 @@
EWOL: Hello world {#ewol_tutorial_hello_world}
Objectif:
=========
:** Understand basis of ewol
:** Create a simple windows with a label "Hello Word"
Application Sources:
====================
Application Main:
================= =================
A generic Ewol application is manage by creating an [class[ewol::context::Application]] that is the basis of your application. @tableofcontents
Due to the fact the ewol library is a multi-platform framework (base on [lib[gale|Gale]]), you will have many contraint like: Objectif: {#ewol_tutorial_hello_world_objectives}
:** One application at the same time (note an exception for android wallpaper) =========
:** One Windows displayable at the time (main point of view of apple developpers) - Understand basis of ewol
:** Not a big CPU ... - Create a simple windows with a label "Hello Word"
debug tools: {#ewol_tutorial_hello_world_debug}
============
I will use for all test a basic template [elog](http://atria-soft.github.io/elog) for debug logger that redirect logs in Android and IOs
File ```appl/debug.h```:
@include HelloWord/appl/debug.h
File ```appl/debug.cpp```:
@include HelloWord/appl/debug.cpp
Application Sources: {#ewol_tutorial_hello_world_sources}
====================
Application Main: {#ewol_tutorial_hello_world_sources_main}
-----------------
A generic Ewol application is manage by creating an ewol::context::Application that is the basis of your application.
Due to the fact the ewol library is a multi-platform framework (base on [GALE](http://atria-soft.github.io/gale)), you will have many contraint like:
- One application at the same time (note an exception for android wallpaper)
- One Windows displayable at the time (main point of view of apple developpers)
- Not a big CPU ...
Then we will create the application: Then we will create the application:
[code style=c++] First things: Some includes:
namespace appl {
class MainApplication : public ewol::context::Application {
public:
void onCreate(ewol::Context& _context) override {
APPL_INFO("==> CREATE ... " PROJECT_NAME " (BEGIN)");
// nothing to do ...
APPL_INFO("==> CREATE ... " PROJECT_NAME " (END)");
}
void onStart(ewol::Context& _context) override {
APPL_INFO("==> START ... " PROJECT_NAME " (BEGIN)");
// nothing to do ...
APPL_INFO("==> START ... " PROJECT_NAME " (END)");
}
void onResume(ewol::Context& _context) override {
APPL_INFO("==> RESUME ... " PROJECT_NAME " (BEGIN)");
// nothing to do ...
APPL_INFO("==> RESUME ... " PROJECT_NAME " (END)");
}
void onPause(ewol::Context& _context) override {
APPL_INFO("==> PAUSE ... " PROJECT_NAME " (BEGIN)");
// nothing to do ...
APPL_INFO("==> PAUSE ... " PROJECT_NAME " (END)");
}
void onStop(ewol::Context& _context) override {
APPL_INFO("==> STOP ... " PROJECT_NAME " (START)");
// nothing to do ...
APPL_INFO("==> STOP ... " PROJECT_NAME " (END)");
}
void onDestroy(ewol::Context& _context) override {
APPL_INFO("==> DESTROY ... " PROJECT_NAME " (START)");
// nothing to do ...
APPL_INFO("==> DESTROY ... " PROJECT_NAME " (END)");
}
};
};
[/code]
The input [class[ewol::Context]] is the main system context. @snippet HelloWord/appl/Main.cpp ewol_sample_HW_main_include
[note] Declare the application:
It is important to know that the system can create your application multiple times, the basic exemple of this is the Wallpaper on Android.
@snippet HelloWord/appl/Main.cpp ewol_sample_HW_main_application
The input ewol::Context is the main system context (for ewol).
**Note:**
```
It is important to know that the system can create your application multiple times, the basic example of this is the Wallpaper on Android.
What is done: What is done:
** When we select the wallpaper it create a new application (to show an example) - When we select the wallpaper it create a new application (to show an example)
** When applying your choice, it create the real one an remove the previous one. - When applying your choice, it create the real one an remove the previous one.
[/note] ```
In all program we need to have a main() In all program we need to have a main()
@ -73,247 +64,151 @@ To be portable on Android, the "main" in the java might call your main through t
To simplify compabilities between platform it is recommanded to not add other things in the application main: To simplify compabilities between platform it is recommanded to not add other things in the application main:
[code style=c++] @snippet HelloWord/appl/Main.cpp ewol_sample_HW_main_main
int main(int argc, const char *argv[]) {
// only one things to do :
return ewol::run(new appl::MainApplication(), _argc, _argv);
}
[/code]
Some configuration are needed Some configuration are needed {#ewol_tutorial_hello_world_sources_config}
============================= -----------------------------
In your application you can use many configuration, it is really better to set all your configuration dynamic. In your application you can use many configuration, it is really better to set all your configuration dynamic.
With this basic condiction will simplify the interface of the library if you would have many different application With this basic condition will simplify the interface of the library if you would have many different application
(never forger the compilator garbage collector is really very efficient). (never forget the compilator garbage collector is really very efficient).
All of this will be done one time:
Then we will do it in:
@snippet HelloWord/appl/Main.cpp ewol_sample_HW_main_create
### Parse arguments: ####
All the argument is store in the ewol main application context: just get it...
@snippet HelloWord/appl/Main.cpp ewol_sample_HW_main_parse_arguments
### Set basic windosw size (for desktop): ####
On descktop you can specify a start windows size:
@snippet HelloWord/appl/Main.cpp ewol_sample_HW_main_set_windows_size
### Select fonts: ####
[b]Select fonts:[/b]
This can be a problem when you design an application for some other operating system (OS), This can be a problem when you design an application for some other operating system (OS),
They do not have the same default font. They do not have the same default fonts, than you can embended some of them or try to use the system fonts.
We select an order to search the font names and the system basic size. We select an order to search the font names and the system basic size.
[code style=c++]
// Use External font depending on the system (for specific application, it is better to provide fonts) @snippet HelloWord/appl/Main.cpp ewol_sample_HW_main_set_font_property
_context.getFontDefault().setUseExternal(true);
// Select font in order you want : if Ewol find FreeSerif, it selected it ...
_context.getFontDefault().set("FreeSerif;DejaVuSansMono", 19);
[/code]
Main Windows: Main Windows: {#ewol_tutorial_hello_world_sources_windows}
============= -------------
Create the main Windows: Create the main Windows:
For this point we will create a class that herited form the basic [class[ewol::widget::Windows]] class: For this point we will create a class that herited form the basic ewol::widget::Windows class:
[b]Windows.h[/b] @include HelloWord/appl/Windows.h
[code style=c++]
#pragma once
#include <ewol/widget/Windows.h>
namespace appl {
class Windows;
using WindowsShared = ememory::SharedPtr<appl::Windows>;
using WindowsWeak = ememory::WeakPtr<appl::Windows>;
class Windows : public ewol::widget::Windows {
protected:
Windows(void);
init();
public:
DECLARE_FACTORY(Windows);
virtual ~Windows(void) {};
};
};
[/code]
The C macro "DECLARE_FACTORY" create a simple factory function "create" that return the [class[ewol::Object]] well create. The C macro "DECLARE_FACTORY" create a simple factory function "create" that return the ewol::Object well create.
For some internal reason, we create the object and we call the "init" function after creating the object. When well done we return the shared object created. For some internal reason, we create the object and we call the "init" function after creating the object. When well done we return the shared object created.
See [tutorial[010_ObjectModel | Next: Object model]] to understand why this structure is so complex. See @ref ewol_tutorial_object_model to understand why this structure is so complex.
[b]Windows.cpp[/b] @include HelloWord/appl/Windows.cpp
[code style=c++]
#include <ewol/ewol.h>
#include <appl/debug.h>
#include <appl/Windows.h>
#include <ewol/widget/Label.h>
appl::Windows::Windows() {
addObjectType("appl::Windows");
propertyTitle.setDirectCheck(std::string("sample ") + PROJECT_NAME);
}
void appl::Windows::init() {
ewol::widget::Windows::init();
ewol::widget::LabelShared tmpWidget = ewol::widget::Label::create();
if (tmpWidget == nullptr) {
APPL_ERROR("Can not allocate widget ==> display might be in error");
} else {
tmpWidget->propertyValue.set("Hello <font color='blue'>World</font>");
tmpWidget->propertyExpand.set(bvec2(true,true));
setSubWidget(tmpWidget);
}
}
[/code]
The init function is virtual and you must call your parent object (or at least the [class[ewol::Object]] init) The init function is virtual and you must call your parent object (or at least the ewol::Object::init)
[code style=c++]
ewol::widget::Windows::init();
[/code]
The title is assiciated on the current windows then it is a simple [class[ewol::widget::Windows]] property. @snippet HelloWord/appl/Windows.cpp ewol_sample_HW_windows_init
Please use the "setDirectCheck" fucntion instead of "set" function when you are in the constructor (the callback can be unstable when we construct the object)
[code style=c++]
propertyTitle.setDirectCheck(std::string("sample ") + PROJECT_NAME);
[/code]
The object [class[ewol::widget::Windows]] is a simple container. But the reference between Object is shared_ptr, and this is not accessible in the constructor. This is the reason we use init function.
After we simple create a [class[widget::Label]] in the main windows init.
The title is associated on the current windows then it is a simple property of ewol::widget::Windows.
We can change with calling the "setDirectCheck" function instead of "set" function when you are in the constructor (the callback can be unstable when we construct the object)
@snippet HelloWord/appl/Windows.cpp ewol_sample_HW_windows_title
The object ewol::widget::Windows is a simple container.
But the reference between Object is ememory::SharedPtr, and this is not accessible in the constructor.
This is the reason we use init function.
After we simple create a ewol::widget::Label in the main windows init.
We set label and basic properties: We set label and basic properties:
[code style=c++]
std::shared_ptr<ewol::widget::Label> tmpWidget = ewol::widget::Label::create();
tmpWidget->propertyValue.set("Hello <font color='blue'>World</font>");
tmpWidget->propertyExpand.set(bvec2(true,true));
[/code]
We can see in this example that the label have some other property like the font color.
@snippet HelloWord/appl/Windows.cpp ewol_sample_HW_windows_label
When we call the function ```ewol::Windows::setSubWidget```, it use the SharedFromThis() function that create an exception if we are in constructor (when setting the sub-widget parrent)
We can see in this example that the label have some other property like the font color.
The label can have decorated text based on the html generic writing but it is composed with really simple set of balise. The label can have decorated text based on the html generic writing but it is composed with really simple set of balise.
I will take a really long time to create a real html parser. I will take a really long time to create a real html parser.
The availlable property is: The availlable property is:
:** [b]<br/>[/b] : New line - ```<br/>``` : New line
:** [b]<font color="#FF0000\"> ... </font>[/b] : change the font color. - ```<font color="#FF0000\"> ... </font>``` : change the font color.
:** [b]<center> ... </center>[/b] : center the text. - ```<center> ... </center>``` : center the text.
:** [b]<left> ... </left>[/b] : Set the text on the left. - ```<left> ... </left>``` : Set the text on the left.
:** [b]<right> ... </right>[/b] : Set the text on the right. - ```<right> ... </right>``` : Set the text on the right.
:** [b]<justify> ... </justify>[/b] : Set the text mode in justify. - ```<justify> ... </justify>``` : Set the text mode in justify.
[note] **Note:**
```
The xml parser is a little strict on the case and end node (!! </br> !!), The xml parser is a little strict on the case and end node (!! </br> !!),
but it support to: but it support to:
:** Not have a main node. - Not have a main node.
:** replace '"' with ''' to simplify xml writing in C code. - replace '"' with ''' to simplify xml writing in C code.
[/note] ```
The last step is to add the widget on the windows:
[code style=c++]
setSubWidget(tmpWidget);
[/code]
When we call this function, it use the shared_from_this() function that create an exception if we are in constructor (when setting the wub-widget parrent)
Configure Ewol to have display the windows Configure Ewol to have display the windows {#ewol_tutorial_hello_world_sources_configure_ewol}
========================================== ------------------------------------------
At this point we have created the basic windows.
But the system does not know it.
Then we create windows and set it in the main context main ```appl::MainApplication::onCreate```:
@snippet HelloWord/appl/Main.cpp ewol_sample_HW_main_set_windows
At this point we have created the basic windows.
But the system does not know it.
Then we create windows and set it in the main context main (in the appl::MainApplication::init()):
[code style=c++]
ewol::WindowsShared basicWindows = appl::Windows::create());
// create the specific windows
_context.setWindows(basicWindows);
[/code]
Here we call the create function that is created by the DECLARE_FACTORY macro Here we call the create function that is created by the DECLARE_FACTORY macro
Then the init fuction is: **Note:**
[code style=c++]
bool MainApplication::init(ewol::Context& _context, size_t _initId) {
APPL_INFO("==> Init APPL (START)");
// select internal data for font ...
_context.getFontDefault().setUseExternal(true);
_context.getFontDefault().set("FreeSerif;DejaVuSansMono", 19);
ewol::WindowsShared basicWindows = appl::Windows::create();
// create the specific windows
_context.setWindows(basicWindows);
APPL_INFO("==> Init APPL (END)");
return true;
}
[/code]
[note] ```
You can use many windows and select the one you want to display, but I do not think it is the best design. You can use many windows and select the one you want to display, but I do not think it is the best design.
[/note] ```
Build declaration: Build declaration: {#ewol_tutorial_hello_world_build}
================== ==================
ewol commonly use the [b]lutin[/b] build system. Ewol commonly use the [lutin](http://HeeroYui.github.io/lutin) build system.
Then we need to add a "lutin_YourApplicationName.py", then for this example: [b]lutin_ewol-sample-HelloWord.py[/b] Then we need to add a "lutin_YourApplicationName.py", then for this example: ```lutin_ewol-sample-HelloWord.py```
@include lutin_ewol-sample-HelloWord.py
[code style=python] Show [lutin](http://HeeroYui.github.io/lutin/lutin_module.html) doc for more information...
#!/usr/bin/python
import lutin.module as module
import lutin.tools as tools
def get_type(): Build your application {#ewol_tutorial_hello_world_buildappl}
return "BINARY"
def get_sub_type():
return "SAMPLE"
def get_desc():
return "Tutorial 001 : Hello Word"
def get_licence():
return "APACHE-2"
def get_compagny_type():
return "com"
def get_compagny_name():
return "atria-soft"
def get_maintainer():
return ["Mr DUPIN Edouard <yui.heero@gmail.com>"]
def get_version():
return [0,1]
def create(target, module_name):
my_module = module.Module(__file__, module_name, get_type())
my_module.add_src_file([
'appl/Main.cpp',
'appl/debug.cpp',
'appl/Windows.cpp',
])
my_module.add_module_depend(['ewol'])
my_module.compile_flags('c++', [
"-DPROJECT_NAME=\"\\\""+my_module.name+"\\\"\"",
"-DAPPL_VERSION=\"\\\"" + tools.version_to_string(get_version()) + "\\\"\""
])
my_module.add_path(tools.get_current_path(__file__))
return my_module
[/code]
show lutin doc for more information...
[note]
I do not explain again the lutin file, for next tutorial, show example sources ...
[/note]
Build your application
====================== ======================
Go to your workspace folder and launch Go to your workspace folder and launch:
[code style=shell]
```{.sh}
lutin -C -mdebug ewol-sample-HelloWord lutin -C -mdebug ewol-sample-HelloWord
# or # or
lutin -C -mdebug ewol-sample-HelloWord?build lutin -C -mdebug ewol-sample-HelloWord?build
[/code] ```
Your program example will build correctly... You can now execute your application:
Launch it : ```{.sh}
[code style=shell]
lutin -C -mdebug ewol-sample-HelloWord?run lutin -C -mdebug ewol-sample-HelloWord?run
[/code] ```

89
doc/tutorial/010_ObjectModel.md
View File

@ -1,73 +1,84 @@
EWOL: Object model {#ewol_tutorial_object_model}
==================
Objectifs: @tableofcontents
Objectifs: {#ewol_tutorial_object_model_objectives}
========== ==========
:** Understand ewol basic [class[ewol::Object]] - Understand ewol basic ewol::Object
:** Use [class[ewol::Object]] correctly - Use ewol::Object correctly
Basis of the ewol::Object Basis of the ewol::Object {#ewol_tutorial_object_model_object}
========================= =========================
An object in Ewol is a simple class: [class[ewol::Object]] This object is the basis of all element in the ewol system. An object in Ewol is a simple class: ewol::Object This object is the basis of all element in the ewol system.
This is designed to manage many common things: This is designed to manage many common things:
:** Unique ID - Unique ID
:** Name - Name
:** Parameters - Parameters
:** Signal generation - Signal generation
:** Xml configuration - Xml configuration
:** Removing - Removing
[note] **Note:**
```
Please do not compare with the gObject basic class... Please do not compare with the gObject basic class...
[/note] ```
Create an Object: Create an Object: {#ewol_tutorial_object_model_create}
================= =================
Creating an object is really simple: Creating an object is really simple:
[code style=c++] ```{.cpp}
ewol::widget::ButtonShared tmpButon = ewol::widget::Button::create(); ewol::widget::ButtonShared tmpButon = ewol::widget::Button::create();
APPL_INFO("We just create a button widget with unique ID=" << tmpButon->getId() << " name='" << tmpButon->propertyName.get() << "'"); APPL_INFO("We just create a button widget with unique ID=" << tmpButon->getId() << " name='" << tmpButon->propertyName.get() << "'");
[/code] ```
Note that all object created are [class[ememory::SharedPtr]] base for the current version on [class[std::shared_ptr]]. Note that all object created are ememory::SharedPtr base for the current version on std::shared_ptr.
We wrapped it because the current inplementation of [class[std::shared_ptr]] is not thread safe, and we want use a thread-safe vertion of it. We wrapped it because the current inplementation of std::shared_ptr is not thread safe, and we want use a thread-safe version of it.
[note] **Note:**
```
The widget is not stored in a ememory::SharedPtr<ewol::widget::Button> but in a ewol::widget::ButtonShared to simplify the using of the pointer. The widget is not stored in a ememory::SharedPtr<ewol::widget::Button> but in a ewol::widget::ButtonShared to simplify the using of the pointer.
You have also: ememory::WeakPtr<ewol::widget::Button> = ewol::widget::ButtonWeak You have also: ememory::WeakPtr<ewol::widget::Button> = ewol::widget::ButtonWeak
[/note] ```
Set the name of the object: Set the name of the object:
[code style=c++] ```{.cpp}
tmpButon->propertyName.set("my widget name"); tmpButon->propertyName.set("my widget name");
APPL_INFO("We just create an Object with ID=" << tmpButon->getId() << " name='" << tmpButon->propertyName.get() << "'"); APPL_INFO("We just create an Object with ID=" << tmpButon->getId() << " name='" << tmpButon->propertyName.get() << "'");
[/code] ```
Remove an Object: Remove an Object: {#ewol_tutorial_object_model_remove}
================= =================
Simply use the function: Simply use the function:
[code style=c++] ```{.cpp}
tmpButon->destroy(); tmpButon->destroy();
[/code] ```
This function request his parrent to remove the [class[ememory::SharedPtr]] it keep on it. This function request his parrent to remove the ememory::SharedPtr it keep on it.
And when all std::shared_ptr is removed the object will be really removed. And when all ememory::SharedPtr is removed the object will be really removed.
At his point we can think an object is allive all the time someone keep a reference on it, then when you are not a parrent of the object, do not keep a [class[ememory::SharedPtr]] but a [class[ememory::WeakPtr]]. At his point we can think an object is alive all the time someone keep a reference on it,
then when you are not a parrent of the object, do not keep a ememory::SharedPtr but a ememory::WeakPtr.
[note] **Note:**
```
If some Object is not removed when you close the application, the system inform you with displaying all object alive. If some Object is not removed when you close the application, the system inform you with displaying all object alive.
[/note] ```
Retrieve an Object: Retrieve an Object: {#ewol_tutorial_object_model_find}
=================== ===================
In Ewol this is possible to get a object with his name. In Ewol this is possible to get a object with his name.
@ -75,43 +86,43 @@ In Ewol this is possible to get a object with his name.
Find a global Object (ouside an Object) Find a global Object (ouside an Object)
--------------------------------------- ---------------------------------------
[code style=c++] ```{.cpp}
#include <ewol/context/Context.h> #include <ewol/context/Context.h>
ewol::ObjectShared tmpObject = ewol::getContext().getEObjectManager().getObjectNamed("obj Name"); ewol::ObjectShared tmpObject = ewol::getContext().getEObjectManager().getObjectNamed("obj Name");
if (tmpObject == nullptr) { if (tmpObject == nullptr) {
APPL_ERROR("The Object does not exist"); APPL_ERROR("The Object does not exist");
} }
[/code] ```
Find a global Object (inside an Object) Find a global Object (inside an Object)
--------------------------------------- ---------------------------------------
[code style=c++] ```{.cpp}
ewol::ObjectShared tmpObject = getObjectNamed("obj Name"); ewol::ObjectShared tmpObject = getObjectNamed("obj Name");
if (tmpObject == nullptr) { if (tmpObject == nullptr) {
APPL_ERROR("The Object does not exist"); APPL_ERROR("The Object does not exist");
} }
[/code] ```
Find a sub-object Find a sub-object
----------------- -----------------
[code style=c++] ```{.cpp}
ewol::ObjectShared tmpObject = getSubObjectNamed("obj Name"); ewol::ObjectShared tmpObject = getSubObjectNamed("obj Name");
if (tmpObject == NULL) { if (tmpObject == NULL) {
APPL_ERROR("The Object does not exist"); APPL_ERROR("The Object does not exist");
} }
[/code] ```
retriving your object type retriving your object type
-------------------------- --------------------------
It could be really interesting to retrive your own instance: It could be really interesting to retrive your own instance:
[code style=c++] ```{.cpp}
ewol::ObjectShared tmpObject ...; ewol::ObjectShared tmpObject ...;
appl::MyOwnObjectShared myObject = std::dynamic_pointer_cast<appl::MyOwnObject>(tmpObject); appl::MyOwnObjectShared myObject = std::dynamic_pointer_cast<appl::MyOwnObject>(tmpObject);
[/code] ```

91
doc/tutorial/011_ObjectConfig.md
View File

@ -1,52 +1,59 @@
EWOL: Object config {#ewol_tutorial_object_config}
Objectifs:
==========
:** Understand base of [lib[eproperty]] configuration parameter
:** Create an configurable object
Configuration using
=================== ===================
All [class[ewol::Object]] have a configuration of parameters (the object name is a parameter), Then we need to set get and use xml to update parameters. @tableofcontents
Set a Parameter/Property Objectifs: {#ewol_tutorial_object_config_objectives}
==========
- Understand base of [e-property](http://atria-soft.github.io/eproperty) configuration parameter
- Create an configurable object
Configuration using {#ewol_tutorial_object_configusing}
===================
All ewol::Object have a configuration of parameters (the object name is a parameter),
then we need to set get and use xml to update parameters.
Set a Parameter/Property {#ewol_tutorial_object_config_prop}
------------------------ ------------------------
[note] **Note:**
Parameter is managed by the [lib[eproperty|e-property library]]
[/note] ```
Parameter is managed by the [e-property](http://atria-soft.github.io/eproperty)
```
With a string configuration With a string configuration
*************************** ***************************
[code style=c++] ```{.cpp}
if (tmpObject->parameterSet("name", "new name of object") == false) { if (tmpObject->properties.set("name", "new name of object") == false) {
APPL_ERROR("Can not set object parameter"); APPL_ERROR("Can not set object parameter");
} }
[/code] ```
whith the object name whith the object name
********************* *********************
[code style=c++] ```{.cpp}
if (parameterSetOnWidgetNamed("objectName", "value", "16.2") == false) { if (ewol::propertySetOnObjectNamed("objectName", "value", "16.2") == false) {
APPL_ERROR("Can not set object parameter"); APPL_ERROR("Can not set object parameter");
} }
[/code] ```
Get Parameter Get Parameter {#ewol_tutorial_object_config_param}
------------- -------------
[code style=c++] ```{.cpp}
std::string val = tmpObject->parameterGet("name"); std::string val = tmpObject->properties.get("name");
APPL_INFO("Get Object property : name='" << val << "'"); APPL_INFO("Get Object property: name='" << val << "'");
[/code] ```
Implement configuration Implement configuration {#ewol_tutorial_object_config_impl}
======================= =======================
[code style=c++] ```{.cpp}
#include <ewol/object/Object.h> #include <ewol/object/Object.h>
namespace appl { namespace appl {
class MyObj : public ewol::Object { class MyObj : public ewol::Object {
@ -75,25 +82,29 @@ namespace appl {
} }
} }
} }
[/code] ```
In the contructor we need to add: In the contructor we need to add:
[code style=c++] ```{.cpp}
m_value(*this, "value", false, "Value of the parameter (descrition string)") propertyValue(this,
[/code] "value",
:** [b]'this':[/b] Pointer the main class to call it chen value change. false,
:** [b]"value":[/b] Is the name of the parameter. "Value of the parameter (descrition string)",
:** [b]false:[/b] The default value. &appl::MyObj::onChangeParameterValue)
:** [b]"....."[/b] Description of the parameter (optionnal). ```
:** [b]&appl::MyObj::onChangeParameterValue[/b] The callback when the value change (optionnal). - **'this':** Pointer the main class to call it chen value change.
- **"value":** Is the name of the parameter.
- **false:** The default value.
- **"....."** Description of the parameter (optionnal).
- **&appl::MyObj::onChangeParameterValue** The callback when the value change (optionnal).
The last point is that the *m_value is an inline fuction then it take no more CPU cycle to access the value than normal variable. The last point is that the ```*propertyValue``` same as ```propertyValue.get()``` are inline fuction then it take no more CPU cycle to access the value than normal variable.
Some other parameter are availlable : Some other parameter are availlable :
:** eproperty::Value<T> Basic parameter. - eproperty::Value<T> Basic parameter.
:** eproperty::Range<T> For numeric parameter that range value are check befor setting new value. - eproperty::Range<T> For numeric parameter that range value are check befor setting new value.
:** eproperty::List<T> For List of parameter values. - eproperty::List<T> For List of parameter values.
For more information see [lib[eproperty]] For more information see [e-property](http://atria-soft.github.io/eproperty)

64
doc/tutorial/012_ObjectMessage.md
View File

@ -1,40 +1,44 @@
EWOL: Object message {#ewol_tutorial_object_message}
====================
Objectifs: @tableofcontents
Objectifs: {#ewol_tutorial_object_message_objectifs}
========== ==========
:** Understand base of [lib[esignal]] Messaging system - Understand base of [e-signal](http://atria-soft.github.io/esignal) Messaging system
:** Create extern message and receive Object message - Create extern message and receive Object message
Message system Message system {#ewol_tutorial_object_message_system}
============== ==============
esignal base his signal on landa functions esignal base his signal on landa functions
It permit to an object to generate some [b]'signals'[/b]. It permit to an object to generate some **'signals'**
All signal are synchronous [i](asynchronous is not implemented yet)[/i] All signal are synchronous *(asynchronous is not implemented yet)*
Receive signals from other object Receive signals from other object {#ewol_tutorial_object_message_from_object}
================================= =================================
Register on the 'up' and 'value' signal of a button: Register on the 'up' and 'value' signal of a button:
Button header : Button header :
[code style=c++] ```{.cpp}
... ...
public: public:
esignal::ISignal<> signalDown; esignal::Signal<> signalDown;
esignal::ISignal<> signalUp; esignal::Signal<> signalUp;
... ...
esignal::ISignal<bool> signalValue; esignal::Signal<bool> signalValue;
... ...
[/code] ```
simple signal connection: simple signal connection:
------------------------- -------------------------
[code style=c++] ```{.cpp}
#include <ewol/object/Object.h> #include <ewol/object/Object.h>
#include <ewol/widget/Button.h> #include <ewol/widget/Button.h>
namespace appl { namespace appl {
@ -49,15 +53,15 @@ namespace appl {
} }
void init() { void init() {
ewol::Object::init(); ewol::Object::init();
m_button = ewol::widget::Button::Create(); m_button = ewol::widget::Button::create();
if (m_button == nullptr) { if (m_button == nullptr) {
APPL_ERROR("Can not create button..."); APPL_ERROR("Can not create button...");
return; return;
} }
m_button.propertyToggle.set(true); m_button->propertyToggle.set(true);
// We connect signals here: (permanent connection) // We connect signals here: (permanent connection)
m_button->signalUp.connect(shared_from_this(), &appl::MyObj::onCallbackUp); m_button->signalUp.connect(sharedFromThis(), &appl::MyObj::onCallbackUp);
m_button->signalValue.connect(shared_from_this(), &appl::MyObj::onCallbackValue); m_button->signalValue.connect(sharedFromThis(), &appl::MyObj::onCallbackValue);
} }
public: public:
//! @brief Destructor //! @brief Destructor
@ -82,23 +86,27 @@ namespace appl {
} }
} }
} }
[/code] ```
[note] **Note:**
```
The connection with SharedPtr are static. they keep in internal a WeakPtr to remove connection if the object is removed. The connection with SharedPtr are static. they keep in internal a WeakPtr to remove connection if the object is removed.
[/note] ```
[note] **Note:**
The connection that return a [class[esignal::Connection]] are volatil, if you don't keep the connection handle, the connection is automaticly removed.
[/note]
Declare Signal: ```
The connection that return a esignal::Connection are volatil, if you don't keep the connection handle, the connection is automaticly removed.
```
Declare Signal: {#ewol_tutorial_object_message_declare}
=============== ===============
source source
------- -------
[code style=c++] ```{.cpp}
#include <ewol/object/Object.h> #include <ewol/object/Object.h>
#include <ewol/widget/Button.h> #include <ewol/widget/Button.h>
namespace appl { namespace appl {
@ -127,14 +135,14 @@ namespace appl {
} }
} }
} }
[/code] ```
Conclusion: Conclusion: {#ewol_tutorial_object_message_conclusion}
=========== ===========
You will now able to reise signals between objects... You will now able to reise signals between objects...
For more information see [lib[esignal]] For more information see [e-signal](http://atria-soft.github.io/esignal)

105
doc/tutorial/020_FileAccess.md
View File

@ -1,67 +1,74 @@
EWOL: File access {#ewol_tutorial_file_access}
=================
Objectifs: @tableofcontents
Objectifs: {#ewol_tutorial_file_access_objectifs}
========== ==========
- Understand why we wrap interface on file system - Understand why we wrap interface on file system
- read and write files
Limitation Limitation {#ewol_tutorial_file_access_limit}
========== ==========
Application generation is really simple, but package management can create some problems... Application generation is really simple, but package management can create some problems...
For example : For example :
:** Android does not permit access on the file system, but we need data that is named assets, these data in contained in a zip file. - Android does not permit access on the file system, but we need data that is named assets, these data in contained in a zip file.
:** Linux set his own application data in a special path : /usr/shared/applName/ - Linux set his own application data in a special path : /usr/shared/applName/
:** MacOs create a bundle (*.app) that is a folder with all application data. - MacOs create a bundle (*.app) that is a folder with all application data.
:** ... - ...
For all these reasons we need to wrap standard application interface. (you can acces directly but it could be tricky and depend on the target) For all these reasons we need to wrap standard application interface. (you can acces directly but it could be tricky and depend on the target)
Generic Properties Generic Properties {#ewol_tutorial_file_access_property}
================== ==================
By default we dertermine some basics for files. By default we dertermine some basics for files.
Then we need to determine file in the tree with: Then we need to determine file in the tree with:
:** "DATA:XXX" Application internal data - **"DATA:XXX"** Application internal data
::** Linux: /usr/share/applName/ * Linux: /usr/share/applName/
::** Android: /xxx/yyy/applName.apk/asssets/ * Android: /xxx/yyy/applName.apk/asssets/
::** IOs: applName.app/share * IOs: applName.app/share
::** MacOs: applName.app/Resources * MacOs: applName.app/Resources
:** "USERDATA:XXX" User save data (like game save) - **"USERDATA:XXX"** User save data (like game save)
::** Linux: ~/.local/share/applName/ * Linux: ~/.local/share/applName/
::** Android: /xxx/yyy/data/applName/ * Android: /xxx/yyy/data/applName/
:** "HOME:XXX" User home folder - **"HOME:XXX"** User home folder
::** Linux: ~/ * Linux: ~/
::** Android: /sdcard/ * Android: /sdcard/
::** IOs: --- => no Home * IOs: --- => no Home
::** MacOs: ~/ * MacOs: ~/
:** "/XXX" Direct acces on a file in the fileSystem - **"/XXX"** Direct acces on a file in the fileSystem
:** ... - ...
When you will call a file, you need to just call it with the starting name. When you will call a file, you need to just call it with the starting name.
For example if I want to access at an application data I will call the file : "DATA:myImage.png" For example if I want to access at an application data I will call the file : "DATA:myImage.png"
Integrate a file in a package Integrate a file in a package {#ewol_tutorial_file_access_package}
============================= =============================
In your lutin_xxx.py file add: In your ```lutin_xxx.py``` file add:
[code style=python]
```{.py}
# to copy a single file: # to copy a single file:
myModule.copy_file("relative/path/file.svg","destination/folder/file.svg") myModule.copy_file("relative/path/file.svg","destination/folder/fileNewName.svg")
# to copy an entire patern path # to copy an entire patern path
myModule.copy_folder("relative/path/start*.png","destination/folder/") myModule.copy_path("relative/path/start*.png","destination/folder/")
[/code] ```
And now you can acces on these file with : "DATA:destination/folder/file.svg" And now you can acces on these file with : "DATA:destination/folder/fileNewName.svg"
Read a file Read a file {#ewol_tutorial_file_access_read}
=========== ===========
[code style=c++]
```{.cpp}
#include <etk/os/FSNode.h> #include <etk/os/FSNode.h>
... ...
@ -84,12 +91,12 @@ Read a file
APPL_INFO("and the end of the line ='" << output << "'"); APPL_INFO("and the end of the line ='" << output << "'");
// close the file (note : if you did not do it, it will be close automaticly with an error) // close the file (note : if you did not do it, it will be close automaticly with an error)
file.fileClose(); file.fileClose();
[/code] ```
Write a file Write a file {#ewol_tutorial_file_access_write}
============ ============
[code style=c++] ```{.cpp}
#include <etk/os/FSNode.h> #include <etk/os/FSNode.h>
... ...
@ -106,42 +113,44 @@ Write a file
file.filePuts(" other string to put in the file ... \n"); file.filePuts(" other string to put in the file ... \n");
// close the file (note : if you did not do it, it will be close automaticly with an error) // close the file (note : if you did not do it, it will be close automaticly with an error)
file.fileClose(); file.fileClose();
[/code] ```
'Theme' management: 'Theme' management: {#ewol_tutorial_file_access_theme}
=================== ===================
The theme management is a subset a file selected by a main key. The theme management is a subset of a file selected by a main key.
For example The basic theme of an API can be manage with only 2 commands (set the theme, and request upate of GUI) For example the basic theme of an API can be manage with only 2 commands (set the theme, and request upate of GUI)
At the start of the program, you might specify the default path theme: At the start of the program, you might specify the default path theme:
[code style=c++] ```{.cpp}
etk::theme::setNameDefault("GUI_COLOR", "theme/black"); etk::theme::setNameDefault("GUI_COLOR", "theme/black");
etk::theme::setNameDefault("GUI_SHAPE", "theme/rounded"); etk::theme::setNameDefault("GUI_SHAPE", "theme/rounded");
[/code] ```
And when you want to change the theme, just call: And when you want to change the theme, just call:
[code style=c++] ```{.cpp}
// change the theme : // change the theme :
etk::theme::setName("GUI_COLOR", "theme/white"); etk::theme::setName("GUI_COLOR", "theme/white");
// force reload of all the resources : // force reload of all the resources :
ewol::getContext().getResourcesManager().reLoadResources(); ewol::getContext().getResourcesManager().reLoadResources();
ewol::getContext().forceRedrawAll(); ewol::getContext().forceRedrawAll();
[/code] ```
[note] **Note:**
```
This is not done automaticly, because reloading the resources can have a real cost of time. This is not done automaticly, because reloading the resources can have a real cost of time.
[/note] ```
You can acces on your theme with accessing the filename: "THEME:GUI_COLOR:your/sub/path/file.xx" You can acces on your theme with accessing the filename: "THEME:GUI_COLOR:your/sub/path/file.xx"
An important think is that the theme file is searching in many path in the order: An important think is that the theme file is searching in many path in the order:
:** USERDATA:GUI_COLOR:your/sub/path/file.xx - USERDATA:GUI_COLOR:your/sub/path/file.xx
:** DATA:GUI_COLOR:your/sub/path/file.xx - DATA:GUI_COLOR:your/sub/path/file.xx
:** USERDATA:GUI_COLOR(default):your/sub/path/file.xx - USERDATA:GUI_COLOR(default):your/sub/path/file.xx
:** DATA:GUI_COLOR(default):your/sub/path/file.xx - DATA:GUI_COLOR(default):your/sub/path/file.xx
Like this a user can overload the application theme... Like this a user can overload the application theme...

73
doc/tutorial/021_Resources.md
View File

@ -1,27 +1,32 @@
EWOL: Resources management {#ewol_tutorial_resources}
==========================
Objectifs @tableofcontents
Objectifs {#ewol_tutorial_resources_objectif}
========= =========
:** Understand what is a resource
:** Use resources
What is a resource: - Understand what is a resource
- Use resources
What is a resource: {#ewol_tutorial_resources_what}
=================== ===================
A resource is an unique element that can be used by many element like: A resource is an unique element that can be used by many element like:
:** An image (special resolution) - An image (special resolution)
:** A configuration file - A configuration file
:** An application manager (special case) - An application manager (special case)
:** A sound file - A sound file
:** ... - ...
A resource have an other objective, form some platform, the graphic interface can be stopped, then we need to reload texture in the graphic inteface... A resource have an other objective, form some platform, the graphic interface can be stopped, then we need to reload texture in the graphic inteface...
Then the texture is an other graphic interface. Then the texture is an other graphic interface.
Get a resource: Get a resource: {#ewol_tutorial_resources_get}
=============== ===============
For this example we will load a configuration file: For this example we will load a configuration file:
[code style=c++] ```{.cpp}
#include <ewol/object/Object.h> #include <ewol/object/Object.h>
#include <ewol/resource/ConfigFile.h> #include <ewol/resource/ConfigFile.h>
namespace appl { namespace appl {
@ -29,7 +34,7 @@ namespace appl {
public: public:
eproperty::Value<std::string> propertyConfig; eproperty::Value<std::string> propertyConfig;
private: private:
std::shared_ptr<ewol::resource::ConfigFile> m_config; ememory::SharedPtr<ewol::resource::ConfigFile> m_config;
int32_t m_configValId; int32_t m_configValId;
protected: protected:
//! @brief Constructor //! @brief Constructor
@ -47,7 +52,7 @@ namespace appl {
} }
public: public:
//! @brief Destructor //! @brief Destructor
virtual ~MyObj(void) { } virtual ~MyObj() { }
DECLARE_FACTORY(MyObj); DECLARE_FACTORY(MyObj);
public: public:
void onChangePropertyFile() { void onChangePropertyFile() {
@ -62,20 +67,20 @@ namespace appl {
} }
} }
} }
[/code] ```
Create a new resource: Create a new resource: {#ewol_tutorial_resources_create}
====================== ======================
A resource is a generic [class[ewol::Resource]] that herited form a generic [class[ewol::Object]], simply change the FACTORY macro in: A resource is a generic gale::Resource:
:** DECLARE_RESOURCE_FACTORY(className) To declare a resource with no name (unique for every creation) - DECLARE_RESOURCE_FACTORY(className) To declare a resource with no name (unique for every creation)
:** DECLARE_RESOURCE_NAMED_FACTORY(className) To create a resource that have a specific name. When created, we will find the previous resource with the specify name in the fanctory. - DECLARE_RESOURCE_NAMED_FACTORY(className) To create a resource that have a specific name. When created, we will find the previous resource with the specify name in the fanctory.
:** DECLARE_RESOURCE_SINGLE_FACTORY(className,uniqueName) This is to have a unique resource for all the application (name is specify in the Macro) - DECLARE_RESOURCE_SINGLE_FACTORY(className,uniqueName) This is to have a unique resource for all the application (name is specify in the Macro)
we have now some specific interface to compleate (if needed): we have now some specific interface to compleate (if needed):
The Resource Level The Resource Level {#ewol_tutorial_resources_level}
------------------ ------------------
The resources can be reloaded, then we need to reaload in the good order (level [0 .. 5]) The resources can be reloaded, then we need to reaload in the good order (level [0 .. 5])
@ -84,7 +89,7 @@ The resources are loaded fron 0 to 5.
Then for basic resource: Then for basic resource:
[code style=c++] ```{.cpp}
#include <ewol/object/Resource.h> #include <ewol/object/Resource.h>
namespace appl { namespace appl {
class MyResource : public gale::Resource { class MyResource : public gale::Resource {
@ -93,38 +98,38 @@ namespace appl {
MyResource() : MyResource() :
m_configValId(-1) { m_configValId(-1) {
m_resourceLevel = 4; m_resourceLevel = 4;
addObjectType("ewol::MyResource"); addObjectType("appl::MyResource");
} }
void init(const std::& _name) { void init(const std::string& _name) {
ewol::Resource::init(_name); ewol::Resource::init(_name);
} }
public: public:
//! @brief Destructor //! @brief Destructor
virtual ~MyResource(void) { } virtual ~MyResource() { }
DECLARE_RESOURCE_NAMED_FACTORY(MyResource); DECLARE_RESOURCE_NAMED_FACTORY(MyResource);
} }
} }
[/code] ```
Now we need to implement somme functions: Now we need to implement somme functions:
To send data on the hardware (openGL): To send data on the hardware (openGL):
[code style=c++] ```{.cpp}
void updateContext(); void updateContext();
[/code] ```
To remove data from the the hardware (openGL): To remove data from the the hardware (openGL):
[code style=c++] ```{.cpp}
void removeContext(); void removeContext();
[/code] ```
When loose hardware (juste update internal state): When loose hardware (juste update internal state the hardware is no more present):
[code style=c++] ```{.cpp}
void removeContextToLate(); void removeContextToLate();
[/code] ```
When user request to reload all resources (can be usefull when using file type : THEME:GUI:xxx) When user request to reload all resources (can be usefull when using file type : THEME:GUI:xxx)
[code style=c++] ```{.cpp}
void reload(); void reload();
[/code] ```

77
doc/tutorial/030_ConplexeXmlGui.md
View File

@ -1,53 +1,61 @@
EWOL: Comple XML GUI {#ewol_tutorial_complex_xml_gui}
====================
Objectifs: @tableofcontents
Objectifs: {#ewol_tutorial_complex_xml_gui_objectif}
========== ==========
:** What is a Widget - What is a Widget
:** Simply create a complex Gui - Simply create a complex Gui
What is a Widget What is a Widget {#ewol_tutorial_complex_xml_gui_what}
================ ================
A widget is a simple entity of a graphical Object. It herited of every [class[ewol::Object]] class with many graphical interface to draw a complex gui. A widget is a simple entity of a graphical Object. It herited of every ewol::Object class with many graphical interface to draw a complex gui.
We can consider some widget: We can consider some widget:
:** Windows: Main gui interface to display the unique "windows". - ewol::Windows: Main gui interface to display the unique "windows".
:** Container Widget: Widget that manage some subWidget (generic) - Container Widget: Widget that manage some subWidget (generic)
:** Simple widget: all widget that display somthing. - Simple widget: all widget that display somthing.
:** Meta widget: Widget composed with some wodget. - Meta widget: Widget composed with some wodget.
Simple load & configure of a widget: Simple load & configure of a widget: {#ewol_tutorial_complex_xml_gui_simple}
==================================== ====================================
We have 4 way to create a widget: We have 4 way to create a widget:
call create and configure call create and configure
------------------------- -------------------------
First create the widget: First create the widget:
[code style=c++] ```{.cpp}
ewol::widget::ButtonShared tmpWidget = ewol::widget::Button::create(); ewol::widget::ButtonShared tmpWidget = ewol::widget::Button::create();
if (tmpWidget == nullptr) { if (tmpWidget == nullptr) {
APPL_CRITICAL("The widget can not be created"); APPL_CRITICAL("The widget can not be created");
} }
[/code] ```
Set some parameters: Set some parameters:
[code style=c++] ```{.cpp}
tmpWidget->propertyName.set("my name"); tmpWidget->propertyName.set("my name");
tmpWidget->propertyExpand.set(bvec2(true,false)); tmpWidget->propertyExpand.set(bvec2(true,false));
tmpWidget->propertyFill.set(bvec2(true,true)); tmpWidget->propertyFill.set(bvec2(true,true));
[/code] ```
[note] **Note:**
```
This is the faster way to configure your gui. and the check are done when you compile your code. This is the faster way to configure your gui. and the check are done when you compile your code.
[/note] ```
==== Call create and direct configuration ==== Call create and direct configuration
------------------------------------
We can configure the wiget before the init() is called. We can configure the wiget before the init() is called.
[code style=c++] ```{.cpp}
ewol::widget::ButtonShared tmpWidget = ewol::widget::Button::create( ewol::widget::ButtonShared tmpWidget = ewol::widget::Button::create(
"name", std::string("my name"), "name", std::string("my name"),
"expand", bvec2(true,false), "expand", bvec2(true,false),
@ -55,46 +63,53 @@ We can configure the wiget before the init() is called.
if (tmpWidget == nullptr) { if (tmpWidget == nullptr) {
APPL_CRITICAL("The widget can not be created"); APPL_CRITICAL("The widget can not be created");
} }
[/code] ```
[note] **Note:**
```
The configuration is done and check at the runtime ==> you need to test it to be sure your configuration work. The configuration is done and check at the runtime ==> you need to test it to be sure your configuration work.
[/note] ```
==== Call generic factory system (compositing) ==== Call generic factory system (compositing)
-----------------------------------------
[code style=c++] ```{.cpp}
#include <ewol::widget::Composer.h> #include <ewol::widget::Composer.h>
ewol::widget::WidgetShared tmpWidget = ewol::widget::composerGenerateString("<button name='my name' expand='true,false' fill='true,true'/>"); ewol::widget::WidgetShared tmpWidget = ewol::widget::composerGenerateString("<button name='my name' expand='true,false' fill='true,true'/>");
if (tmpWidget == nullptr) { if (tmpWidget == nullptr) {
APPL_CRITICAL("The widget can not be created"); APPL_CRITICAL("The widget can not be created");
} }
[/code] ```
With this way you just like string ... With this way you just like string ...
==== Load from a xml file (compositing) ==== Load from a xml file (compositing)
----------------------------------
File gui.xml File ```gui.xml```
[code]
```{.xml}
<button name="my name" <button name="my name"
expand="true,false" expand="true,false"
fill="true,true"/> fill="true,true"/>
[/code] ```
[code style=c++] ```{.cpp}
#include <ewol::widget::Composer.h> #include <ewol::widget::Composer.h>
ewol::widget::WidgetShared tmpWidget = ewol::widget::composerGenerateFile("DATA:gui.xml"); ewol::widget::WidgetShared tmpWidget = ewol::widget::composerGenerateFile("DATA:gui.xml");
if (tmpWidget == nullptr) { if (tmpWidget == nullptr) {
APPL_CRITICAL("The widget can not be created"); APPL_CRITICAL("The widget can not be created");
} }
[/code] ```
This last way is just to simplify gui generation This last way is just to simplify gui generation
=== Now we will create a simple hierarchic gui === Now we will create a simple hierarchic gui {#ewol_tutorial_complex_xml_gui_simple}
==========================================
The objective is to create a text label area with 2 button centered. The objective is to create a text label area with 2 button centered.
**TODO ...**

45
doc/tutorial/050_CreateCustomWidget.md
View File

@ -1,15 +1,27 @@
EWOL: Create a custom Widget {#ewol_tutorial_create_custom_widget}
============================
@tableofcontents
Objectifs: {#ewol_tutorial_create_custom_widget_objectif}
==========
To create a custum widget, this is as simple as complex. To create a custum widget, this is as simple as complex.
The first things to do is to choice a methode to display you widget: The first things to do is to choice a methode to display you widget:
:** [b]Direct mode:[/b] display on openGL engine with your prefered methode (some help for shaders) - [b]Direct mode:[/b] display on openGL engine with your prefered methode (some help for shaders)
:** [b]Compositing:[/b] display with a toolbox for drawing on openGL - [b]Compositing:[/b] display with a toolbox for drawing on openGL
:** [b]Shaper:[/b] this is a special mode of compositing - [b]Shaper:[/b] this is a special mode of compositing
:** [b]Add capacity:[/b] this could be interesting to increase some capacity of a widget... - [b]Add capacity:[/b] this could be interesting to increase some capacity of a widget...
==Create the widget structure== Create the widget structure {#ewol_tutorial_create_custom_widget_structure}
===Header=== ===========================
[code style=c++]
Header
------
```{.cpp}
#include <ewol/widget/Widget.h> #include <ewol/widget/Widget.h>
#include <ewol/compisiting/Widget.h>
namespace appl { namespace appl {
class myWidget : public ewol::Widget { class myWidget : public ewol::Widget {
private: private:
@ -22,31 +34,32 @@ The first things to do is to choice a methode to display you widget:
void onRegenerateDisplay(void); void onRegenerateDisplay(void);
} }
} }
[/code] ```
We can show that we have two function, the first is call every time we render the widget (as the number of fps) "onDraw()". We can show that we have two function, the first is call every time we render the widget (as the number of fps) "onDraw()".
And the second that is call only when we need to redraw the widget (after the user call markToRedraw() ) "onRegenerateDisplay()". And the second that is call only when we need to redraw the widget (after the user call markToRedraw() ) "onRegenerateDisplay()".
===basic code=== basic code
----------
we can define some basic functions: we can define some basic functions:
The constructor: The constructor:
[code style=c++] ```{.cpp}
appl::myWidget::myWidget() { appl::myWidget::myWidget() {
addObjectType("appl::widget::VectorDisplay"); addObjectType("appl::widget::VectorDisplay");
} }
[/code] ```
The draw function: The draw function:
[code style=c++] ```{.cpp}
void appl::myWidget::onDraw() { void appl::myWidget::onDraw() {
m_draw.draw(); m_draw.draw();
} }
[/code] ```
The drawing area function (where we create the patern.). The drawing area function (where we create the patern.).
[code style=c++] ```{.cpp}
void appl::myWidget::onRegenerateDisplay() { void appl::myWidget::onRegenerateDisplay() {
//!< Check if we really need to redraw the display, if not needed, we redraw the previous data ... //!< Check if we really need to redraw the display, if not needed, we redraw the previous data ...
if (needRedraw() == false) { if (needRedraw() == false) {
@ -62,8 +75,8 @@ void appl::myWidget::onRegenerateDisplay() {
m_draw.setPos(m_size*0.2); m_draw.setPos(m_size*0.2);
m_draw.rectangleWidth(m_size*0.5); m_draw.rectangleWidth(m_size*0.5);
} }
[/code] ```
A more complex sample is availlable in [b]"ewol-sample-CustomWidget"[/b] A more complex sample is availlable in **"ewol-sample-CustomWidget"**

55
doc/tutorial/051_AddWidgetCustumInXML.md
View File

@ -1,65 +1,80 @@
EWOL: Add Widget in XML access {#ewol_tutorial_add_widget_custum_in_xml}
==============================
== Declare object in XML == @tableofcontents
Objectifs: {#ewol_tutorial_add_widget_custum_in_xml_objectif}
==========
- Create a C++ widget
- use it in a XML
Declare object in XML {#ewol_tutorial_add_widget_custum_in_xml_declare}
=====================
Object can be declared in some XML, (like gui decription), then we need to declare the Object in the system recognition. Object can be declared in some XML, (like gui decription), then we need to declare the Object in the system recognition.
=== Declare Object === Declare Object
--------------
In your application "void onCreate(ewol::Context& _context) override" add the function: In your application "void onCreate(ewol::Context& _context) override" add the function:
[code style=c++] ```{.cpp}
YourWidgetClass::createManagerWidget(_context.getWidgetManager()); YourWidgetClass::createManagerWidget(_context.getWidgetManager());
[/code] ```
The simple question is: I does not define this function, where it is done ? The simple question is: I does not define this function, where it is done ?
The createManagerWidget is instancuate when you use the macro: The createManagerWidget is instancuate when you use the macro:
[code style=c++] ```{.cpp}
DECLARE_WIDGET_FACTORY(YourWidgetClass, "YourWidgetClass"); DECLARE_WIDGET_FACTORY(YourWidgetClass, "YourWidgetClass");
[/code] ```
it create 2 function: "create(...)" and "createManagerWidget()" it create 2 function: "create(...)" and "createManagerWidget()"
=== Declare on XML and configuration === Declare on XML and configuration {#ewol_tutorial_add_widget_custum_in_xml_dec2}
================================
in the xml instance simply request it like: in the xml instance simply request it like:
[code style=xml] ```{.xml}
<YourWidgetClass name="jkjkj"> <YourWidgetClass name="jkjkj">
... ...
</YourWidgetClass> </YourWidgetClass>
[/code] ```
The xml attribute are automaticaly parsed to configure properties of you object (this is the reason of naming it). The xml attribute are automaticaly parsed to configure properties of you object (this is the reason of naming it).
=== Special case SubParsing XML element === Special case SubParsing XML element {#ewol_tutorial_add_widget_custum_in_xml_parse}
===================================
If you want to parse sub-node of the xml just override the function member: If you want to parse sub-node of the xml just override the function member:
[code style=c++] ```{.cpp}
bool loadXML(const std::shared_ptr<const exml::Element>& _node) override; bool loadXML(const exml::Element& _node) override;
[/code] ```
Many example are availlable in container widget. Many example are availlable in container widget.
Simple example: Simple example:
[code style=c++] ```{.cpp}
if (_node == nullptr) { if (_node.exist() == false) {
return false; return false;
} }
// parse generic properties: // parse generic properties:
ewol::Widget::loadXML(_node); ewol::Widget::loadXML(_node);
// parse all the elements: // parse all the elements:
for (size_t iii=0; iii < _node->size(); iii++) { for (const auto it : _node.nodes) {
std::shared_ptr<const exml::Element> pNode = _node->getElement(iii); exml::Element pNode = it.toElement();
if (pNode == nullptr) { if (pNode.exist() == false) {
// trash here all that is not element // trash here all that is not element
continue; continue;
} }
// Get the sub-node name: // Get the sub-node name:
std::string widgetName = pNode->getValue(); std::string widgetName = pNode.getValue();
if (getWidgetManager().exist(widgetName) == false) { if (getWidgetManager().exist(widgetName) == false) {
APPL_ERROR("[" << getId() << "] (l "<<pNode->getPos()<<") Unknown basic node='" << widgetName << "' not in : [" << getWidgetManager().list() << "]" ); APPL_ERROR("[" << getId() << "] (l "<<pNode->getPos()<<") Unknown basic node='" << widgetName << "' not in : [" << getWidgetManager().list() << "]" );
continue; continue;
@ -67,7 +82,7 @@ Simple example:
... ...
} }
return true; return true;
[/code] ```

18
doc/tutorials.md
View File

@ -0,0 +1,18 @@
Tutorials {#ewol_tutorials}
=========
- @ref ewol_page_bases
- @ref ewol_tutorial_hello_world
- @ref ewol_tutorial_object_model
- @ref ewol_tutorial_object_config
- @ref ewol_tutorial_object_message
- @ref ewol_tutorial_file_access
- @ref ewol_tutorial_resources
- @ref ewol_tutorial_complex_xml_gui
- @ref ewol_tutorial_create_custom_widget
- @ref ewol_tutorial_add_widget_custum_in_xml

4
doxy_ewol.py
View File

@ -14,6 +14,9 @@ def create(target, module_name):
module_name, module_name,
"doc" "doc"
]) ])
my_module.add_sample_path([
"sample"
])
my_module.add_depend([ my_module.add_depend([
'elog', 'elog',
'etk', 'etk',
@ -34,6 +37,7 @@ def create(target, module_name):
my_module.add_file_patterns([ my_module.add_file_patterns([
'*.h', '*.h',
'*.md', '*.md',
'*.py',
]) ])
return my_module return my_module

5
sample/CustomWidgets/appl/widget/VectorDisplay.cpp
View File

@ -9,19 +9,23 @@
#include <ewol/object/Manager.h> #include <ewol/object/Manager.h>
#include <etk/tool.h> #include <etk/tool.h>
//! [EWOL_SAMPLE_CW_CONSTRUCTOR]
appl::widget::VectorDisplay::VectorDisplay() : appl::widget::VectorDisplay::VectorDisplay() :
m_autoDisplay(false), m_autoDisplay(false),
m_minVal(-1.0f), m_minVal(-1.0f),
m_maxVal(1.0f) { m_maxVal(1.0f) {
addObjectType("appl::widget::VectorDisplay"); addObjectType("appl::widget::VectorDisplay");
} }
//! [EWOL_SAMPLE_CW_CONSTRUCTOR]
//! [EWOL_SAMPLE_CW_INIT]
void appl::widget::VectorDisplay::init() { void appl::widget::VectorDisplay::init() {
ewol::Widget::init(); ewol::Widget::init();
markToRedraw(); markToRedraw();
// set call all time (sample ...). // set call all time (sample ...).
getObjectManager().periodicCall.connect(sharedFromThis(), &appl::widget::VectorDisplay::periodicEvent); getObjectManager().periodicCall.connect(sharedFromThis(), &appl::widget::VectorDisplay::periodicEvent);
} }
//! [EWOL_SAMPLE_CW_INIT]
appl::widget::VectorDisplay::~VectorDisplay() { appl::widget::VectorDisplay::~VectorDisplay() {
@ -42,6 +46,7 @@ void appl::widget::VectorDisplay::ToggleAuto() {
} }
} }
//! [EWOL_SAMPLE_CW_DRAW]
void appl::widget::VectorDisplay::onDraw() { void appl::widget::VectorDisplay::onDraw() {
m_draw.draw(); m_draw.draw();
} }

8
sample/CustomWidgets/appl/widget/VectorDisplay.h
View File

@ -5,6 +5,8 @@
*/ */
#pragma once #pragma once
//! [EWOL_SAMPLE_CW_HEADER]
#include <ewol/widget/Widget.h> #include <ewol/widget/Widget.h>
#include <ewol/compositing/Drawing.h> #include <ewol/compositing/Drawing.h>
#include <ewol/widget/Manager.h> #include <ewol/widget/Manager.h>
@ -22,6 +24,10 @@ namespace appl {
DECLARE_WIDGET_FACTORY(VectorDisplay, "VectorDisplay"); DECLARE_WIDGET_FACTORY(VectorDisplay, "VectorDisplay");
//! @brief destructor //! @brief destructor
virtual ~VectorDisplay(); virtual ~VectorDisplay();
public
void onDraw() override;
void onRegenerateDisplay() override;
//! [EWOL_SAMPLE_CW_HEADER]
protected: protected:
std::vector<float> m_data; //!< data that might be displayed std::vector<float> m_data; //!< data that might be displayed
public: public:
@ -34,8 +40,6 @@ namespace appl {
float m_minVal; //!< display minimum value float m_minVal; //!< display minimum value
float m_maxVal; //!< display maximum value float m_maxVal; //!< display maximum value
public: public:
void onDraw() override;
void onRegenerateDisplay() override;
void periodicEvent(const ewol::event::Time& _event); void periodicEvent(const ewol::event::Time& _event);
}; };
} }

76
sample/HelloWord/appl/Main.cpp
View File

@ -3,11 +3,14 @@
* @copyright 2010, Edouard DUPIN, all right reserved * @copyright 2010, Edouard DUPIN, all right reserved
* @license GPL v3 (see license file) * @license GPL v3 (see license file)
*/ */
//! [ewol_sample_HW_main_all]
//! [ewol_sample_HW_main_include]
#include <etk/types.h> #include <etk/types.h>
#include <ewol/ewol.h> #include <ewol/ewol.h>
#include <gale/context/commandLine.h> #include <gale/context/commandLine.h>
//! [ewol_sample_HW_main_include]
#include <appl/debug.h> #include <appl/debug.h>
#include <appl/Windows.h> #include <appl/Windows.h>
@ -15,12 +18,47 @@
#include <ewol/widget/Manager.h> #include <ewol/widget/Manager.h>
#include <ewol/context/Context.h> #include <ewol/context/Context.h>
//! [ewol_sample_HW_main_application]
namespace appl { namespace appl {
class MainApplication : public ewol::context::Application { class MainApplication : public ewol::context::Application {
public: public:
//! [ewol_sample_HW_main_create]
void onCreate(ewol::Context& _context) override { void onCreate(ewol::Context& _context) override {
APPL_INFO(" == > CREATE ... " << PROJECT_NAME << " v" << APPL_VERSION << " (START) [" << ewol::getBoardType() << "] (" << ewol::getCompilationMode() << ") (BEGIN)"); APPL_INFO("==> CREATE ... " PROJECT_NAME " (BEGIN)");
for( int32_t iii=0 ; iii<_context.getCmd().size(); iii++) { localCreate(_context);
APPL_INFO("==> CREATE ... " PROJECT_NAME " (END)");
}
//! [ewol_sample_HW_main_create]
void onStart(ewol::Context& _context) override {
APPL_INFO("==> START ... " PROJECT_NAME " (BEGIN)");
// nothing to do ...
APPL_INFO("==> START ... " PROJECT_NAME " (END)");
}
void onResume(ewol::Context& _context) override {
APPL_INFO("==> RESUME ... " PROJECT_NAME " (BEGIN)");
// nothing to do ...
APPL_INFO("==> RESUME ... " PROJECT_NAME " (END)");
}
void onPause(ewol::Context& _context) override {
APPL_INFO("==> PAUSE ... " PROJECT_NAME " (BEGIN)");
// nothing to do ...
APPL_INFO("==> PAUSE ... " PROJECT_NAME " (END)");
}
void onStop(ewol::Context& _context) override {
APPL_INFO("==> STOP ... " PROJECT_NAME " (START)");
// nothing to do ...
APPL_INFO("==> STOP ... " PROJECT_NAME " (END)");
}
void onDestroy(ewol::Context& _context) override {
APPL_INFO("==> DESTROY ... " PROJECT_NAME " (START)");
// nothing to do ...
APPL_INFO("==> DESTROY ... " PROJECT_NAME " (END)");
}
//! [ewol_sample_HW_main_application]
void localCreate(ewol::Context& _context) {
//! [ewol_sample_HW_main_parse_arguments]
// parse all the argument of the application
for (int32_t iii=0 ; iii<_context.getCmd().size(); iii++) {
std::string tmpppp = _context.getCmd().get(iii); std::string tmpppp = _context.getCmd().get(iii);
if ( tmpppp == "-h" if ( tmpppp == "-h"
|| tmpppp == "--help") { || tmpppp == "--help") {
@ -28,32 +66,28 @@ namespace appl {
exit(0); exit(0);
} }
} }
// TODO : Remove this : Move if in the windows properties //! [ewol_sample_HW_main_parse_arguments]
//! [ewol_sample_HW_main_set_windows_size]
// TODO : Remove this: Move if in the windows properties
_context.setSize(vec2(800, 600)); _context.setSize(vec2(800, 600));
//! [ewol_sample_HW_main_set_windows_size]
// select internal data for font ... //! [ewol_sample_HW_main_set_font_property]
// eneble the search of the font in the system font path
_context.getFontDefault().setUseExternal(true); _context.getFontDefault().setUseExternal(true);
// select font preference of der with a basic application size
_context.getFontDefault().set("FreeSerif;DejaVuSansMono", 19); _context.getFontDefault().set("FreeSerif;DejaVuSansMono", 19);
//! [ewol_sample_HW_main_set_font_property]
//! [ewol_sample_HW_main_set_windows]
// Create the windows
ewol::widget::WindowsShared basicWindows = appl::Windows::create(); ewol::widget::WindowsShared basicWindows = appl::Windows::create();
// create the specific windows // configure the ewol context to use the new windows
_context.setWindows(basicWindows); _context.setWindows(basicWindows);
APPL_INFO("==> CREATE ... " PROJECT_NAME " (END)"); //! [ewol_sample_HW_main_set_windows]
}
void onStart(ewol::Context& _context) override {
APPL_INFO("==> START ... " PROJECT_NAME " (BEGIN)");
// nothing to do ...
APPL_INFO("==> START ... " PROJECT_NAME " (END)");
}
void onStop(ewol::Context& _context) override {
APPL_INFO("==> STOP ... " PROJECT_NAME " (START)");
// nothing to do ...
APPL_INFO("==> STOP ... " PROJECT_NAME " (END)");
} }
}; };
} }
//! [ewol_sample_HW_main_main]
/** /**
* @brief Main of the program (This can be set in every case, but it is not used in Andoid...). * @brief Main of the program (This can be set in every case, but it is not used in Andoid...).
* @param std IO * @param std IO
@ -63,5 +97,7 @@ int main(int _argc, const char *_argv[]) {
// second possibility // second possibility
return ewol::run(new appl::MainApplication(), _argc, _argv); return ewol::run(new appl::MainApplication(), _argc, _argv);
} }
//! [ewol_sample_HW_main_main]
//! [ewol_sample_HW_main_all]

8
sample/HelloWord/appl/Windows.cpp
View File

@ -11,18 +11,26 @@
appl::Windows::Windows() { appl::Windows::Windows() {
addObjectType("appl::Windows"); addObjectType("appl::Windows");
//! [ewol_sample_HW_windows_title]
propertyTitle.setDirectCheck(std::string("sample ") + PROJECT_NAME); propertyTitle.setDirectCheck(std::string("sample ") + PROJECT_NAME);
//! [ewol_sample_HW_windows_title]
} }
void appl::Windows::init() { void appl::Windows::init() {
//! [ewol_sample_HW_windows_init]
ewol::widget::Windows::init(); ewol::widget::Windows::init();
//! [ewol_sample_HW_windows_init]
//! [ewol_sample_HW_windows_label]
ewol::widget::LabelShared tmpWidget = ewol::widget::Label::create(); ewol::widget::LabelShared tmpWidget = ewol::widget::Label::create();
if (tmpWidget == nullptr) { if (tmpWidget == nullptr) {
APPL_ERROR("Can not allocate widget ==> display might be in error"); APPL_ERROR("Can not allocate widget ==> display might be in error");
} else { } else {
tmpWidget->propertyValue.set("Hello <font color='blue'>World</font>"); tmpWidget->propertyValue.set("Hello <font color='blue'>World</font>");
tmpWidget->propertyExpand.set(bvec2(true,true)); tmpWidget->propertyExpand.set(bvec2(true,true));
// confidure the label as a windows sub-widget
setSubWidget(tmpWidget); setSubWidget(tmpWidget);
} }
//! [ewol_sample_HW_windows_label]
} }

3
sample/HelloWord/lutin_ewol-sample-HelloWord.py
View File

@ -41,6 +41,3 @@ def create(target, module_name):
my_module.add_path(tools.get_current_path(__file__)) my_module.add_path(tools.get_current_path(__file__))
return my_module return my_module