aboutsummaryrefslogtreecommitdiffstats
path: root/pages/develop/efl/start.txt
diff options
context:
space:
mode:
authorAndrew Williams <andy@andywilliams.me>2017-10-20 08:53:58 -0700
committerapache <apache@e5-web1.enlightenment.org>2017-10-20 08:53:58 -0700
commit6ba47a1d2100a86bd1f41174161b414487f5a78c (patch)
tree4ccb0029ea07c458ac08e4e4a0950d8badd5cb34 /pages/develop/efl/start.txt
parentWiki page start changed with summary [] by Andrew Williams (diff)
downloadwww-content-6ba47a1d2100a86bd1f41174161b414487f5a78c.tar.gz
Wiki page start changed with summary [refactoring developer docs] by Andrew Williams
Diffstat (limited to 'pages/develop/efl/start.txt')
-rw-r--r--pages/develop/efl/start.txt298
1 files changed, 297 insertions, 1 deletions
diff --git a/pages/develop/efl/start.txt b/pages/develop/efl/start.txt
index c86c3f355..7bea6abee 100644
--- a/pages/develop/efl/start.txt
+++ b/pages/develop/efl/start.txt
@@ -1 +1,297 @@
-none \ No newline at end of file
+~~Title: EFL~~
+~~CODE-c~~
+
+{{page>index}}
+
+==== EFL ====
+
+EFL is a range of libraries that cover APIs to solve every day problems we, and others have encountered. You can see it having various API layers, with some intended for very low-level controls and access that no one but specialists (e.g. those writing a window manager itself) will need, through to higher level "just writing a notepad" application. The lower you go, the less portable things can be. Here we will cover the EFL features and APIs used to make things portably and cleanly. We will cover these topics here:
+
+ * Data structures (lists, hash tables, growable buffers/strings etc.)
+ * Main loop event, I/O and timing core
+ * Event queue and call handling
+ * Canvas scene graph and rendering
+ * UI object element layout, animation and theme abstraction
+ * Widgets/controls (buttons, sliders, scrollers etc.)
+ * Input method framework
+ * Data archive storage & retrieval
+ * Data structure (de)serialization
+ * Video & audio codec playback, control and display
+ * IPC and network connectivity (TCP, UDP, unix domain & abstract sockets, HTTP)
+ * File utilities
+ * Freedesktop.org standards (desktop files, menus, mime types, icons)
+ * Async I/O
+ * D-Bus IPC integration
+ * Location API
+ * Basic Audio playback, recording and mixing
+
+You will use a range of libraries to make use of the above, and so learning the naming of these is important to know where to look. They will be in Ecore, Evas, Edje, Elementary (Elm), Ecore_IMF, Eet, Emotion, Ecore_Con, Ecore_IPC, Eio, Eldbus, Elocation, Ecore_Audio, Ecore_File and Efreet. It is very useful to know the names of parts of EFL and what they are responsible for:
+
+^Component ^Domain ^Description ^
+|Ecore |Mainloop Input & Display |Mainloop, low level display and input system, connections and IPC |
+|Ector |Vector Graphics |*INTERNAL* Vector rendering API used by Evas |
+|Edje |Theme Graphics & Animation |Layout and abstraction for graphical elements that lay out items to define a look and feel with animation and basic event response |
+|Eet |Data Storage & Serialization |Data structure serialization and multi-key data storage in files with compression and encryption with fast random-access read |
+|Eeze |Device UDev Wrapper |A thin wrapper over UDev for finding devices on Linux |
+|Efl |Core Shared |*INTERNAL* Core things shared between EFL libraries |
+|Efreet |Standards |Handle desktop file, menus and icons from freedesktop.org |
+|Eina |Core Data Types |Core utilities for threading, data types (lists, hashes etc.) and more |
+|Eio |Async I/O |Handle async File I/O |
+|Eldbus |D-Bus & Event Glue |Glue in D-Bus protocol handling as a client and server into EFL |
+|Elementary |High Level & Widgets |High level wrapper on EFL as well as a full widget set with buttons, boxes, scrollers, sliders etc. |
+|Elocation |Location |Used for location and mapping services |
+|Elua |Lua Execution |*INTERNAL* Lua wrapper and convenience layer for running a Lua script engine |
+|Embryo |Bytecode VM & Compiler |A compiler and tiny VM execution library for the Small/Pawn language used by Edje for scripting |
+|Emile |Compression & Encryption |*INTERNAL* Compression and encryption utilities and abstractions |
+|Emotion |Video & Audio Playback |Wrapping Gstreamer, Xine and/or VLC to provide Video playback in Evas objects as well as audio playback controls |
+|Eo |Object System |Core object system for EFL with handling of classes, references, inheritance, safe object access and method execution etc. |
+|Eolian |Object Code Generation |Used with Eo to generate both C boilerplate src, and for generating bindings |
+|Ephysics |Physics & Object Glue |Glues the Bullet physics library to Evas objects and is used by Edje |
+|Escape |PS3 LibC Filler |*INTERNAL* Fills in missing LibC functionality for PS3 |
+|Ethumb |Image Thumbnailer |A library and service for async thumbnail generation and caching |
+|Evas |Scene Graph & Rendering |A complete scene graph and rendering abstraction as well as event router for UI and general graphics needs |
+|Evil |Windows LibC Filler |*INTERNAL* Fills in missing LibC functionality for Windows |
+
+We will make an assumption that you have a reasonable grasp of the C programming language here. Perhaps you might want to read the [[docs/c/start]] if you are new to C, or need a refresher.
+
+----
+
+=== Application Mainloop ===
+
+It is assumed every application has a [[mainloop]], and that EFL is
+in charge of that. If you are writing a library, then that assumption
+would be made ultimately of the application using that library as well.
+For the purposes of this introduction to EFL, we will talk about an
+application, how it starts, runs and shuts down.
+
+Every application is expected to have a life-cycle as follows. If you
+have a design that is significantly different then you will be
+struggling against EFL and what it is pushing you to use. This does
+not mean we do not support threads, we just push you into a specific
+design pattern.
+
+{{ :docs:efl:mainloop.svg?nolink |Application Mainloop}}
+
+An application would spend almost it's entire life inside the
+[[mainloop]] sleeping, processing events and then updating it's UI,
+until it decides to exit. All of this would take place inside the
+[[mainloop]] processing function elm_run() which will only return
+once the [[mainloop]] voluntarily exits if an elm_exit() function is
+called while it runs, which marks the loop to exit, next time it has a
+chance. Before and after this, will be initialization and shutdown of the
+application. Your most basic application that just does nothing but
+wait forever for events would be:
+
+<code c example.c>
+#include <Elementary.h>
+
+EAPI_MAIN int
+elm_main(int argc, char **argv)
+{
+ elm_run();
+ return 0;
+}
+ELM_MAIN()
+</code>
+
+Compile it (and other examples on this page) with:
+
+ cc example.c -o example `pkg-config --cflags --libs elementary`
+
+If ''pkg-config'' is complaining about not finding Elementary you may
+want to adjust your ''PKG_CONFIG_PATH'' environment variable to point
+to where the ''.pc'' files are installed. Perhaps like:
+
+ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
+
+Please see this nice page
+[[http://people.freedesktop.org/~dbn/pkg-config-guide.html|about pkg-config]]
+Which should tell you what it is and how it works if you are having trouble.
+
+Expanding on this, let us make our first application with an actual
+visible window and a button inside to click to exit. This will be our
+proverbial "Hello world" application.
+
+<code c example.c>
+#include <Elementary.h>
+
+static void
+on_click(void *data, Evas_Object *obj, void *event_info)
+{
+ evas_object_del(data);
+}
+
+EAPI_MAIN int
+elm_main(int argc, char **argv)
+{
+ Evas_Object *win, *btn;
+
+ elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED);
+
+ win = elm_win_util_standard_add("Main", "Hello, World!");
+ elm_win_autodel_set(win, EINA_TRUE);
+
+ btn = elm_button_add(win);
+ elm_object_text_set(btn, "Goodbye Cruel World");
+ elm_win_resize_object_add(win, btn);
+ evas_object_smart_callback_add(btn, "clicked", on_click, win);
+ evas_object_show(btn);
+
+ evas_object_show(win);
+
+ elm_run();
+
+ return 0;
+}
+ELM_MAIN()
+</code>
+
+When the application runs, the ELM_MAIN() macro sets up a normal
+main() function, inits EFL for you and then calls elm_main() with
+the usual application argc & argv parameters you get in C. When
+elm_main() returns, it will pass the return value to the return
+value of main() for the application exit code. Before it does this,
+EFL will be cleanly shut down for you. You are encouraged to use this
+setup above to ensure this happens.
+
+<code c>
+elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED);
+</code>
+
+The first thing we do is enable a policy where if our last window is
+deleted, the [[mainloop]] started by elm_run() is automatically
+quit when this last window is closed. This is really handy for
+applications with multiple windows that want to just go away when they
+are no longer presenting any UI.
+
+<code c>
+win = elm_win_util_standard_add("Main", "Hello, World!");
+</code>
+
+We now create a standard window with a standard background using a
+utility function. It has the **name** set to "Main". This is normally
+not a user-visible property of a window. It is used to identify that
+window separately from other windows the app may create. A dialog, a
+file selector window, a settings dialog etc. so name appropriately
+here. The window will display a title of "Hello, World!" in the
+titlebar (if such a thing exists on your platform). This title may be
+used in other places on a platform such as a window switcher, a
+taskbar or some other interface control element. The window will have a
+background already placed as the resize object of a window.
+
+<code c>
+elm_win_autodel_set(win, EINA_TRUE);
+</code>
+
+Next we enable **autodel** on the window. This means that if someone
+hits the close button, or otherwise uses some normal environment
+mechanism (keybinding, menu) to close the window, the window object is
+automatically deleted on the application side. If you do not do this,
+these mechanisms will not work and the window will stay around. It is
+expected that you would add a callback to handle the "delete,request"
+event on the window and then either delete it or do something like
+prompt the user if they are sure they wish to close the window
+(unsaved content?) etc.
+
+<code c>
+btn = elm_button_add(win);
+</code>
+
+Next we create a button (relative to the window). You must create all
+objects relative to some object inside a window or the window itself.
+All graphical objects belong to a window of some sort. This will not
+have set up the parent/child containering and control relationships
+yet. That comes later.
+
+<code c>
+elm_object_text_set(btn, "Goodbye Cruel World");
+elm_win_resize_object_add(win, btn);
+</code>
+
+We now set the label of the button to "Goodbye Cruel World", then add
+the button as a window resize object. If we did not set the label
+text, the button would be empty (and quite small by default). Windows
+have a special list of resize objects (can be more than one) stacked
+one on top of the other which resize when the window resizes. In turn
+they also affect the window sizing with their minimum and maximum
+sizes as well as sizing hints for weight and alignment (which we will
+come to later).
+
+<code c>
+static void
+on_click(void *data, Evas_Object *obj, void *event_info)
+{
+ evas_object_del(data);
+}
+</code>
+<code c>
+evas_object_smart_callback_add(btn, "clicked", on_click, win);
+</code>
+
+We now add a callback for the "clicked" smart event on the button.
+This will call the ''on_click'' function when a user clicks on the
+button. The [[mainloop]] drives event handling and thus calling of
+this callback. All event callbacks can pass in an arbitrary pointer to
+anything the like. This will be passed as the first data pointer to
+the callback above. In this case we will passing our window pointer as
+we want to delete the window when someone presses the button. Due to
+our policy settings, this will end up deleting the last window we have
+and automatically exiting the [[mainloop]], and then of course the
+application. The example works this way to show how it might be
+extended to open multiple windows and only have the window you click
+the button in be deleted, until all windows are gone and application
+cleanly exits.
+
+<code c>
+evas_object_show(btn);
+</code>
+
+Next we show the button. All graphical objects are hidden by default.
+This avoids unwanted events like mouse in, move and out events due to
+objects being created underneath the current pointer position. It
+makes things more efficient as you can show the object after you have
+finished defining its state.
+
+<code c>
+evas_object_show(win);
+</code>
+
+Now we show the window. It is best to show it last just before you
+jump into the [[mainloop]] to process everything. This means all
+window setup is invisible until it is finished.
+
+<code c>
+elm_run();
+</code>
+
+Finally we begin the [[mainloop]]. This function will not exit until
+the [[mainloop]] is done and exits (with an elm_exit() being
+called from inside some callback there). So at this point your
+application is handing full control over it's execution to EFL and the
+[[mainloop]] to deal with events and rendering of updates. From inside the mainloop function run by EFL, all your callbacks (functions you register to be called when events, state changes etc. etc. happen) will be called.
+
+----
+
+**NOTE**: If you don't want to use ELM_MAIN(), you can use
+elm_init() and elm_shutdown() manually yourself. You **MUST**
+call elm_init() before you call any EFL functions. It could fail
+too. Also never call any EFL functions after elm_shutdown().
+
+<code c example.c>
+#include <Elementary.h>
+
+int
+main(int argc, char **argv)
+{
+ if (!elm_init(argc, argv)) return -1;
+
+ elm_run();
+
+ elm_shutdown();
+ return 0;
+}
+</code>
+
+----
+
+~~DISCUSSIONS~~