summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorYakov Goldberg <yakov.g@samsung.com>2014-12-24 15:00:30 +0200
committerYakov Goldberg <yakov.g@samsung.com>2015-01-07 15:21:41 +0200
commit99ae9f22153166f9a51e713aeb557aa10edc56b1 (patch)
treecaf459639a477c61e1ee9561bbe05c33834fbf14
parenta7d59548a5428fad9c8d1d83b94490d9aa3f4709 (diff)
Documentationdevelop
-rw-r--r--AUTHORS2
-rw-r--r--COPYING25
-rw-r--r--README482
3 files changed, 265 insertions, 244 deletions
diff --git a/AUTHORS b/AUTHORS
new file mode 100644
index 0000000..de81c97
--- /dev/null
+++ b/AUTHORS
@@ -0,0 +1,2 @@
1Yakov Goldberg <yakov.goldberg@gmail.com>
2Daniel Zaoui <daniel.zaoui@yahoo.com>
diff --git a/COPYING b/COPYING
new file mode 100644
index 0000000..981ed1f
--- /dev/null
+++ b/COPYING
@@ -0,0 +1,25 @@
1Copyright notice for Erigo:
2
3Copyright (C) 2013-2015 Yakov Goldberg and various contributors (see AUTHORS)
4
5All rights reserved.
6
7Redistribution and use in source and binary forms, with or without
8modification, are permitted provided that the following conditions are met:
9
10 1. Redistributions of source code must retain the above copyright
11 notice, this list of conditions and the following disclaimer.
12 2. Redistributions in binary form must reproduce the above copyright
13 notice, this list of conditions and the following disclaimer in the
14 documentation and/or other materials provided with the distribution.
15
16THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
17INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
18FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
19COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
20INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
21LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
22OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
23LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
24NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
25EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/README b/README
index 87aad52..8412eec 100644
--- a/README
+++ b/README
@@ -1,245 +1,239 @@
1Aim: 1[Erigo v0.9]
2 Create user-friendly efl gui builder. 2
3 3[Links to read]
4Functions: 4 https://phab.enlightenment.org/w/projects/gui_builder/
5 * Building Gui from scratch 5 http://yakov-g.blogspot.co.il/2013/04/egui-efl-gui-builder.html
6 * Emulate gui behavior without compilation 6
7 * Code generating with embedded json comments (or separate file with json) 7
8 8[Erigo - EFL GUI Builder]
9Features: 9
10 * Values validation (size >= 0) (should we make it in settings per widget) 10 Introducing Erigo (v.0.9) - the EFL gui builder.
11 * Integration with edje for theming 11It enables you easily create user interface for your application.
12 * Undo/redo management 12You can easily build multi-windowed application, simulate its behavior without compiling,
13 * Source code generation 13generate sources in different languages (currently C).
14 * Creating library of user's widgets, customize widgets 14
15 * Animations 15[Demo videos]
16 16
17Views / Functions / To remember: 17 https://www.youtube.com/watch?v=54lH4St9-8g
18 * Views: 18 https://www.youtube.com/watch?v=Y4RAKYKB-68
19 - Canvas 19
20 - Widgets view - displays set of available widgets 20[Compiling and installing]
21 - The Object Inspector - displays a hierarchical list of all the objects on the form 21 [Source Download]
22 that is currently being edited. 22 https://git.enlightenment.org/devs/yakov/egui.git/
23 - The Property Editor. Properties in hierarchical order. 23
24 24 [Dependencies]
25 * Tab order - change focus with pressing Tab 25 Mandatory:
26 * Copy/paste/cut/delete/clone + shortcuts 26 - CMake
27 * Find/replace/refactor (change name) + shortcuts 27 - FFI LIbrary (Ubuntu: sudo apt-get install libffi6 libffi6-dbg libffi-dev)
28 * Layouts / containers 28
29 * Translations 29 Non-Mandatory:
30 * Target device (layouts/resoltion/thumb size/available controls) 30 - Graphviz (Version > 2.35.00) - show application's graph.
31 * Callbacks for basic visual actions: "open/close..." 31
32 * Working modes: 32 [Building]
33 - GUI designer emulation/generation 33 $ cd egui
34 - Emulation without compilation (CLI) 34 $ mkdir build
35 - Export to another languages (CLI) 35 $ cd build
36 36 $ cmake ..
37 37 $ make
38JSON example 38
39 39 [Installing]
40/** 40 (run from "build" directory)
41 * @egui 41
42 * { 42 [Using Erigo]
43 * "win": { 43 [Command line]
44 * "parent" : "NULL", 44
45 * "class" : "ELM_OBJ_WIN_CLASS", 45 Start:
46 * "constructor" : ["elm_obj_win_constructor", "bg", 0], 46 $ ./src/bin/egui ../examples/example.egui
47 * "name" : "window", 47
48 * "title" : "window!!", 48 Simulation:
49 * "autodel" : 1, 49 $ ./src/bin/egui -s [Desktop/Phone/Tablet] ../examples/example.egui
50 * "size" : [320, 320], 50
51 * "visibility" : 1 51 Export to C ("filename.c" and "filename.h" will be generated):
52 * } 52 $ ./src/bin/egui -e c -o filename ../examples/example.egui
53 * } 53
54 * @!egui 54 Export to JSON ("filename" generated):
55 */ 55 $ ./src/bin/egui -e json -o filename ../examples/example.egui
56 56
57Issues / questions / internal design: 57 [User Interface]
58 * How to integrate callbacks 58 Top - Actions Toolbar:
59 59 - Project (New, Open, Save, Save As, Export, Close).
60 60 - Resource manager (Project's Resources - Images, Edge files, Callbacks, Strings).
61******************************************************************* 61 - Settings (Project's Settings - Project name, enter points, paths).
62**************** Blog article ************************************* 62 - Edit (Undo, Redo, Reload context).
63******************************************************************* 63 - View - show/hide, change view of windows.
64http://yakov-g.blogspot.co.il/2013/04/egui-efl-gui-builder.html 64 - Simulate - run application simulation on different targets.
65 65 - Graph - show application's graph.
66Gui Builder first example. 66 Left:
67 67 - Widgets factory - Drag`n`Drop supported
68 68 Right:
69We want to create Gui_Bulder which will implement all main gui creator's functionality and also will support 69 - Objects Tree View;
70simulation and generation modes from command line. 70 - Properties view with Description, Properties, Callbacks and Content tabs.
71 71 Center - Main canvas.
72Here I'm going to describe how we are going to do this. 72
73 73 [Resource manager]
74So let's start.. 74 Resource Manager allows you to add such resources as images, edge files,
75 75 callbacks and strings, assign alias name and later use in application design.
76Main idea is that we don't want to have large hard-to-read resource file. 76 In order to add resource, switch to desired tab, fill in fields at the bottom,
77We want to put json comments right into c file. (Anyway we can put all the comments into separate file) 77 when it is possible you can use file selection dialog (press "..."). In the end press "Add Resource" button.
78 78 In order to edit resouce: change desired fields and press "Save" button.
79/* @egui 79 To delete resource: press "del" button.
80{ 80
81 "main_win": 81 [Project Settings]
82 { 82 Set Project name - used in structure's, function's, variable's names in generated code.
83 "Desc": 83 Set Images prefix name: - give the name of define which will provide prefix path for app's images.
84 { 84 Set Start Points - define main objects which will be created on application start.
85 "parent":null, 85
86 "class":"Elm_Win", 86 [Object tree view]
87 "public":true, 87 Objtree shows items with it's children.
88 "type":"widget" 88 Search string allows to filter widgets by name.
89 }, 89
90 "Properties": 90 [Property View]
91 { 91 Property view provides detailed information about widgets.
92 "constructor":["elm_obj_win_constructor"], 92 It contains four tabs: Description, Properties, Callbacks, Content.
93 "elm_obj_win_constructor":[null, "ELM_WIN_BASIC"], 93 Search string allows to filter properties by name and fields contain popup hints - just put mouse over it.
94 "title":["Egui is Cool! - Autogenerated"], 94
95 "autodel":[true], 95 Description tab contains following fields: class name (can not be changed), name, public property.
96 "size":[1000, 650], 96 When widget is marked as "public" it will be accessible in generated code.
97 "resize_object_add":["main_bg"], 97
98 "resize_object_add":["main_box"], 98 Properties tab shows properties grouped by class in inheritance order.
99 "visibility":[true] 99 Properties colored in grey are properties, which were not changed by user and they show default values,
100 } 100 whereas properties colored in white were changed by user.
101 } 101 They can be dropped by clicking "Menu" button and choosing "Drop Property".
102 } 102 Some properties such as ("Size Hint Weight", "Size Hint Align") have predefined(aliased) set of values,
103@!egui */ 103 which can be accessed by pressing on "..." button next to property value.
104 main_win = eo_add_custom(ELM_OBJ_WIN_CLASS, NULL, elm_obj_win_constructor(NULL, ELM_WIN_BASIC)); 104
105 eo_unref(main_win); 105 Callbacks tab shows callbacks supported by widget. The list is sorted by inheritance order.
106 pub_widgets.main_win = main_win; 106 Callbacks can be assigned with next actions: "Modify", "Create", "Invoke".
107 eo_do(main_win, elm_obj_win_title_set("Egui is Cool!")); 107
108 eo_do(main_win, elm_obj_win_autodel_set(EINA_TRUE)); 108 "Modify" - this action changes a property of desired object.
109 eo_do(main_win, evas_obj_size_set(1000, 650)); 109 First you choose "Modify" action, then you choose an object - one of the widgets defined in the project.
110 eo_do(main_win, elm_obj_win_resize_object_add(main_bg)); 110 Then you can choose a property from the list of supported and finally fill in values.
111 eo_do(main_win, elm_obj_win_resize_object_add(main_box)); 111
112 eo_do(main_win, evas_obj_visibility_set(EINA_TRUE)); 112 "Create" - this action allows to invoke creation of one of main objects.
113 113 After you choose "Create", choose main object to create and it's parent.
114 In this example, "main_win" is widgets, 114 Example: You have two main object: "Window 1" and "Window 2". "Window 1" is created when application is launched.
115 "parent", "public", "size" etc - are properties 115 You want "Window 2" to be created when "Button" is clicked in "Window 1".
116 116 You need to open "Callbacks" tab for "Button" object. Extend class "Evas.CLickable_Interface",
117 Different properties can be seen in json. 117 for "clicked" event choose "Create", select "Window 2" as first parameter and leave the second parameter empty,
118 Some of them are shorter names of well-known evas/elementary functions, 118 because we want "Window 2" to be created next to "Window 1" (parent is NULL).
119 some are for internal builder needs. 119
120 like "public" - means that this widget should be accessible from outside. 120 "Invoke" - this action allows you to invoke user callback. User callback must be registered in Resource Manager.
121 121
122 As soon as there is such data, it's possible to parse json, save data and later simulate 122 Content tab - allows to manage content according to class of selected windget.
123 current gui's behavior or generate sources in desired language. 123 Erigo defines following types of containers:
124 124 - Pack containers: Box, Table.
125 125 - Resize object containers: Window.
126 How do we get such names of properties? 126 - Part containers: (according to "part_content_set" function): Button, Check, Radio, Actionslider, Clock,
127 Gui Builder is based on Eo (EFL object oriented model). 127 Dayseelctor, Calendar, Colorselector, Bubble, Entry, Flip, Layout
128 Currently each Evas object or Elementary widget are implemented using Eo. 128 - Item containers (Item widgets): Menu, Diskselector, Ctxpopup, Toolbar, Naviframe.
129 So widget's class name also provided in json. 129 Content view contains different control elements depending on type of selected widget.
130 130
131 During simulation and source code generation proper function is fetched from 131 [Graph view]
132 internal Gui Builders database according to property name and widget's class name. 132 Erigo allows you to build graph of your application. Press "Graph" button to open Graph View window.
133 133
134 What is internal Gui Builder's database? 134 [Project menu]
135 We have a script which searches for all data (functions, parameters, types, etc) 135
136 of all classes in provided paths. (all Elementary widgets, etc). 136 "New Project" - create new project.
137 Only needed data(based on gui_db.in) will be selected and database for Gui Builder 137 Click "New Project" menu item to open "New Project" dialog.
138 will be generated. 138 Type in project name, select project folder or type new folder name. Click "Ok".
139 139 Project file will be created in selected folder.
140 Currently "gui_db.in" looks like this. 140 For project name "New Project" project file will be created with name "new_project".
141 141
142 ************************************************************ 142 "Save" - save project file. Also "Ctrl + S" key combination can be usde.
143 gui_db.in 143
144 ************************************************************ 144 "Save As" - save project file as.
145 OPERATIONS = 145 Click "Save As" menu item to save project in different file. In opened dialog select folder and enter file name.
146 evas_obj_color,set:color_set: 146 Click "Ok."
147 evas_obj_size_set:size_set: 147 Also "Ctrl + Shift + S" key combination can be used.
148 evas_obj_position,set:position_set: 148
149 evas_obj_size_hint_weight,set:size_hint_weight_set 149 "Export" - option allows you to generate C source code.
150 evas_obj_visibility_set:visibility_set 150 Click "Export" choose folder and enter "filename". "filename.c" and "filename.h" files will be generated.
151 elm_obj_bg_color_set:bg_color_set 151
152 elm_obj_win_title_set:title_set 152 Close project - closes current project.
153 elm_obj_win,autodel_set:autodel_set 153
154 elm_obj_win_resize_object_add:resize_object_add 154 [Editing]
155 elm_wdg_part_text_set: part_text_set 155 Erigo supports all conventional ways of editing in gui builders: drag and drop, moving and resizing,
156 elm_obj_win_constructor: 156 properties and containers editing.
157 elm_obj_container_content_set:content_set 157
158 ; 158 Select object by clicking it on canvas or by selecting it in Object View.
159 159 When object is selected green border is drawn around it. Now you can open Property view to review and change property's values,
160 CLASSES = 160 manage callbacks and containers. Object can be resized by dragging border's markers.
161 elm_win , 161 If object is packed into container, changing it's size/position may not have effect.
162 elm_button, 162
163 elm_bg, 163 Objects can be dragged and dropped around canvas. It can be dragged from factory to canvas, between containers,
164 elm_label, 164 between windows, from window to canvas(object becomes main) and from canvas to window(object stops being main).
165 elm_bubble, 165
166 ; 166 Erigo also supports undo/redo functionality. You can either use Undo/Redo buttons, or shortcuts "Ctrl + z", "Ctrl + Shift + z"
167 ************************************************************ 167
168 168 [Main Objects]
169 169 All objects which are located directly on canvas are main. Generally they are windows, but any other object also can be main.
170 CLASSES - literally widgets which will be known by Gui Builder. 170 It is useful when you want to have custom snippet which can be used in different places around the project.
171 OPERATIONS - functions which will be searched by script and mapped into Gui Builder property. 171 You build it as a main object and invoke its creation using "Create" action.
172 172
173 For example: "evas_obj_color,set:color_set" looks for every function, 173 [Using Edje]
174 which has parts "evas_obj_color" and "set" and stores it's data into hash. 174 You can use Edje objects in your project. It can be either compiled edj object or raw edc file.
175 175 If you use compiled edj object simply add it as a resource and use in "File" property.
176 In this case "evas_object_color_set" will be found in "Evas_Obj" class. 176 If you want to use raw edc file, add all its objects into your project's folder into consequent dirs: "images", "sounds", "fonts", "data".
177 Data about this func will be stored in a hash with key "class + property" {"Evas_Obj", "color_set"}. 177 In order to edit edc file you can start Enventor right from Resource Manager. When you save the changes, edc file will be automatically compiled and reloaded.
178 178
179 another example: 179 [Simulation]
180 Rule "_multi_select_set":"multi" 180 This feature allows you to test application behaviour without compiling.
181 will find two functions: "elm_obj_genlist_multi_select_set", "elm_obj_gengrid_multi_select_set" 181 Go to "Simulate->Create a new session..." submenu in toolbar and select target, which you want to run simulation on.
182 and store it into {"elm_genlist", "multi"} and {"elm_gengrid", "multi"}. 182 To finish simulation close all simulated windows or select "Simulation->Name of simulation->Kill".
183 When simulating, this property will be dispatched correctrly as soon as 183
184 "multi" belongs to classes in separate hierarchies. 184 [Key Shortcuts]
185 185 Following key shortcuts are currently available in Erigo.
186 But name clashes in the same hierarchy should be avoided. 186 "Crtl + z" - Undo.
187 for example: 187 "Crtl + Shift + z" - Redo.
188 "evas_obj_color_set" and "elm_obj_bg_color_set" both can be mapped into property "color_set". 188 "Ctrl + s" - Save.
189 Dispatch will work correctly, because functions belong to different classes, but user will have to remember, that 189 "Ctrl + Shift + s" - Save as.
190 "color_set" in backgroud widget receives three parameters and other widgets - four. 190 "Delete" - delete widget.
191 191
192 There can be other issues, and it's planned to use interfaces in such cases. 192 [Usecases]
193 193 [Creating new project - Add Window, Background, Box, Button]
194 194 Start Erigo with
195 Also, according to this database, widget's available properties will be displayed in "Property Inspector" of builder. 195 $ ./src/bin/erigo
196 196 Click "Project->New Project".
197 Checkout Egui: 197 Type in "Project Name", choose project folder and click "Ok". New project is created.
198 > git clone git://git.enlightenment.org/devs/yakov/egui.git 198
199 199 Drag "Window" widget from Factory to main canvas. Drag "Background" widget to Window.
200 Mandatory Requirements: 200 Select "Window" widget and open "Content" tab in Property view.
201 FFI library: 201 Set "Background" as Window's content. Background will be set as window's resize object.
202 In order to install it in Ubuntu: 202
203 > sudo apt-get install libffi6 libffi6-dbg libffi-dev 203 Drag "Box" widget to Window. Select "Window" widget and open "Content" tab in Property view.
204 204 Set "Box" as Window's content. Box will be set as window's resize object.
205 Non-mandatory requirements: 205
206 In order to be able to generate application's graph, which shows relations between 206 Drag and drop "Button" widget into the Box.
207 widgets, sequences and callbacks, Graphviz library (version > 2.35.00) is needed. 207 That's it!
208 208
209 In order to install it in Ubuntu: 209 [Adding image as a resource and apply it to background.]
210 > sudo apt-get install libgraphviz-dev libgvc6 210 Open "Resource manager" and switch to Images tab.
211 211 Fill in fields in the bottom: type in alias name,
212 Build: 212 press "..." button and select image file.
213 > cd egui 213 Press "Add resource" button. Close "Resource manager".
214 > mkdir build 214 Select background widget in you project. Open "Property" tab.
215 > cd build 215 Find "File" property in Efl.File subclass and select desired alias in dropdown list.
216 > cmake .. 216
217 > make 217 [Adding menu (or any itemed widget)]
218 Should be compiled without errors. 218 It will be shown on example of window's main menu. Each window widget has main menu, but it is not visible if has no items.
219 219 Select main menu in Object View and open Content tab in Property View.
220 Run simulation: 220 Tab has following buttons:
221 > ./src/bin/egui -f ../examples/example.c -s 221 "Add Item" - add new item after selected item.
222 222 "Add Subitem" - add subitem for selected item.
223 To see how this application look like on Phone or Tablet: 223 "Add Separator" - add separator after selected item
224 > ./src/bin/egui -f ../examples/example.c -s -t Tablet 224 "Delete Item" - not hard to guess :)
225 225 Add as many items as you need and set needed values. Put mouse over edit field in order to see tooltip.
226 Generate source code: 226
227 > ./src/bin/egui -f ../examples/example.c -e c -o new 227 [Working with edje]
228 - new.c and new.h will be generated in current dir 228 Add window widget on the canvas. Add layout to window and set it as window's resize object.
229 229 Add edje resource through Resource Manager. Open layout's "File" property and assign edje with needed part name.
230 Run simulation on newly generated file: 230
231 > ./src/bin/egui -f new.c -s 231 [Technical notes]
232 232 Current version is 0.9.
233 Run Gui Builder and open file: 233 ToDo:
234 > ./src/bin/egui -f new.c 234 - install script;
235 235 - fix drag and drop errors;
236 236 - add testing;
237 Also suggest name for this application, 237 - widgets multiselection and copy/paste;
238 We were thinking about "eline." 238 - cosmetics.
239
240 Waiting for your comments. :)
241
242
243
244
245 239