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

[DEV] update documantation

Browse Source
This commit is contained in:
Edouard DUPIN 2013-12-10 21:40:43 +01:00
parent 74554809c9
commit 5c295fcca9
5 changed files with 255 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
build

@ -1 +1 @@
Subproject commit 47b884d9b2e3285878988ac99496c7c6a26fdceb
Subproject commit b02c8b5221d94dd8446319ea224ff25f801a2924

33
doc/001_bases.bb
View File

@ -1,16 +1,35 @@
== [center]EWOL: Bases[/center] ==
=?=EWOL: Bases =?=
__________________________________________________
[right][tutorial[000_Build | Next: Tutorals]][/right]
=== 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 has a C++ architecture that allows for maximum flexibility.
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:===
To use ewol you need to know only C++ language. It could be usefull to know:
:** [b]Python[/b] for all build tool.
:** [b]git[/b] for all version management
:** [b]OpenGL-ES2[/b] if you want to create custum advenced widget.
Basicly this library is designed to be platform abstract and work on all classicle platform :
: ** Linux (X11)
: ** Windows
: ** MacOs
: ** Andoid
: ** IOs
=== Architecture:===
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.
:** 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
:** 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.

59
doc/index.bb
View File

@ -1,24 +1,37 @@
== [center]Ewol library[/center] ==
__________________________________________________
===What is EWOL, and how can I use it?===
EWOL, or Edn Widget OpenGl Layer, is a multi-platform library for creating graphical user interfaces in OpenGL. Offering a complete set of widgets.
`Ewol` (Edn Widget OpenGl Layer) is a [b]FREE software[/b]. [i]All sub-library are FREE and staticly linkable !!![/i]
Ewol is a graphycal renderer with classical graphycs think. The main idea is to developpe a library compatible natively on:
: ** Linux (X11)
: ** Windows
: ** MacOs
: ** Andoid
===Where can I use it?===
Everywhere! EWOL is cross-platform devolopped to support bases OS:
: ** Linux (X11) (mouse)
: ** Windows (mouse)
: ** MacOs (mouse)
: ** Android (mouse + touch)
: ** IOs (in-progress)
===What languages are supported?===
EWOL is written in C++ and is not (for now) supported for other languages.
=== Copyright (c) ===
2011, Edouard DUPIN
===Are there any licensing restrictions?===
EWOL is [b]FREE software[/b] and [i]all sub-library are FREE and staticly linkable !!![/i]
That allow you to use it for every program you want, including those developing proprietary software, without any license fees or royalties.
=== License (DSB) ===
[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
:** PNG
:** ZLIB
This exclude the classical extern library with licence:
:** L-GPL
:** GPL
[/note]
==== License (DSB) ====
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
@ -30,8 +43,8 @@ are met:
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.
== Sub library: ==
=== License: ===
==== Sub library: ====
===== License: =====
:** [b][lib[etk | e-tk]][/b] : BSD 3 clauses
::** [b][lib[linearmath | Linear-Math]][/b] : z-lib (subset of bullet lib)
::** [b][lib[earchive | e-Archive]][/b] : BSD 3 clauses
@ -42,21 +55,22 @@ THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRA
::** [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[freetype | Free-Type]][/b] : BSD-like
:** [b][lib[ejson | e-json]][/b] : BSD 3 clauses
:** [b][lib[exml | e-xml]][/b] : BSD 3 clauses
=== Description : ===
==== Internal: ====
==== Description : ====
===== Internal: =====
:** [b][lib[etk | e-tk]][/b] : Generic toolkit to acces on file, standardize acces on string (for Android and MacOs) ...
:** [b][lib[earchive | e-Archive]][/b] : Generic access to a zip file (used to access on file on Android)
:** [b][lib[eggami | e-gami]][/b] : generic image accessor for PNG, svg and bmp image (might add some other type ...)
:** [b][lib[esvg | e-svg]][/b] : Generic SVG image parser and displayer
:** [b][lib[ejson | e-json]][/b] : JSON file access (read and write)
:** [b][lib[exml | e-xml]][/b] : XML file access (read and write)
:** [b][lib[ege | e-ge]][/b] : (library in BSDv3) 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)
==== External: ====
===== External: =====
:** [b][lib[linearmath | Linear-Math]][/b] : bullet mathamatical sub lib (for using same vec3).
:** [b][lib[z | Z lib]][/b] : Clkassical zlib lib.
:** [b][lib[agg | AGG]][/b] : A c++ drawing lib.
@ -64,10 +78,13 @@ THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRA
:** [b][lib[portaudio | portaudio]][/b] : The classical audio wrapper lib.
:** [b][lib[ogg | ogg]][/b] : The classical Ogg coder reader lib.
:** [b][lib[freetype | Free-Type]][/b] : The classicle true-type reader lib.
:** [b][lib[bullet | bullet]][/b] : the classical bullet library physical engine. (dependence by ege)
==== Other workspace working library and programs ====
===== Program Using EWOL =====
:** [b][lib[edn | edn]][/b] : (Application in GPLv3) Edn is the main application using this lib and designed for (in the first time). This is a "Code editor".
:** [b][lib[ege | e-ge]][/b] : (library in BSDv3) 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)
:** [b][lib[bullet | bullet]][/b] : the classical bullet library physical engine.
== Main documentation: ==
[doc[001_bases | Global Documantation]]
[tutorial[000_Build | Tutorials]]

