[DEV] start updating documentation
This commit is contained in:
parent
331acf2303
commit
87f4aedb95
2
build
2
build
@ -1 +1 @@
|
||||
Subproject commit 885a60f22ce3dfde99819d3471a86fdbd3836237
|
||||
Subproject commit 92c552fd59009e30388d9762b1c9e618193c8d16
|
||||
@ -5,7 +5,7 @@ __________________________________________________
|
||||
=== 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).
|
||||
EWOL is released under the BSD 3 clauses license (BSD v3), 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.
|
||||
|
||||
The main idea of EWOL is to create a complete abstraction of the platforms.
|
||||
@ -21,7 +21,7 @@ To use ewol you need to know only C++ language. It could be usefull to know:
|
||||
One of the important point to know in this framwork 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 BSD, and depend on some sub-library with small license restriction.
|
||||
:** 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
|
||||
|
||||
38
doc/index.bb
38
doc/index.bb
@ -7,10 +7,10 @@ EWOL, or Edn Widget OpenGl Layer, is a multi-platform library for creating graph
|
||||
===Where can I use it?===
|
||||
Everywhere! EWOL is cross-platform devolopped to support bases OS:
|
||||
: ** Linux (X11) (mouse)
|
||||
: ** Windows (mouse)
|
||||
: ** Windows (mouse) (not compile anymore ==> TODO)
|
||||
: ** MacOs (mouse)
|
||||
: ** Android (mouse + touch)
|
||||
: ** IOs (in-progress)
|
||||
: ** IOs (touch)
|
||||
|
||||
===What languages are supported?===
|
||||
EWOL is written in C++ and is not (for now) supported for other languages.
|
||||
@ -23,7 +23,7 @@ That allow you to use it for every program you want, including those developing
|
||||
[note]The static support is important for some platform like IOs, and this limit the external library use at some license like :
|
||||
:** BSD*
|
||||
:** MIT
|
||||
:** APPACHE
|
||||
:** APPACHE-2
|
||||
:** PNG
|
||||
:** ZLIB
|
||||
This exclude the classical extern library with licence:
|
||||
@ -31,33 +31,37 @@ This exclude the classical extern library with licence:
|
||||
:** GPL
|
||||
[/note]
|
||||
|
||||
==== License (BSD) ====
|
||||
Redistribution and use in source and binary forms, with or without
|
||||
modification, are permitted provided that the following conditions
|
||||
are met:
|
||||
==== License (APACHE 2) ====
|
||||
Copyright ewol Edouard DUPIN
|
||||
|
||||
:** Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
|
||||
:** Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
|
||||
:** The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
|
||||
==== Sub library: ====
|
||||
===== License: =====
|
||||
:** [b][lib[etk | e-tk]][/b] : BSD 3 clauses
|
||||
:** [b][lib[etk | e-tk]][/b] : APACHE-2
|
||||
::** [b][lib[linearmath | Linear-Math]][/b] : z-lib (subset of bullet lib)
|
||||
::** [b][lib[earchive | e-Archive]][/b] : BSD 3 clauses
|
||||
::** [b][lib[earchive | e-Archive]][/b] : APACHE-2
|
||||
:::** [b][lib[z | Z lib]][/b] : z-lib
|
||||
:** [b][lib[egami | e-gami]][/b] : BSD 3 clauses
|
||||
::** [b][lib[esvg | e-svg]][/b] : BSD 3 clauses
|
||||
:** [b][lib[egami | e-gami]][/b] : APACHE-2
|
||||
::** [b][lib[esvg | e-svg]][/b] : APACHE-2
|
||||
:::** [b][lib[agg | AGG]][/b] : BSD-like
|
||||
::** [b][lib[png | libPNG]][/b] : PNG
|
||||
:** [b][lib[portaudio | portaudio]][/b] : MIT
|
||||
:** [b][lib[ogg | ogg]][/b] : BSD-like
|
||||
:** [b][lib[freetype | Free-Type]][/b] : BSD-like
|
||||
:** [b][lib[ejson | e-json]][/b] : BSD 3 clauses
|
||||
:** [b][lib[exml | e-xml]][/b] : BSD 3 clauses
|
||||
:** [b][lib[ejson | e-json]][/b] : APACHE-2
|
||||
:** [b][lib[exml | e-xml]][/b] : APACHE-2
|
||||
|
||||
|
||||
==== Description : ====
|
||||
|
||||
@ -12,12 +12,15 @@ __________________________________________________
|
||||
|
||||
A generic Ewol application is manage by creating an [class[ewol::context::Application]] that is the basis of your application.
|
||||
|
||||
Due to the fact the ewol librairy is a multi-platform framework, then you need to think all you will do with only one
|
||||
application and only one windows displayable at the same time.
|
||||
Due to the fact the ewol library is a multi-platform framework, you will have many contraint like:
|
||||
:** One application at the same time
|
||||
:** One Windows displayable at the time
|
||||
:** Not a big CPU ...
|
||||
|
||||
Then we will create the application:
|
||||
|
||||
[code style=c++]
|
||||
namespace appl {
|
||||
class MainApplication : public ewol::context::Application {
|
||||
public:
|
||||
bool init(ewol::Context& _context, size_t _initId) {
|
||||
@ -32,42 +35,47 @@ Then we will create the application:
|
||||
APPL_INFO("==> Un-Init APPL (END)");
|
||||
}
|
||||
};
|
||||
};
|
||||
[/code]
|
||||
|
||||
The input [class[ewol::Context]] is the main system context.
|
||||
|
||||
[note]
|
||||
It is important to know that the system can call your application in parallele, the basic exemple of this is the Wallpaper on Android.
|
||||
It is important to know that the system can create your application multiple times, the basic exemple of this is the Wallpaper on Android.
|
||||
|
||||
What is done:
|
||||
** When selected, it create an intance and when it is apply Android create a new instance and remove the previous one...
|
||||
** 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]
|
||||
|
||||
In all program we need to have a main()
|
||||
|
||||
To be portable on Android, that have a java main the User might the Wrapper call the generic main() (please do not add other things in this main).
|
||||
To be portable on Android, the "main" in the java might call your main through the Android wrapper.
|
||||
|
||||
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 MainApplication(), _argc, _argv);
|
||||
return ewol::run(new appl::MainApplication(), _argc, _argv);
|
||||
}
|
||||
[/code]
|
||||
|
||||
|
||||
==== Some configuration are needed ====
|
||||
|
||||
In your application you can use many configuration,
|
||||
none of them are set in static for compilation and interface reason,
|
||||
then you will to set it on 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
|
||||
(never forger the compilator garbage collector is really very efficient).
|
||||
|
||||
|
||||
Select fonts:
|
||||
|
||||
[b]Select fonts:[/b]
|
||||
|
||||
This can be a problem when you design an application for some other operating system (OS),
|
||||
They do not have the same default font.
|
||||
|
||||
And 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)
|
||||
_context.getFontDefault().setUseExternal(true);
|
||||
@ -80,7 +88,7 @@ And we select an order to search the font names and the system basic size.
|
||||
|
||||
Create the main Windows:
|
||||
|
||||
For this point we will create a class that herited form the basic windows class:
|
||||
For this point we will create a class that herited form the basic [class[ewol::wiget::Windows]] class:
|
||||
|
||||
[b]Windows.h[/b]
|
||||
[code style=c++]
|
||||
@ -91,14 +99,28 @@ For this point we will create a class that herited form the basic windows class:
|
||||
|
||||
namespace appl {
|
||||
class Windows : public ewol::widget::Windows {
|
||||
public:
|
||||
protected:
|
||||
Windows(void);
|
||||
init()
|
||||
public:
|
||||
DECLARE_FACTORY(Windows);
|
||||
virtual ~Windows(void) {};
|
||||
};
|
||||
};
|
||||
#endif
|
||||
[/code]
|
||||
|
||||
At this point you will ask an important question : [b]Why we use this really bad "DECLARE_FACTORY" Macro ?[/b]
|
||||
|
||||
For some reason!!! But everything might be clear:
|
||||
:** In ewol we masively use std::shared_ptr<xxx> (I have create my own but it is not "standard" (I like when we use genecic system)).
|
||||
:** The main class : [class[ewol::Object]] herited from [i]std::enable_shared_from_this<Object>[/i] to permit to access at his own [i]std::shared_ptr[/i].
|
||||
:** Acces At his own [i]std::shared_ptr[/i] is not allowed in the class contructor/destructor.
|
||||
:** Many time for meta-widget we need to propagate our [i]std::shared_ptr[/i] in child.
|
||||
|
||||
Then for all these reasons, I have create a simple MACRO that create a static template funtion that create the object and just after
|
||||
creation call the init(...) function to permit to create a complex widget or others with some writing convinience.
|
||||
|
||||
[b]Windows.cpp[/b]
|
||||
[code style=c++]
|
||||
#include <ewol/ewol.h>
|
||||
@ -110,8 +132,13 @@ For this point we will create a class that herited form the basic windows class:
|
||||
#define __class__ "Windows"
|
||||
|
||||
appl::Windows::Windows(void) {
|
||||
// To simplify log (if you have a better solution, I am aware)
|
||||
addObjectType("appl::Windows");
|
||||
}
|
||||
appl::Windows::init(void) {
|
||||
ewol::widget::Windows::init();
|
||||
setTitle("example 001_HelloWord");
|
||||
ewol::object::Shared<ewol::widget::Label> tmpWidget = new ewol::widget::Label();
|
||||
std::shared_ptr<ewol::widget::Label> tmpWidget = ewol::widget::Label::create();
|
||||
if (NULL == tmpWidget) {
|
||||
APPL_ERROR("Can not allocate widget ==> display might be in error");
|
||||
} else {
|
||||
@ -122,6 +149,11 @@ For this point we will create a class that herited form the basic windows class:
|
||||
}
|
||||
[/code]
|
||||
|
||||
The init function can not be virtual due to his polymorphic status, then we need to call parrent init
|
||||
[code style=c++]
|
||||
ewol::widget::Windows::init();
|
||||
[/code]
|
||||
|
||||
The fist basic property to set is the Title:
|
||||
[code style=c++]
|
||||
setTitle("example 001_HelloWord");
|
||||
@ -130,14 +162,17 @@ The fist basic property to set is the Title:
|
||||
After we simple create a [class[widget::Label]] in the main windows constructor.
|
||||
And we set the widget property (label).
|
||||
[code style=c++]
|
||||
ewol::object::Shared<ewol::widget::Label> tmpWidget = ewol::object::makeShared(new ewol::widget::Label());
|
||||
tmpWidget->setLabel("Hello <font color=\"blue\">Word</font>");
|
||||
std::shared_ptr<ewol::widget::Label> tmpWidget = ewol::widget::Label::create();
|
||||
tmpWidget->setLabel("Hello <font color='blue'>Word</font>");
|
||||
tmpWidget->setExpand(bvec2(true,true));
|
||||
[/code]
|
||||
We can se in this example that the label have some other property like the font color.
|
||||
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 the availlable property is:
|
||||
I will take a really long time to create a real html parser.
|
||||
|
||||
The availlable property is:
|
||||
:** [b]<br/>[/b] : New line
|
||||
:** [b]<font color="#FF0000\"> ... </font>[/b] : change the font color.
|
||||
:** [b]<center> ... </center>[/b] : center the text.
|
||||
@ -156,6 +191,7 @@ 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 shard_from_this() function that create an exception if we are in constructor
|
||||
|
||||
|
||||
==== Configure Ewol to have display the windows ====
|
||||
@ -164,10 +200,12 @@ 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 contect main (in the MainApplication::init()):
|
||||
[code style=c++]
|
||||
ewol::object::Shared<ewol::Windows> basicWindows = ewol::object::makeShared(new appl::Windows());
|
||||
std::shared_ptr<ewol::Windows> basicWindows = appl::Windows::create());
|
||||
// create the specific windows
|
||||
_context.setWindows(basicWindows);
|
||||
[/code]
|
||||
Her we call the create function that is created by the DECLARE_FACTORY macro
|
||||
|
||||
|
||||
Then the init fuction is :
|
||||
[code style=c++]
|
||||
@ -177,7 +215,7 @@ bool MainApplication::init(ewol::Context& _context, size_t _initId) {
|
||||
_context.getFontDefault().setUseExternal(true);
|
||||
_context.getFontDefault().set("FreeSerif;DejaVuSansMono", 19);
|
||||
|
||||
ewol::Windows* basicWindows = new appl::Windows();
|
||||
std::shared_ptr<ewol::Windows> basicWindows = appl::Windows::create();
|
||||
// create the specific windows
|
||||
_context.setWindows(basicWindows);
|
||||
APPL_INFO("==> Init APPL (END)");
|
||||
@ -245,9 +283,9 @@ I do not explain again the lutin file, for next tutorial, show example sources .
|
||||
|
||||
=== Build your application ===
|
||||
|
||||
go to your workspace folder and launch
|
||||
Go to your workspace folder and launch
|
||||
[code style=shell]
|
||||
./ewol/build/lutin.py -C -mdebug -p 001_HelloWord
|
||||
./ewol/build/lutin.py -C -mdebug 001_HelloWord
|
||||
[/code]
|
||||
|
||||
Your program example will build correctly...
|
||||
@ -259,13 +297,14 @@ Launch it :
|
||||
|
||||
The [b]-l6[/b] is used to specify the Log level of the application display (this log is synchronous)
|
||||
|
||||
|
||||
The output compile in a separate folder depending on the compilation tool (gcc or clang)
|
||||
|
||||
|
||||
It create a complete final tree in the ./out/Linux/debug/staging/gcc/001_HelloWord/ folder
|
||||
|
||||
The final folder contain the package generated
|
||||
|
||||
tree of the output
|
||||
The final folder contain the package generated:
|
||||
:** out
|
||||
::** MacOs
|
||||
::** Android
|
||||
|
||||
2
monk
2
monk
@ -1 +1 @@
|
||||
Subproject commit eba3e4f97f618b607e0fc52794b2a72c7f6902e8
|
||||
Subproject commit 9b9a5d323787b13ab5b0f7de6d064e326e143426
|
||||
@ -63,6 +63,7 @@ namespace ewol {
|
||||
*/
|
||||
Object();
|
||||
void init();
|
||||
//! @previous
|
||||
void init(const std::string& _name);
|
||||
public:
|
||||
/**
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user