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]] ++++ --