cedric pushed a commit to branch master.
http://git.enlightenment.org/website/www-content.git/commit/?id=24d88d9d69aa9f5394e43c9e6001c5f0d039a7bb
commit 24d88d9d69aa9f5394e43c9e6001c5f0d039a7bb
Author: Clément Bénier <clement.ben...@openwide.fr>
Date: Fri Sep 4 14:44:25 2015 +0200
Wiki pages customizing_ui_pg created: 1 main PG
Signed-off-by: Clément Bénier <clement.ben...@openwide.fr>
---
pages/docs.txt | 1 +
pages/program_guide/customizing_ui_pg.txt | 503 ++++++++++++++++++++++++++++++
pages/program_guide/index.txt | 1 +
3 files changed, 505 insertions(+)
diff --git a/pages/docs.txt b/pages/docs.txt
index e362e33..238c34e 100644
--- a/pages/docs.txt
+++ b/pages/docs.txt
@@ -66,6 +66,7 @@ Go check the current available version of EFL on each
distro/platform:
* [[program_guide/connectivity_pg|Connectivity PG]]
* [[program_guide/eina_pg|Eina PG]]
* [[program_guide/focus_ui_pg|Managing UI Component Focus PG]]
+ * [[program_guide/customizing_ui_pg|Customizing UI Components PG]]
=== Samples ===
diff --git a/pages/program_guide/customizing_ui_pg.txt
b/pages/program_guide/customizing_ui_pg.txt
new file mode 100644
index 0000000..a3be002
--- /dev/null
+++ b/pages/program_guide/customizing_ui_pg.txt
@@ -0,0 +1,503 @@
+{{page>index}}
+--------
+===== Customizing UI Components =====
+
+Elementary UI components use the Edje library EDC themes to manage their look.
+
+=== Table of Contents ===
+
+ * [[#Elementary_Theme|Elementary Theme]]
+ * [[#Overlay|Overlay]]
+ * [[#Extension|Extension]]
+ * [[#Customizing_a_UI_Component_Style|Customizing a UI Component Style]]
+ * [[#Swallow_Parts|Swallow Parts]]
+ * [[#Text_Parts|Text Parts]]
+
+==== Elementary Theme ====
+
+An Elementary theme is an Edje EDC file that contains groups composed of parts
+and programs. For more information about Edje, refer to the
+[[/program_guide/edje_pg|Edje Guide]].
+
+== Use Theme Styles ==
+
+Elementary UI components provide a way to modify only some parts of the styles
+using the default theme. A style is a part of the EDC theme (a group) that
+concerns only one UI component. For example, you can create a new style for a
+button component to change its appearance without modifying the default theme.
+
+<note>
+When creating a new style, knowledge of how each UI component is themed is
+required, because setting another style always replaces the entire group used
+by the UI component. Important signals and parts must be there for the object
+to behave properly.
+</note>
+
+When several styles are loaded in the current theme, you can set a different
+style to a specific UI component using the ''elm_object_style_set()''
+function. It is also possible to see the current style with the
+''elm_object_style_get()'' function.
+
+The default theme specifies several styles for the button component. The code
+below shows how to set the "anchor" style of a newly created button component.
+
+<code c>
+Evas_Object *parent, *button;
+
+// Create a button object
+button = elm_button_add(parent);
+
+// Set its style to "anchor""
+elm_object_style_set(button, "anchor");
+</code>
+
+== Load Theme Styles ==
+
+Once written and compiled with Edje tools, the Elementary provides two methods
+to load the style in the application theme:
+
+ * overlays
+ * extensions
+
+When looking for a theme, the Elementary checks the list of overlays, if any
+are defined. Then it takes the default theme, and if it cannot find a theme
+for the UI component, it looks at the extensions list.
+
+=== Overlay ===
+
+An overlay can replace the look of all UI components by overriding the default
+style. If we create a new style called "default" for the button component and
+add it as an overlay, the Elementary uses the overlay for all button
+components overriding the default theme.
+
+Here is how to add an overlay to your application's theme.
+
+<code c>
+elm_theme_overlay_add(NULL, "./theme_button.edj");
+</code>
+
+<note>
+Here we assume that the "theme_button.edj" file only contains a new theme for
+the button component.
+</note>
+
+<note>
+Doing this is not recommended. Adding a file as an overlay makes the
+Elementary use the new theme for all the button components defined in the
+application. You must make sure that the "theme_button.edj" file reimplements
+everything that was previously defined in the default theme concerning the
+button component.
+</note>
+
+This is how to remove the previously added overlay to return to the default
+theme.
+
+<code c>
+elm_theme_overlay_del(NULL, "./theme_button.edj");
+</code>
+
+=== Extension ===
+
+With extensions, we can write styles that we can apply to some UI components
+(not all of them) by using the ''elm_object_style_set()'' function.
+
+The application adds a theme to the list of extensions with the following
+call.
+
+<code c>
+elm_theme_extension_add(NULL, "./theme_button_style_custom.edj");
+</code>
+
+<note>
+Here we assume that the "theme_button_style_custom.edj" file contains a new
+button style called "custom".
+</note>
+
+This is how to use the new "custom" style on a button component.
+
+<code c>
+Evas_Object *parent, *button;
+
+// Create a button object
+button = elm_button_add(parent);
+
+// Set its style to "custom"
+elm_object_style_set(button, "custom");
+</code>
+
+<note>
+When using ''elm_theme_extension_add'' or ''elm_theme_overlay_add'' to add a
+new theme extension or overlay to a Theme object (here called the default
+theme), the Elementary calls the ''elm_theme_flush'' function to flush
+Elementary theme caches. Thus, the theme of all UI components that use the
+default theme is reloaded.
+</note>
+
+== Create a New Theme ==
+
+This is how to create a new theme object.
+
+<code c>
+Elm_Theme *new_theme = elm_theme_new();
+</code>
+
+This function creates an empty specific theme that only uses the default
+theme. It has its own private set of extensions and overlays (which are empty
+by default). Specific themes do not fall back to the themes of parent objects.
+They are not intended for this use.
+
+This is how to apply this theme to a UI component and its children (a button,
+for example).
+
+<code c>
+// Create a button component
+Evas_Object *button = elm_button_add();
+
+// Set the new theme to the button component
+elm_object_theme_set(button, new_theme);
+</code>
+
+==== Customizing a UI Component Style ====
+
+UI component themes are written in Edje EDC source files (.edc). These files
+are compiled with Edje tools to make an .edj file that is used by the
+application. For more information on using the EDC language, see the
+[[/program_guide/edje_pg|Edje Guide]].
+
+A new Edje style can be added for a UI component. The best way is to copy the
+existing "default" style, rename it, and update it to your needs.
+
+== Create a Customized Style for the Check Component ==
+
+As an example, we show how to create a new style for the ''check'' component.
+The aim is to update the background and the main pictures of this UI component
+with custom pictures.
+
+The EDC source file concerning the check component (check.edc file) is
+composed of several groups.
+
+<code c>
+group
+{
+ name: "elm/check/base/default";
+}
+
+group
+{
+ name: "elm/check/base/toggle";
+}
+</code>
+
+Those two groups define two different styles for the check component (the
+"default" style and the "toggle" style).
+
+We copy the group corresponding to the "default" style in a new file to create
+a new style called "custom". This new style is saved in the "check_custom.edc"
+file.
+
+<code c>
+group
+{
+ name: "elm/check/base/custom";
+ // Here is the copy of the content of "default" style
+}
+</code>
+
+In the new group ("elm/check/base/custom"), we have to find the parts we want
+to modify. Here, the appropriate parts are "bg" and "check" parts.
+
+<code c>
+part
+{
+ name: "bg";
+ mouse_events: 0;
+ scale: 1;
+ description
+ {
+ state: "default" 0.0;
+ rel1.offset: 1 1;
+ rel2.relative: 0.0 1.0;
+ rel2.offset: 1 -2;
+ align: 0.0 0.5;
+ min: 16 16;
+ max: 16 16;
+ aspect: 1.0 1.0;
+ aspect_preference: VERTICAL;
+ image
+ {
+ normal: "check_base.png";
+ border: 5 5 5 5;
+ middle: 0;
+ }
+ fill.smooth: 0;
+ }
+}
+part
+{
+ name: "check";
+ mouse_events: 0;
+ scale: 1;
+ description
+ {
+ state: "default" 0.0;
+ rel1
+ {
+ to: "bg";
+ offset: 1 1;
+ }
+ rel2
+ {
+ to: "bg";
+ offset: -2 -2;
+ }
+ visible: 0;
+ color: 255 255 255 255;
+ image.normal: "check.png";
+ }
+ description
+ {
+ state: "visible" 0.0;
+ inherit: "default" 0.0;
+ visible: 1;
+ }
+ description
+ {
+ state: "disabled" 0.0;
+ inherit: "default" 0.0;
+ visible: 0;
+ color: 128 128 128 128;
+ }
+ description
+ {
+ state: "disabled_visible" 0.0;
+ inherit: "default" 0.0;
+ color: 128 128 128 128;
+ visible: 1;
+ }
+}
+</code>
+
+We do not detail all the options that can be modified here, but assume that
+the user is familiar with [[/program_guide/edje_pg|Edje]] and knows Edje
+basics.
+.
+Our custom pictures filenames are:
+
+ * check_base_custom.png for the bg part
+ * check_custom.png for the check part
+
+We must update the image.normal attribute in both parts with our custom
+pictures filenames to modify the pictures of this style.
+
+<code c>
+part
+{
+ name: "bg";
+ description
+ {
+ state: "default" 0.0;
+
+ image
+ {
+ normal: "check_base_custom.png";
+ border: 5 5 5 5;
+ middle: 0;
+ }
+
+ }
+}
+part
+{
+ name: "check";
+
+ description
+ {
+ state: "default" 0.0;
+
+ image.normal: "check_custom.png";
+ }
+
+}
+</code>
+
+<note>
+Here, we assume that the custom images are the same size as the "default"
+images.
+</note>
+
+== Use the New Style ==
+
+This is how to add the new theme file as an extension in the application.
+
+<code c>
+char edj_path[PATH_MAX] = {0, };
+
+// Get the full path of the edj file
+app_get_resource("/edje/check_custom.edj", edj_path, (int)PATH_MAX);
+
+// Load check custom style as an extension
+elm_theme_extension_add(NULL, edj_path);
+</code>
+
+Use the "custom" style on a new check component.
+
+<code c>
+Evas_Object *parent, *check;
+
+// Create a check object
+check = elm_check_add(parent);
+
+// Set its style to "custom"
+elm_object_style_set(check, "custom");
+</code>
+
+== Special Theme Parts ==
+
+Some parts of the EDC file can be interacted with the Elementary. The content
+of parts of the type ''TEXT'' are modified using the
+''elm_object_part_set_text()'' function. The content of ''SWALLOW'' parts is
+updated using the ''elm_object_part_content_set()'' function.
+
+=== Swallow Parts ===
+
+In the previous example (the check component "default" style), there is a part
+called "elm.swallow.content" that is of the type ''SWALLOW''.
+
+<code c>
+part
+{
+ name: "elm.swallow.content";
+ type: SWALLOW;
+ scale: 1;
+ description
+ {
+ state: "default" 0.0;
+ fixed: 1 0;
+ visible: 0;
+ align: 0.0 0.5;
+ rel1.to_x: "bg";
+ rel1.relative: 1.0 0.0;
+ rel1.offset: 1 1;
+ rel2.to_x: "bg";
+ rel2.offset: 1 -2;
+ rel2.relative: 1.0 1.0;
+ }
+ description
+ {
+ state: "visible" 0.0;
+ inherit: "default" 0.0;
+ fixed: 1 0;
+ visible: 1;
+ aspect: 1.0 1.0;
+ min: 16 16;
+ }
+ description
+ {
+ state: "disabled" 0.0;
+ inherit: "default" 0.0;
+ color: 255 255 255 128;
+ }
+ description
+ {
+ state: "disabled_visible" 0.0;
+ inherit: "default" 0.0;
+ color: 255 255 255 128;
+ fixed: 1 0;
+ visible: 1;
+ aspect: 1.0 1.0;
+ }
+}
+</code>
+
+We can push content (Evas_Object) to this part from the application anytime.
+The size and position of the content pushed is controlled by the EDC theme.
+
+<code c>
+Evas_Object *parent, *check1, *content;
+
+// Create a check object
+check1 = elm_check_add(parent);
+
+// Set the content of the check object
+elm_object_part_content_set(check1, "elm.swallow.content", content);
+</code>
+
+<note>
+We can add new ''SWALLOW'' parts when customizing a UI component's style, if
+we want to be able to control more content from the application. Note that
+removing existing ''SWALLOW'' parts changes the UI component's behavior.
+</note>
+
+=== Text Parts ===
+
+The same is done with parts of the type ''TEXT''. The check "default" style
+contains a part named "elm.text".
+
+<code c>
+part
+{
+ name: "elm.text";
+ type: TEXT;
+ mouse_events: 0;
+ scale: 1;
+ description
+ {
+ state: "default" 0.0;
+ visible: 0;
+ rel1.to_x: "elm.swallow.content";
+ rel1.relative: 1.0 0.0;
+ rel1.offset: 1 1;
+ rel2.relative: 1.0 1.0;
+ rel2.offset: -2 -2;
+ color: 0 0 0 255;
+ text
+ {
+ font: "Sans,Edje-Vera";
+ size: 10;
+ min: 0 1;
+ align: -1.0 0.5;
+ }
+ }
+ description
+ {
+ state: "visible" 0.0;
+ inherit: "default" 0.0;
+ visible: 1;
+ text.min: 1 1;
+ }
+ description
+ {
+ state: "disabled" 0.0;
+ inherit: "default" 0.0;
+ color: 0 0 0 128;
+ color3: 0 0 0 0;
+ }
+ description
+ {
+ state: "disabled_visible" 0.0;
+ inherit: "default" 0.0;
+ color: 0 0 0 128;
+ color3: 0 0 0 0;
+ visible: 1;
+ text.min: 1 1;
+ }
+}
+</code>
+
+This is how to modify the content of the "elm.text" part from the application.
+The position of the text, its size, color, look and feel are managed by the
+EDC theme.
+
+<code c>
+Evas_Object *parent, *check2;
+
+// Create a check object
+check2 = elm_check_add(parent);
+
+// Set the text of the check object
+elm_object_part_text_set(check2, "elm.text", "Test text");
+</code>
+
+------
+{{page>index}}
+
diff --git a/pages/program_guide/index.txt b/pages/program_guide/index.txt
index dfa897b..d53fab2 100644
--- a/pages/program_guide/index.txt
+++ b/pages/program_guide/index.txt
@@ -8,5 +8,6 @@
* [[program_guide/multilingual_pg|Multilingual PG]]
* [[program_guide/connectivity_pg|Connectivity PG]]
* [[program_guide/eina_pg|Eina PG]]
+ * [[program_guide/customizing_ui_pg|Customizing UI Components PG]]
* [[program_guide/focus_ui_pg|Managing UI Component Focus PG]]
++++
--
