From e6cab1e0cb2fc64048e5fa11e96cc19cdb378a9d Mon Sep 17 00:00:00 2001 From: Edouard DUPIN Date: Fri, 16 Sep 2016 22:35:06 +0200 Subject: [PATCH] [DOC] update done for doxygen over doxy --- doc/001_bases.md | 53 ++- doc/build.md | 210 ++++++---- doc/codingStyle.md | 140 +++---- doc/mainpage.md | 101 ++--- doc/tutorial/001_HelloWord.md | 383 +++++++----------- doc/tutorial/010_ObjectModel.md | 89 ++-- doc/tutorial/011_ObjectConfig.md | 91 +++-- doc/tutorial/012_ObjectMessage.md | 64 +-- doc/tutorial/020_FileAccess.md | 105 ++--- doc/tutorial/021_Resources.md | 73 ++-- doc/tutorial/030_ConplexeXmlGui.md | 77 ++-- doc/tutorial/050_CreateCustomWidget.md | 45 +- doc/tutorial/051_AddWidgetCustumInXML.md | 55 ++- doc/tutorials.md | 18 + doxy_ewol.py | 4 + .../appl/widget/VectorDisplay.cpp | 5 + .../CustomWidgets/appl/widget/VectorDisplay.h | 8 +- sample/HelloWord/appl/Main.cpp | 76 +++- sample/HelloWord/appl/Windows.cpp | 8 + .../HelloWord/lutin_ewol-sample-HelloWord.py | 3 - 20 files changed, 864 insertions(+), 744 deletions(-) diff --git a/doc/001_bases.md b/doc/001_bases.md index 8204e1c1..304743c1 100644 --- a/doc/001_bases.md +++ b/doc/001_bases.md @@ -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. -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 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. 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: -- **Python** for all build tool. -- **git** and **repo** for all version management. -- **OpenGL-ES2** if you want to create custum advenced widget. + - **Python** for [lutin](http://HeeroYui.github.io/lutin) build tool. + - **git** and **repo** for all version management. + - **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: -- 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. -- 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 -- Only one graphyc framework is availlable on all platform. This is OpenGL (nned check for windows phone) -- Main interesting point is packaging of the application data: - * Linux store it in /usr/share/applName/* - * MacOs store it in applName.app/subFolder/* - * Android store it in the .pkg that is a renamed .zip that the name is dynamic - * Windows (TODO : Never done a pakage) - 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. + - 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 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 (windows phone is not supported (moribund archi)) + - Main interesting point is packaging of the application data: + * Linux store it in /usr/share/applName/* + * MacOs store it in applName.app/subFolder/* + * Android store it in the .pkg that is a renamed .zip that the name is dynamic + * Windows (TODO : Never done a pakage) + This will generate a complex result of data access... + - 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. diff --git a/doc/build.md b/doc/build.md index c7dad061..fd498d02 100644 --- a/doc/build.md +++ b/doc/build.md @@ -1,13 +1,14 @@ -=?=Ewol extract and build examples=?= -__________________________________________________ -[left][doc[001_bases | Previous: Doc]][/left] [right][tutorial[001_HelloWord | Next: Hello-Word]][/right] +Build lib & build sample {#ewol_build} +======================== -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 ==== -[code style=shell] +```{.sh} sudo apt-get install g++ libgl1-mesa-dev zlib1g-dev libasound2-dev # Compile with 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: sudo apt-get install ia32-libs sudo apt-get install g++-multilib libc6-dev-i386 -[/code] +``` -==== Arch-linux ==== -[code style=shell] +Arch-linux {#ewol_build_dependency_archlinux} +---------- +```{.sh} # Cross compile for windows: 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 # connect adb: (and you can do a "android/sdk/platform-tools/adb shell" to enable computer key on device) 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] - sudo pip install lutin - sudo pip install pillow -[/code] - -==== need google repo: ==== +need google repo: {#ewol_build_download_repo} +----------------- see: http://source.android.com/source/downloading.html#installing-repo -[code style=shell] +On all platform: +```{.sh} mkdir ~/.bin PATH=~/.bin:$PATH curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo chmod a+x ~/.bin/repo -[/code] -==== download the software: ==== +``` -[code style=shell] - mkdir WORKING_DIRECTORY - cd WORKING_DIRECTORY +On ubuntu +```{.sh} + 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 sync -j8 -[/code] + cd ../.. +``` -==== Compile software and test: ==== +sources: {#ewol_build_download_sources} +-------- -[code style=shell] - lutin ewol-* -[/code] +They are already download in the repo manifest in: -[note] -The full build tool documentation is availlable here : [[http://heeroyui.github.io/lutin/ | lutin]] -[/note] +```{.sh} + cd WORKING_DIRECTORY/framework/atria-soft/ewol +``` -=== Common build instructions === +Build: {#ewol_build_build} +====== -Compile software in debug for the curent platform : -[code style=shell] - lutin -mdebug -[/code] +you must stay in zour working directory... +```{.sh} + cd WORKING_DIRECTORY +``` -You can specify the platform with: -[code style=shell] - lutin -tAndroid -mdebug -[/code] +library: {#ewol_build_build_library} +-------- -It coud be usefull to disable the package generation in local debug: -[code style=shell] - lutin -mdebug -p -[/code] +```{.sh} + lutin -mdebug ewol +``` -Build with clang instead of gcc: -[code style=shell] - lutin -cclang -[/code] +Sample: {#ewol_build_build_sample} +------- -Display the build in color : -[code style=shell] - lutin -C -mdebug -p -[/code] +```{.sh} + lutin -mdebug ewol-sample-* +``` -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 -[code style=shell] - lutin -C ewol-sample-HelloWord?install - #or - lutin -C ewol-sample-HelloWord@install -[/code] +Run sample: {#ewol_build_run_sample} +----------- -To run an application you will find it directly on the out 'staging' tree or execute the command: -[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] +Basic way -== 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. It will create a tree like this : -:** workspace -::** application -:::** Application clone application area. -::** framework -:::** atria-soft -::::** Graphic interface -:::** generic-library -::::** common untuch library (just wrap in lutin mode) -:::** HeeroYui -::::** unstable stuff -:::** musicdsp -::::** Common library for audio interfacing -:::** tools + - **workspace** + * **application:** set your application here, it is a good position + * **framework:** framework download by repo + + **atria-soft:** graphic framework + + **generic-library:** open sources library that is wrapped on lutin builder + + **musicdsp:** Common library for audio interfacing + + **tools:** build tools (now only the IOs flasher) + * **out:** + + Android_arm_32 + + Android_arm_64 + + Windows_x86_32 + + Windows_x86_64 + + 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 + + diff --git a/doc/codingStyle.md b/doc/codingStyle.md index ec866a8c..e8b3bda4 100644 --- a/doc/codingStyle.md +++ b/doc/codingStyle.md @@ -1,51 +1,53 @@ Ewol coding style {#ewol_coding_style} ================= +@tableofcontents -Comments --------- + +Comments {#ewol_coding_style_comment} +======== - One line comment: (never in #define xxx ==> too dangerous) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} // -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - Multiple line comment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} /* * xxxx yyyy * zzzz */ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - Documentation : doxygen (do not set un-nneded field) - @verbatim - /** - * @brief my summery - * @param[in,out] _xxxx Comment on the variable - * @return my return explanation - */ - @endverbatim - +@verbatim +/** + * @brief my summery + * @param[in,out] _xxxx Comment on the variable + * @return my return explanation + */ +@endverbatim - one line documlentation: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} 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 -Indentation & braces --------------------- +Indentation & braces {#ewol_coding_style_indent} +==================== + 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, 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) - if: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} if ( xxx == yyy - && xxx == kkk) { - your action ...; + && ( xxx == kkk + || xxx == zzz )) { + //your action ...; } -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - switch: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} switch (suffix) { case 'G': case 'g': @@ -79,17 +82,17 @@ To be simple : (tab stop at the 'if' start) default: break; } -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - function: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} void myFunction(void) { actions ...; } -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - classes: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} class MyClass { public: MyClass(void); @@ -97,36 +100,36 @@ To be simple : (tab stop at the 'if' start) private: const char* getName(void); }; -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - namespace: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} namespace appl { void get(void); } -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - For special element like : you might add a tabulation too -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} case xxx: actions... public: definition ... -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - An exception for the inline function inside c++ header: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} class Plop { private: int32_t m_value; //!< my value of money gain public: 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 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 : -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} void* myVariableName; -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` -C and c++ ---------- +C and c++ {#ewol_coding_style_c_and_cpp} +========= All C header files might have : -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} #ifdef __cplusplus extern "C" { #endif @@ -159,71 +162,72 @@ All C header files might have : #ifdef __cplusplus } #endif -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` -Naming ------- +Naming {#ewol_coding_style_naming} +====== - Fonction/Methods: Camel case with first letter in lower case. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} void myExampleFontionName(void); -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - Variable: Camel case with first letter in lower case. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} nt32_t myVariableExample; -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - namespace: one world in lower case -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} namspace ewol { -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - Class: Camel case with first letter in upper case. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} class MyClass; -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - Members fields: Put a 'm' prefix and then a normal Variable name -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} int32_t m_memberField; -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - enum: Camel case with first letter in lower case. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} enum myEnum { myEnum_def1, myEnum_def2, myEnum_def3, }; -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` - structure (C only) use naming like Classes (and for mamber too) - minimum size : Do not use variable with size <3, the for a iterator for a 'for' : -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} +```{.cpp} for (int32_t iii=0; iii 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] +First things: Some includes: -The input [class[ewol::Context]] is the main system context. +@snippet HelloWord/appl/Main.cpp ewol_sample_HW_main_include -[note] -It is important to know that the system can create your application multiple times, the basic exemple of this is the Wallpaper on Android. +Declare the application: + +@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: -** 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. -[/note] + - 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. +``` 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: -[code style=c++] - int main(int argc, const char *argv[]) { - // only one things to do : - return ewol::run(new appl::MainApplication(), _argc, _argv); - } -[/code] +@snippet HelloWord/appl/Main.cpp ewol_sample_HW_main_main -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. -With this basic condiction will simplify the interface of the library if you would have many different application -(never forger the compilator garbage collector is really very efficient). +With this basic condition will simplify the interface of the library if you would have many different application +(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 - -[b]Select fonts:[/b] +### Select fonts: #### 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. -[code style=c++] - // Use External font depending on the system (for specific application, it is better to provide fonts) - _context.getFontDefault().setUseExternal(true); - // Select font in order you want : if Ewol find FreeSerif, it selected it ... - _context.getFontDefault().set("FreeSerif;DejaVuSansMono", 19); -[/code] + +@snippet HelloWord/appl/Main.cpp ewol_sample_HW_main_set_font_property -Main Windows: -============= +Main Windows: {#ewol_tutorial_hello_world_sources_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] -[code style=c++] - #pragma once - #include - namespace appl { - class Windows; - using WindowsShared = ememory::SharedPtr; - using WindowsWeak = ememory::WeakPtr; - class Windows : public ewol::widget::Windows { - protected: - Windows(void); - init(); - public: - DECLARE_FACTORY(Windows); - virtual ~Windows(void) {}; - }; - }; -[/code] +@include HelloWord/appl/Windows.h -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. -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] -[code style=c++] - #include - #include - #include - #include - - 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 World"); - tmpWidget->propertyExpand.set(bvec2(true,true)); - setSubWidget(tmpWidget); - } - } -[/code] +@include HelloWord/appl/Windows.cpp -The init function is virtual and you must call your parent object (or at least the [class[ewol::Object]] init) -[code style=c++] - ewol::widget::Windows::init(); -[/code] +The init function is virtual and you must call your parent object (or at least the ewol::Object::init) -The title is assiciated on the current windows then it is a simple [class[ewol::widget::Windows]] property. -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] +@snippet HelloWord/appl/Windows.cpp ewol_sample_HW_windows_init -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: -[code style=c++] - std::shared_ptr tmpWidget = ewol::widget::Label::create(); - tmpWidget->propertyValue.set("Hello World"); - 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. I will take a really long time to create a real html parser. The availlable property is: -:** [b]
[/b] : New line -:** [b] ... [/b] : change the font color. -:** [b]
...
[/b] : center the text. -:** [b] ... [/b] : Set the text on the left. -:** [b] ... [/b] : Set the text on the right. -:** [b] ... [/b] : Set the text mode in justify. + - ```
``` : New line + - ``` ... ``` : change the font color. + - ```
...
``` : center the text. + - ``` ... ``` : Set the text on the left. + - ``` ... ``` : Set the text on the right. + - ``` ... ``` : Set the text mode in justify. -[note] +**Note:** + +``` The xml parser is a little strict on the case and end node (!!
!!), but it support to: -:** Not have a main node. -:** 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) + - Not have a main node. + - replace '"' with ''' to simplify xml writing in C code. +``` -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 -Then the init fuction is: -[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:** -[note] +``` 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] -#!/usr/bin/python -import lutin.module as module -import lutin.tools as tools +Show [lutin](http://HeeroYui.github.io/lutin/lutin_module.html) doc for more information... -def get_type(): - 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 "] - -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 +Build your application {#ewol_tutorial_hello_world_buildappl} ====================== -Go to your workspace folder and launch -[code style=shell] +Go to your workspace folder and launch: + +```{.sh} lutin -C -mdebug ewol-sample-HelloWord # or lutin -C -mdebug ewol-sample-HelloWord?build -[/code] +``` -Your program example will build correctly... +You can now execute your application: -Launch it : -[code style=shell] +```{.sh} lutin -C -mdebug ewol-sample-HelloWord?run -[/code] +``` diff --git a/doc/tutorial/010_ObjectModel.md b/doc/tutorial/010_ObjectModel.md index 2b1ed344..d90039ff 100644 --- a/doc/tutorial/010_ObjectModel.md +++ b/doc/tutorial/010_ObjectModel.md @@ -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]] -:** Use [class[ewol::Object]] correctly + - Understand ewol basic ewol::Object + - 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: -:** Unique ID -:** Name -:** Parameters -:** Signal generation -:** Xml configuration -:** Removing + - Unique ID + - Name + - Parameters + - Signal generation + - Xml configuration + - Removing -[note] +**Note:** + +``` 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: -[code style=c++] +```{.cpp} 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() << "'"); -[/code] +``` -Note that all object created are [class[ememory::SharedPtr]] base for the current version on [class[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. +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 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 but in a ewol::widget::ButtonShared to simplify the using of the pointer. You have also: ememory::WeakPtr = ewol::widget::ButtonWeak -[/note] +``` Set the name of the object: -[code style=c++] +```{.cpp} tmpButon->propertyName.set("my widget name"); 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: -[code style=c++] +```{.cpp} tmpButon->destroy(); -[/code] +``` -This function request his parrent to remove the [class[ememory::SharedPtr]] it keep on it. -And when all std::shared_ptr is removed the object will be really removed. +This function request his parrent to remove the ememory::SharedPtr it keep on it. +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. -[/note] +``` -Retrieve an Object: +Retrieve an Object: {#ewol_tutorial_object_model_find} =================== 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) --------------------------------------- -[code style=c++] +```{.cpp} #include ewol::ObjectShared tmpObject = ewol::getContext().getEObjectManager().getObjectNamed("obj Name"); if (tmpObject == nullptr) { APPL_ERROR("The Object does not exist"); } -[/code] +``` Find a global Object (inside an Object) --------------------------------------- -[code style=c++] +```{.cpp} ewol::ObjectShared tmpObject = getObjectNamed("obj Name"); if (tmpObject == nullptr) { APPL_ERROR("The Object does not exist"); } -[/code] +``` Find a sub-object ----------------- -[code style=c++] +```{.cpp} ewol::ObjectShared tmpObject = getSubObjectNamed("obj Name"); if (tmpObject == NULL) { APPL_ERROR("The Object does not exist"); } -[/code] +``` retriving your object type -------------------------- It could be really interesting to retrive your own instance: -[code style=c++] +```{.cpp} ewol::ObjectShared tmpObject ...; appl::MyOwnObjectShared myObject = std::dynamic_pointer_cast(tmpObject); -[/code] +``` diff --git a/doc/tutorial/011_ObjectConfig.md b/doc/tutorial/011_ObjectConfig.md index 718ef346..711c974d 100644 --- a/doc/tutorial/011_ObjectConfig.md +++ b/doc/tutorial/011_ObjectConfig.md @@ -1,52 +1,59 @@ - -Objectifs: -========== - -:** Understand base of [lib[eproperty]] configuration parameter -:** Create an configurable object - -Configuration using +EWOL: Object config {#ewol_tutorial_object_config} =================== -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] - Parameter is managed by the [lib[eproperty|e-property library]] -[/note] +**Note:** + +``` + Parameter is managed by the [e-property](http://atria-soft.github.io/eproperty) +``` With a string configuration *************************** -[code style=c++] - if (tmpObject->parameterSet("name", "new name of object") == false) { +```{.cpp} + if (tmpObject->properties.set("name", "new name of object") == false) { APPL_ERROR("Can not set object parameter"); } -[/code] +``` whith the object name ********************* -[code style=c++] - if (parameterSetOnWidgetNamed("objectName", "value", "16.2") == false) { +```{.cpp} + if (ewol::propertySetOnObjectNamed("objectName", "value", "16.2") == false) { APPL_ERROR("Can not set object parameter"); } -[/code] +``` -Get Parameter +Get Parameter {#ewol_tutorial_object_config_param} ------------- -[code style=c++] - std::string val = tmpObject->parameterGet("name"); - APPL_INFO("Get Object property : name='" << val << "'"); -[/code] +```{.cpp} + std::string val = tmpObject->properties.get("name"); + APPL_INFO("Get Object property: name='" << val << "'"); +``` -Implement configuration +Implement configuration {#ewol_tutorial_object_config_impl} ======================= -[code style=c++] +```{.cpp} #include namespace appl { class MyObj : public ewol::Object { @@ -75,25 +82,29 @@ namespace appl { } } } -[/code] +``` In the contructor we need to add: -[code style=c++] -m_value(*this, "value", false, "Value of the parameter (descrition string)") -[/code] -:** [b]'this':[/b] Pointer the main class to call it chen value change. -:** [b]"value":[/b] Is the name of the parameter. -:** [b]false:[/b] The default value. -:** [b]"....."[/b] Description of the parameter (optionnal). -:** [b]&appl::MyObj::onChangeParameterValue[/b] The callback when the value change (optionnal). +```{.cpp} +propertyValue(this, + "value", + false, + "Value of the parameter (descrition string)", + &appl::MyObj::onChangeParameterValue) +``` + - **'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 : -:** eproperty::Value Basic parameter. -:** eproperty::Range For numeric parameter that range value are check befor setting new value. -:** eproperty::List For List of parameter values. + - eproperty::Value Basic parameter. + - eproperty::Range For numeric parameter that range value are check befor setting new value. + - eproperty::List For List of parameter values. -For more information see [lib[eproperty]] +For more information see [e-property](http://atria-soft.github.io/eproperty) diff --git a/doc/tutorial/012_ObjectMessage.md b/doc/tutorial/012_ObjectMessage.md index 86c485f5..1e105b5e 100644 --- a/doc/tutorial/012_ObjectMessage.md +++ b/doc/tutorial/012_ObjectMessage.md @@ -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 -:** Create extern message and receive Object message + - Understand base of [e-signal](http://atria-soft.github.io/esignal) Messaging system + - Create extern message and receive Object message -Message system +Message system {#ewol_tutorial_object_message_system} ============== 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: Button header : -[code style=c++] +```{.cpp} ... public: - esignal::ISignal<> signalDown; - esignal::ISignal<> signalUp; + esignal::Signal<> signalDown; + esignal::Signal<> signalUp; ... - esignal::ISignal signalValue; + esignal::Signal signalValue; ... -[/code] +``` simple signal connection: ------------------------- -[code style=c++] +```{.cpp} #include #include namespace appl { @@ -49,15 +53,15 @@ namespace appl { } void init() { ewol::Object::init(); - m_button = ewol::widget::Button::Create(); + m_button = ewol::widget::Button::create(); if (m_button == nullptr) { APPL_ERROR("Can not create button..."); return; } - m_button.propertyToggle.set(true); + m_button->propertyToggle.set(true); // We connect signals here: (permanent connection) - m_button->signalUp.connect(shared_from_this(), &appl::MyObj::onCallbackUp); - m_button->signalValue.connect(shared_from_this(), &appl::MyObj::onCallbackValue); + m_button->signalUp.connect(sharedFromThis(), &appl::MyObj::onCallbackUp); + m_button->signalValue.connect(sharedFromThis(), &appl::MyObj::onCallbackValue); } public: //! @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. -[/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] +**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 ------- -[code style=c++] +```{.cpp} #include #include 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... -For more information see [lib[esignal]] +For more information see [e-signal](http://atria-soft.github.io/esignal) diff --git a/doc/tutorial/020_FileAccess.md b/doc/tutorial/020_FileAccess.md index c373892c..f3b650d0 100644 --- a/doc/tutorial/020_FileAccess.md +++ b/doc/tutorial/020_FileAccess.md @@ -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 + - read and write files -Limitation +Limitation {#ewol_tutorial_file_access_limit} ========== Application generation is really simple, but package management can create some problems... 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. -:** 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. -:** ... + - 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/ + - 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) -Generic Properties +Generic Properties {#ewol_tutorial_file_access_property} ================== By default we dertermine some basics for files. Then we need to determine file in the tree with: -:** "DATA:XXX" Application internal data -::** Linux: /usr/share/applName/ -::** Android: /xxx/yyy/applName.apk/asssets/ -::** IOs: applName.app/share -::** MacOs: applName.app/Resources -:** "USERDATA:XXX" User save data (like game save) -::** Linux: ~/.local/share/applName/ -::** Android: /xxx/yyy/data/applName/ -:** "HOME:XXX" User home folder -::** Linux: ~/ -::** Android: /sdcard/ -::** IOs: --- => no Home -::** MacOs: ~/ -:** "/XXX" Direct acces on a file in the fileSystem -:** ... + - **"DATA:XXX"** Application internal data + * Linux: /usr/share/applName/ + * Android: /xxx/yyy/applName.apk/asssets/ + * IOs: applName.app/share + * MacOs: applName.app/Resources + - **"USERDATA:XXX"** User save data (like game save) + * Linux: ~/.local/share/applName/ + * Android: /xxx/yyy/data/applName/ + - **"HOME:XXX"** User home folder + * Linux: ~/ + * Android: /sdcard/ + * IOs: --- => no Home + * MacOs: ~/ + - **"/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. 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: -[code style=python] +In your ```lutin_xxx.py``` file add: + +```{.py} # 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 - myModule.copy_folder("relative/path/start*.png","destination/folder/") -[/code] + myModule.copy_path("relative/path/start*.png","destination/folder/") +``` -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 ... @@ -84,12 +91,12 @@ Read a file 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) file.fileClose(); -[/code] +``` -Write a file +Write a file {#ewol_tutorial_file_access_write} ============ -[code style=c++] +```{.cpp} #include ... @@ -106,42 +113,44 @@ Write a file 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) 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. -For example The basic theme of an API can be manage with only 2 commands (set the theme, and request upate of GUI) +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) 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_SHAPE", "theme/rounded"); -[/code] +``` And when you want to change the theme, just call: -[code style=c++] +```{.cpp} // change the theme : etk::theme::setName("GUI_COLOR", "theme/white"); // force reload of all the resources : ewol::getContext().getResourcesManager().reLoadResources(); ewol::getContext().forceRedrawAll(); -[/code] +``` -[note] +**Note:** + +``` 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" An important think is that the theme file is searching in many path in the order: -:** USERDATA:GUI_COLOR:your/sub/path/file.xx -:** DATA:GUI_COLOR:your/sub/path/file.xx -:** USERDATA:GUI_COLOR(default):your/sub/path/file.xx -:** DATA:GUI_COLOR(default):your/sub/path/file.xx + - USERDATA:GUI_COLOR:your/sub/path/file.xx + - DATA:GUI_COLOR:your/sub/path/file.xx + - USERDATA: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... diff --git a/doc/tutorial/021_Resources.md b/doc/tutorial/021_Resources.md index e7e0d424..dd476fca 100644 --- a/doc/tutorial/021_Resources.md +++ b/doc/tutorial/021_Resources.md @@ -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: -:** An image (special resolution) -:** A configuration file -:** An application manager (special case) -:** A sound file -:** ... + - An image (special resolution) + - A configuration file + - An application manager (special case) + - 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... 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: -[code style=c++] +```{.cpp} #include #include namespace appl { @@ -29,7 +34,7 @@ namespace appl { public: eproperty::Value propertyConfig; private: - std::shared_ptr m_config; + ememory::SharedPtr m_config; int32_t m_configValId; protected: //! @brief Constructor @@ -47,7 +52,7 @@ namespace appl { } public: //! @brief Destructor - virtual ~MyObj(void) { } + virtual ~MyObj() { } DECLARE_FACTORY(MyObj); public: 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: -:** 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_SINGLE_FACTORY(className,uniqueName) This is to have a unique resource for all the application (name is specify in the Macro) +A resource is a generic gale::Resource: + - 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_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): -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]) @@ -84,7 +89,7 @@ The resources are loaded fron 0 to 5. Then for basic resource: -[code style=c++] +```{.cpp} #include namespace appl { class MyResource : public gale::Resource { @@ -93,38 +98,38 @@ namespace appl { MyResource() : m_configValId(-1) { m_resourceLevel = 4; - addObjectType("ewol::MyResource"); + addObjectType("appl::MyResource"); } - void init(const std::& _name) { + void init(const std::string& _name) { ewol::Resource::init(_name); } public: //! @brief Destructor - virtual ~MyResource(void) { } + virtual ~MyResource() { } DECLARE_RESOURCE_NAMED_FACTORY(MyResource); } } -[/code] +``` Now we need to implement somme functions: To send data on the hardware (openGL): -[code style=c++] +```{.cpp} void updateContext(); -[/code] +``` To remove data from the the hardware (openGL): -[code style=c++] +```{.cpp} void removeContext(); -[/code] +``` -When loose hardware (juste update internal state): -[code style=c++] +When loose hardware (juste update internal state the hardware is no more present): +```{.cpp} void removeContextToLate(); -[/code] +``` When user request to reload all resources (can be usefull when using file type : THEME:GUI:xxx) -[code style=c++] +```{.cpp} void reload(); -[/code] +``` diff --git a/doc/tutorial/030_ConplexeXmlGui.md b/doc/tutorial/030_ConplexeXmlGui.md index 9c8f1b9c..3aa8ca82 100644 --- a/doc/tutorial/030_ConplexeXmlGui.md +++ b/doc/tutorial/030_ConplexeXmlGui.md @@ -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 -:** Simply create a complex Gui + - What is a Widget + - 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: -:** Windows: Main gui interface to display the unique "windows". -:** Container Widget: Widget that manage some subWidget (generic) -:** Simple widget: all widget that display somthing. -:** Meta widget: Widget composed with some wodget. + - ewol::Windows: Main gui interface to display the unique "windows". + - Container Widget: Widget that manage some subWidget (generic) + - Simple widget: all widget that display somthing. + - 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: + call create and configure ------------------------- First create the widget: -[code style=c++] +```{.cpp} ewol::widget::ButtonShared tmpWidget = ewol::widget::Button::create(); if (tmpWidget == nullptr) { APPL_CRITICAL("The widget can not be created"); } -[/code] +``` Set some parameters: -[code style=c++] +```{.cpp} tmpWidget->propertyName.set("my name"); tmpWidget->propertyExpand.set(bvec2(true,false)); 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. -[/note] +``` -==== Call create and direct configuration ==== +Call create and direct configuration +------------------------------------ We can configure the wiget before the init() is called. -[code style=c++] +```{.cpp} ewol::widget::ButtonShared tmpWidget = ewol::widget::Button::create( "name", std::string("my name"), "expand", bvec2(true,false), @@ -55,46 +63,53 @@ We can configure the wiget before the init() is called. if (tmpWidget == nullptr) { 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. -[/note] +``` -==== Call generic factory system (compositing) ==== +Call generic factory system (compositing) +----------------------------------------- -[code style=c++] +```{.cpp} #include ewol::widget::WidgetShared tmpWidget = ewol::widget::composerGenerateString("