28
doc/tutorial/000_Build.bb
View File

@ -1,6 +1,8 @@
== [center]Ewol extract and build examples[/center] ==
=?=Ewol extract and build examples=?=
__________________________________________________
[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.
=== Linux dependency packages ===
[code style=shell]
@ -74,5 +76,29 @@ To run an application you will find it directly on the out 'staging' tree :
./out/Linux/debug/staging/clang/edn/usr/bin/edn
[/code]
== Simple explanation : ==
The workspace is a simple folder that contain all the modules ans sub module.
It will create a tree like this :
:** workspace
::** ewol
:::** external [i](ewol external dependency sub-lib)[/i]
::::** agg
::::** bullet
::::** date
::::** egami
::::** ege
::::** ejson
::::** etk
::::** exml
::::** freetype
::::** glew
::::** lua
::::** ogg
::::** png
::::** portaudio
::::** z
:::** souces
::::** ewol
::** example

187
doc/tutorial/001_HelloWord.bb
View File

@ -1,35 +1,174 @@
== [center]Tutorial 1: Hello Word[/center] ==
=?= Tutorial 1: Hello Word =?=
__________________________________________________
[left][tutorial[000_Build | Previous: Download & Build]][/left] [right][tutorial[002_HelloWord | Next: Hello Word]][/right]
=== Objectif ===
:** Understand basis of ewol
:** Create a simple windows with a label "Hello Word"
=== Application Sources: ===
==== Main Windows: ====
==== Application "main()": ====
=== Build declaration: ===
=== Build your application ===
In all the application we need to have a main, for some reason this main is stored by the application and only call the EWOL main:
=== Instructions ===
download the software :
[code style=shell]
git clone git://github.com/HeeroYui/ewol.git
cd ewol
git submodule init
git submodule update
[code style=c++]
int main(int argc, const char *argv[]) {
// only one things to do :
return ewol::run(argc, argv);
}
[/code]
Then the first question, is where is the input of the application:
[code style=c++]
// application start:
bool APP_Init(ewol::eContext& _context) {
return true;
}
// application stop:
void APP_UnInit(ewol::eContext& _context) {
}
[/code]
The input [class[ewol::eContext]] is the main application context.
All the application globals have a reference in this element.
It is important to note that the system can call you some time in parallele, the basic exemple of this is the Wallpaper on Android.
When selected, it create an intance and when it is apply Android create a new instance and remove the previous one...
Now we will create some generic property:
In first: set the font availlagle on the global font property (system font).
This can be a problem when you designe 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.
[code style=c++]
_context.getFontDefault().setUseExternal(true);
_context.getFontDefault().set("FreeSerif;DejaVuSansMono", 19);
[/code]
Compile software and install :
[code style=shell]
For this you might use a project that create binaries or something else ...
Show http://github.com/HeeroYui/edn project
In second: we will create a windows.
For this point we will create a class that herited form the basic windows class:
[b]Windows.h[/b]
[code style=c++]
#ifndef __APPL_WINDOWS_H__
#define __APPL_WINDOWS_H__
#include <ewol/widget/Windows.h>
namespace appl {
class Windows : public ewol::Windows {
public:
Windows(void);
public:
};
};
#endif
[/code]
[b]Windows.cpp[/b]
[code style=c++]
#include <ewol/ewol.h>
#include <appl/debug.h>
#include <appl/Windows.h>
#include <ewol/widget/Label.h>
#undef __class__
#define __class__ "Windows"
appl::Windows::Windows(void) {
setTitle("example 001_HelloWord");
widget::Label* tmpWidget = new widget::Label();
if (NULL == tmpWidget) {
APPL_ERROR("Can not allocate widget ==> display might be in error");
} else {
tmpWidget->setLabel("Hello <font color=\"blue\">Word</font>");
tmpWidget->setExpand(bvec2(true,true));
setSubWidget(tmpWidget);
}
}
[/code]
The fist basic property to set is the Title:
[code style=c++]
setTitle("example 001_HelloWord");
[/code]
After we simple create a [class[widget::Label]] in the main windows constructor.
And we set the widget property (label).
[code style=c++]
widget::Label* tmpWidget = new widget::Label();
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.
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:
:** [b]<br/>[/b] : New line
:** [b]<font color="#FF0000\"> ... </font>[/b] : change the font color.
:** [b]<center> ... </center>[/b] : center the text.
:** [b]<left> ... </left>[/b] : Set the text on the left.
:** [b]<right> ... </right>[/b] : Set the text on the right.
:** [b]<justify> ... </justify>[/b] : Set the text mode in justify.
[note] The xml parser is a little strict on the case and end node, but it support to not have a main node.[/note]
The last step is to add the widget on the windows :
[code style=c++]
setSubWidget(tmpWidget);
[/code]
=== Dependency packages ===
[code style=shell]
sudo apt-get install g++ libgl1-mesa-dev zlib1g-dev libasound2-dev
# if you want to compile with clang :
sudo apt-get install clang
# For andoid compilation (jdk 7 does not work...)
sudo apt-get install javacc openjdk-6-jdk
# if you want to compile for windows :
sudo apt-get install mingw32
# on 64 bits processor for compatibility
sudo apt-get install ia32-libs
[/code]
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 APPL_init()):
[code style=c++]
ewol::Windows* basicWindows = new appl::Windows();
// create the specific windows
_context.setWindows(basicWindows);
[/code]
Then the init fuction is :
[code style=c++]
bool APP_Init(ewol::eContext& _context) {
// select internal data for font ...
_context.getFontDefault().setUseExternal(true);
_context.getFontDefault().set("FreeSerif;DejaVuSansMono", 19);
ewol::Windows* basicWindows = new appl::Windows();
// create the specific windows
_context.setWindows(basicWindows);
return true;
}
[/code]
To un-init the application, the context call a generic function [b]APP_UnInit[/b].
In this function we just need to remove the windows and un-init all needed by the system.
[code style=c++]
void APP_UnInit(ewol::eContext& _context) {
// Remove windows :
ewol::Windows* basicWindows = _context.getWindows();
if (NULL != basicWindows) {
delete(basicWindows);
basicWindows = NULL;
}
_context.setWindows(NULL);
}
[/code]