include/SLP_UI_Gadget_PG.h

   1 /*
   2  * Copyright 2012  Samsung Electronics Co., Ltd
   3  *
   4  * Licensed under the Flora License, Version 1.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.tizenopensource.org/license
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18
  19
  20
  21 /**
  22  *
  23  * @ingroup SLP_PG
  24  * @defgroup SLP_PG_UI_GADGET UI gadget library
  25  * @{
  26
  27 <h1 class="pg">Introduction</h1>
  28 <h2 class="pg">Purpose of this document</h2>
  29 The purpose of this document is to describe how to develop/use UI gadget. This document gives programming guidelines to UI gadget devlopers and users.
  30 <h2 class="pg">Scope</h2>
  31 The scope of this document is limited to UI gadget component interface and API usage.
  32
  33 <h1 class="pg">UI gadget architecture</h1>
  34 <h2 class="pg">UI gadget</h2>
  35 An UI gadget is a visual component providing views (or features) of other applications, e.g., phonebook, myfile. Because UI gadgets are supposed to deliver most commonly used features that the platform can natively support, developers can avoid unnecessary massive code writing using UI gadgets. Hence an UI gadget eventually includes logics to handle simple request. UI gadget is able to be managed by UI gadget library.
  36 \image html SLP_UI_Gadget_PG_image00.png "Picture 1. UI gadget architecture diagram"
  37
  38 <h2 class="pg">UI gadget features</h2>
  39 UI Gadget Library has the following features:
  40 - It provides component interfaces for UI Gadget
  41 - It manages UI gadget instances in an application according to their lifecycle
  42
  43 <h2 class="pg">Lifecycle</h2>
  44 Essentially, an UI gadget has following five states (See Picture 2)
  45 - The initial state is \b Ready
  46 - If an UI gadget has been created, it is \b Created
  47 - If an UI gadget has been started, it is \b Running
  48 - If the application that is using an UI gadget is put into background, it is \b Stopped
  49 - If an UI gadget has been destroyed, it is \b Destroyed
  50
  51 An UI gadget has five callback methods that you can implement to perform operations when the UI gadget moves between states
  52 - When an UI gadget is created, \b create() is invoked
  53 - When an UI gadget is started, \b start() is invoked
  54 - When the application that is using an UI gadget is put into background, \b pause() is invoked
  55 - When the application that is using an UI gadget is brought to the foreground, \b resume() is invoked.
  56 - When an UI gadget is destroyed, \b destroy() is invoked
  57
  58 In addition, an UI gadget has callback methods for system events and message:
  59 - When an system event is generated, event() is invoked
  60 - When an UI gadget receives message from the caller, message() is invoked
  61
  62 \image html SLP_UI_Gadget_PG_image01.png "Picture 2. UI gadget state diagram"
  63
  64 <h2 class="pg">Management</h2>
  65 UI gadgets in an application are managed as a TREE structure (See Picture 3.) The features for the tree are:
  66 - Root of the tree is the UI gadget manager
  67 - UI gadget caller is parent of callees
  68 - Parents arrange the layout of their children
  69
  70 Every application which is using UI gadgets has one UI gadget manager as a root of the tree. And the UI gadget manager propagates system events and task management events by post-order traversal. Available system events are <i>low memory, low battery, language changed, and window rotate event</i>. And task management events are <i>pause and resume</i>.
  71
  72 \image html SLP_UI_Gadget_PG_image02.png "Picture 3. UI gadget management policy"
  73
  74 <h1 class="pg">Getting started</h1>
  75 <h2 class="pg">How to make UI gadget</h2>
  76 In this section, we are going to write your first UI gadget called "helloUG-efl". Before we get started, make sure you have read the overview, especially, lifecycle section. We will mainly deal with the operations of lifecycle.
  77
  78 \note <b>Sample codes</b> are included in the UI gadget source package. The samples for UI gadget developers are located in "/test/ug/", and the samples for UI gadget users are in "/test/app/." For instance, "helloUG-efl" codes are in "/test/ug/helloUG-efl/."
  79 \note <b>Naming rule:</b> The name of UI gadget must be "{NAME}-{UI LIB NAME}", e.g., "helloUG-efl"
  80
  81 <br>
  82 <h3 class="pg">UI gadget template</h3>
  83 To create an UI gadget, start by generating boilerplate code using UI gadget template as follow:
  84 @verbatim
  85 # ug-gen.sh helloUG-efl helloUG-efl EFL
  86 @endverbatim
  87
  88 \note <b>How to install UI gadget template:</b>
  89 @verbatim
  90 # apt-get install ui-gadget-template
  91 @endverbatim
  92
  93 \note <b>How to use UI gadget template:</b>
  94 @verbatim
  95 # ug-gen.sh [destination] [name] [UI library]
  96 @endverbatim
  97 - destination: destination directory
  98 - name: UI gadget name
  99 - UI library: UI library to use. Only EFL is available for now
 100
 101 After you generate code, you get following files:
 102 - <i>helloUG-efl.c</i>  (Source)
 103 - <i>helloUG-efl.h</i>  (Private header)
 104 - <i>CMakeList.txt</i>  (Build script)
 105 - <i>po/*</i>           (I18N files)
 106
 107 <i>helloUG-efl.c</i> contains base code, and the most important parts are <i>UG_MODULE_INIT</i> and <i>UG_MODULE_EXIT</i> which are symbols to export for dynamic linking. <i>UG_MODULE_INIT</i> is invoked when the UI gadget is loading, and it sets operations, private data, and the option. <i>UG_MODULE_EXIT</i> is invoked when the UI gadget is unloading, and it clears private data.<br><br>
 108 Even if you don't understand generated code right now, don't worry about it. What you have to do is just implementation of operations according to their role (see next section.)
 109 @code
 110 // in helloUG-efl.c
 111 UG_MODULE_API int UG_MODULE_INIT(struct ug_module_ops *ops)
 112 {
 113         struct ug_data *ugd;            // User defined private data
 114
 115         if (!ops)
 116                 return -1;
 117
 118         ugd = calloc(1, sizeof(struct ug_data));
 119         if (!ugd)
 120                 return -1;
 121
 122         // create operation
 123         ops->create = on_create;
 124         // start operation
 125         ops->start = on_start;
 126         // pause operation
 127         ops->pause = on_pause;
 128         // resume operation
 129         ops->resume = on_resume;
 130         // destroy operation
 131         ops->destroy = on_destroy;
 132         // message operation
 133         ops-> message = on_message;
 134         // event operation
 135         ops->event = on_event;
 136         // private data
 137         ops->priv = ugd;
 138         // option
 139         ops->opt = UG_OPT_INDICATOR_ENABLE;
 140
 141         return 0;
 142 }
 143
 144 UG_MODULE_API void UG_MODULE_EXIT(struct ug_module_ops *ops)
 145 {
 146         struct ug_data *ugd;
 147
 148         if (!ops)
 149                 return;
 150
 151         ugd = ops->priv;
 152         if (ugd)
 153                 free(ugd);              // clear private data
 154 }
 155
 156 @endcode
 157
 158 \note <b>struct ug_module_ops</b> is a data structure describing operations, private data, and the option of UI gadget:
 159 @code
 160 struct ug_module_ops {
 161         void *(*create)(struct ui_gadget *ug, enum ug_mode mode, bundle *data, void *priv);
 162         void (*start)(struct ui_gadget *ug, bundle *data, void *priv);
 163         void (*pause)(struct ui_gadget *ug, bundle *data, void *priv);
 164         void (*resume)(struct ui_gadget *ug, bundle *data, void *priv);
 165         void (*destroy)(struct ui_gadget *ug, bundle *data, void *priv);
 166         void (*message)(struct ui_gadget *ug, bundle *msg, bundle *data, void *priv);
 167         void (*event)(struct ui_gadget *ug, enum ug_event event, bundle *data, void *priv);
 168         void *reserved[5];
 169         void *priv;
 170         enum ug_option opt;
 171 };
 172 @endcode
 173
 174 \note <b>enum ug_option</b> is UI gadget options, available options are:
 175 @code
 176 // Enable indicator
 177 UG_OPT_INDICATOR_ENABLE
 178 // Enable indicator with portrait window
 179 UG_OPT_INDICATOR_PORTRAIT_ONLY
 180 // Enable indicator with landscape window
 181 UG_OPT_INDICATOR_LANDSCAPE_ONLY
 182 // Disable indicator
 183 UG_OPT_INDICATOR_DISABLE
 184 @endcode
 185
 186 \note <b>struct ug_data</b> is a user defined private data structure describing base layout, own UI gadget handler, and whatever you need:
 187 @code
 188 struct ug_data {
 189         Evas_Object *base;
 190         struct ui_gadget *ug;
 191
 192         // PUT WHATEVER YOU NEED
 193 }
 194 @endcode
 195
 196 <br>
 197 <h3 class="pg">Operations</h3>
 198 There are five state operations, a message operation, and an event operation: <i>create, start, pause, resume, destroy, message, and event.</i>
 199 <br><br>
 200 When "helloUG-efl" is created, the create operation is invoked. The implementation of create operation is <b>on_create()</b>. Basically, in the operation, we have to make a base layout and return it. Hence, we made base layout using <i>"window layout winset."</i> In case of fullview, we let indicator area be shown, otherwise, we don't (see <i>create_fullview()</i> and <i>create_frameview()</i>.) In addition, in the base layout, we put a box including a label and two buttons (see <i>create_content()</i>.) The label is labeled "Hello UI Gadget." And the first button, labeled "Send result", is for sending result to the "helloUG-efl" caller. The other button, labeled "Back", is for sending destroy request to the caller. For more information about two buttons, please see <i>Send results and request to destroy section</i>.
 201
 202 \note <b>Arguments:</b> All operations receive bundle type data which is named <i>data</i> (see \ref bundle_PG "bundle programming guide") And the argument <i>data</i> is automatically released by UI gadget manager after the UI gadget is destroyed.
 203
 204 @code
 205 // in helloUG-efl.c
 206 static void *on_create(struct ui_gadget *ug, enum ug_mode mode, bundle *data, void *priv)
 207 {
 208         Evas_Object *parent;
 209         Evas_Object *content;
 210         struct ug_data *ugd;
 211
 212         if (!ug || !priv)
 213                 return NULL;
 214
 215         ugd = priv;
 216         ugd->ug = ug;
 217
 218         parent = ug_get_parent_layout(ug);
 219         if (!parent)
 220                 return NULL;
 221
 222         if (mode == UG_MODE_FULLVIEW)
 223                 ugd->base = create_fullview(parent, ugd);
 224         else
 225                 ugd->base = create_frameview(parent, ugd);
 226
 227         if (ugd->base) {
 228                 content = create_content(parent, ugd);
 229                 elm_layout_content_set(ugd->base, "elm.swallow.content", content);
 230         }
 231         return ugd->base;
 232 }
 233
 234 static Evas_Object *create_fullview(Evas_Object *parent, struct ug_data *ugd)
 235 {
 236         Evas_Object *base;
 237
 238         base = elm_layout_add(parent);
 239         if (!base)
 240                 return NULL;
 241
 242         elm_layout_theme_set(base, "standard", "window", "integration");
 243         // In case of fullview, show indicator area
 244         edje_object_signal_emit(_EDJ(base), "elm,state,show,indicator", "elm");
 245         edje_object_signal_emit(_EDJ(base), "elm,state,show,content", "elm");
 246
 247         return base;
 248 }
 249
 250 static Evas_Object *create_frameview(Evas_Object *parent, struct ug_data *ugd)
 251 {
 252         Evas_Object *base;
 253
 254         base = elm_layout_add(parent);
 255         if (!base)
 256                 return NULL;
 257
 258         // In case of frameview, do not show indicator area
 259
 260         elm_layout_theme_set(base, "standard", "window", "integration");
 261         edje_object_signal_emit(_EDJ(base), "elm,state,show,content", "elm");
 262
 263         return base;
 264 }
 265
 266 static Evas_Object *create_content(Evas_Object *parent, struct ug_data *ugd)
 267 {
 268         Evas_Object *bx, *eo;
 269
 270         // add box
 271         bx = elm_box_add(parent);
 272
 273         // add label and pack it in the box
 274         eo = elm_label_add(parent);
 275         elm_label_label_set(eo, _("Hello UI Gadget"));
 276         evas_object_size_hint_align_set(eo, 0.5, EVAS_HINT_FILL);
 277         evas_object_size_hint_weight_set(eo, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
 278         evas_object_show(eo);
 279         elm_box_pack_end(bx, eo);
 280
 281         // add buttons and pack it in the box
 282         eo = elm_button_add(parent);
 283         elm_button_label_set(eo, _("Send result"));
 284         evas_object_size_hint_align_set(eo, EVAS_HINT_FILL, EVAS_HINT_FILL);
 285         evas_object_smart_callback_add(eo, "clicked", result_cb, ugd);
 286         elm_object_style_set(eo, "bottom_btn");
 287
 288         evas_object_show(eo);
 289         elm_box_pack_end(bx, eo);
 290
 291         eo = elm_button_add(parent);
 292         elm_button_label_set(eo, _("Back"));
 293         evas_object_size_hint_align_set(eo, EVAS_HINT_FILL, EVAS_HINT_FILL);
 294         evas_object_smart_callback_add(eo, "clicked", back_cb, ugd);
 295         elm_object_style_set(eo, "bottom_btn");
 296
 297         evas_object_show(eo);
 298         elm_box_pack_end(bx, eo);
 299         return bx;
 300 }
 301
 302 @endcode
 303
 304 When "helloUG-efl" starts, the start operation is invoked. The implementation of start operation is <b>on_start()</b>. In this operation, we do nothing:
 305
 306 @code
 307 // in helloUG-efl.c
 308 static void on_start(struct ui_gadget *ug, bundle *data, void *priv)
 309 {
 310
 311 }
 312 @endcode
 313
 314 When "helloUG-efl" is destroyed, the destroy operation is invoked. The implementation of destroy operation is <b>on_destroy()</b>. In the method, we delete base layout:
 315
 316 @code
 317 // in helloUG-efl.c
 318 static void on_destroy(struct ui_gadget *ug, bundle *data, void *priv)
 319 {
 320         struct ug_data *ugd;
 321
 322         if (!ug || !priv)
 323                 return;
 324
 325         ugd = priv;
 326
 327         evas_object_del(ugd->base);
 328         ugd->base = NULL;
 329 }
 330 @endcode
 331
 332 When the application using "helloUG-efl" is put into background, the pause operation is invoked. When the application is brought to the foreground, the resume operation is invoked. Besides, when an UI gadget receives message from its caller, the message operation is invoked. And when a system event is generated, the event operation is invoked. The implementation of pause, resume, message, and event operations are <b>on_pause(), on_resume(), on_message(), and on_event()</b>. In these operations, we do nothing:
 333
 334 @code
 335 // in helloUG-efl.c
 336 static void on_pause(struct ui_gadget *ug, bundle *data, void *priv)
 337 {
 338 }
 339 static void on_resume(struct ui_gadget *ug, bundle *data, void *priv)
 340 {
 341 }
 342
 343 static void on_message(struct ui_gadget *ug, bundle *msg, bundle *data, void *priv)
 344 {
 345 }
 346
 347 static void on_event(struct ui_gadget *ug, enum ug_event event, bundle *data, void *priv)
 348 {
 349         switch (event) {
 350                 case UG_EVENT_LOW_MEMORY:
 351                         break;
 352                 case UG_EVENT_LOW_BATTERY:
 353                         break;
 354                 case UG_EVENT_LANG_CHANGE:
 355                         break;
 356                 case UG_EVENT_ROTATE_PORTRAIT:
 357                         break;
 358                 case UG_EVENT_ROTATE_PORTRAIT_UPSIDEDOWN:
 359                         break;
 360                 case UG_EVENT_ROTATE_LANDSCAPE:
 361                         break;
 362                 case UG_EVENT_ROTATE_LANDSCAPE_UPSIDEDOWN:
 363                         break;
 364                 default:
 365                         break;
 366         }
 367 }
 368 @endcode
 369
 370 \warning Message data of message operation is bundle type data, named <i>msg.</i> <b>Because the message data is released after message operation is finished,</b> if you want to keep using it, please use <b>bundle_dup()</b> which duplicates given bundle data (see \ref bundle_PG "bundle programming guide")
 371
 372 <br>
 373 <h3 class="pg">Send results and request to destroy</h3>
 374 Usually, an UI gadget needs to send results or destroy request to the UI gadget caller. To send result, use <b>ug_send_result()</b>, and to send the destroy request, use <b>ug_destroy_me().</b>
 375 <br>
 376 We use bundle library for composing result data. The bundle provides us a few APIs to make a list of dictionary data that consists of key and value. (ex. {"name"  "John Doe"}) To get more information of bundle, please see \ref bundle_PG "bundle programming guide".
 377
 378 \warning After send your result data, you have to release it using <b>bundle_free()</b> API.
 379
 380 In our "helloUG-efl", we made two buttons for sending results and destroy request as below:
 381 @code
 382 // in helloUG-efl.c
 383
 384 //Include to use bundle APIs
 385 #include <bundle.h>
 386
 387 static void result_cb(void *data, Evas_Object *obj, void *event_info)
 388 {
 389         bundle *b;
 390         struct ug_data *ugd;
 391
 392         if (!data)
 393                 return;
 394
 395         ugd = data;
 396         b = bundle_create();
 397         if (!b)
 398                 return;
 399
 400         bundle_add(b, "name", "helloUG-efl");
 401         bundle_add(b, "description", "sample UI gadget");
 402         //Send result
 403         ug_send_result(ugd->ug, b);
 404
 405         //release bundle
 406         bundle_free(b);
 407 }
 408
 409 static void back_cb(void *data, Evas_Object *obj, void *event_info)
 410 {
 411         struct ug_data *ugd;
 412
 413         if (!data)
 414                 return;
 415         ugd = data;
 416
 417         //Send destroy request
 418         ug_destroy_me(ugd->ug);
 419 }
 420 @endcode
 421
 422 \note <b>To use bundle</b>
 423 - Install libbundle-dev package
 424 - Modify CMakeFile.txt to use bundle package as follow:
 425 @code
 426         …
 427                 pkg_check_modules(pkgs REQUIRED elementary ui-gadget-efl bundle)
 428         …
 429 @endcode
 430
 431 <br>
 432 <h3 class="pg">Internationalization</h3>
 433 Basically, we use <b><i>dgettext</i></b> for translating a text string into the user's native language because each UI gadget uses different textdomain. Fortunately, if you generate your code using UI gadget template, you don't need to worry about <i>dgettext</i> and textdomain because a few macros are kindly provided by template. In helloUG-efl.h, which is a generated private header of "helloUG-efl", there are a few macros for convenience:
 434 @code
 435 // in helloUG-efl.h
 436 #define PKGNAME                 "ug-helloUG-efl"
 437 #define _(s)                    dgettext(PKGNAME, s)
 438 #define dgettext_noop(s)        (s)
 439 #define N_(s)                   dgettext_noop(s)
 440 @endcode
 441
 442 The PKGNAME is textdomain of "helloUG-efl", and _() is a dgettext wrapper, and N_() is dummy macro. In addition, _() and N_() are additional keywords for marking translatable string for xgettext. Especially, N_() is a dummy keyword for special case as follow:
 443 @code
 444 static const char *message[] = {
 445         N_("translatable string"),
 446 };
 447 @endcode
 448
 449 For more information, please see <a href="http://www.gnu.org/software/gettext/manual/gettext.html">GNU gettext utilities</a>.
 450
 451 \note <b>xgettext</b> extracts gettext strings from given input files. The canonical keyword for marking translatable strings is 'gettext'. For convenience, many packages use '_' as a keyword instead of 'gettext', and write '_("translatable string")' instead of 'gettext("translatable string")'.
 452
 453 <br>
 454 <h3 class="pg">Rotation and indicator</h3>
 455 When the UI gadget is created as fullview, we have to consider whether the indicator is shown or not. For instance, "Image viewer" shows the indicator on the portrait mode but not on the landscape mode. Hence, we provided option field named <i>opt</i> of <i>struct ug_module_ops</i> in UG_MODULE_INIT.
 456 Available options are as following:
 457 - UG_OPT_INDICATOR_ENABLE (default)
 458 - UG_OPT_INDICATOR_POTRAIT_ONLY
 459 - UG_OPT_LANDSCAPE_ONLY
 460 - UG_OPT_INDICATOR_DISABLE
 461
 462 And we used UG_OPT_INDICATOR_ENABLE in "helloUG-efl"
 463
 464 <br>
 465 <h3 class="pg">Build and test</h3>
 466 Before you build, you have to make sure whether translatable strings exist or not. IF translatable strings EXIST, please follow these steps before you build:
 467 @verbatim
 468 # cd po
 469 # ./update-po.sh
 470 # cd ..
 471 @endverbatim
 472 IF NOT, please remove the following line in your CMakeList.txt
 473 @verbatim
 474 ADD_SUBDIRECTORY(po)
 475 @endverbatim
 476
 477 To build "helloUG-efl", follow these steps:
 478 @verbatim
 479 # mkdir build
 480 # cd build
 481 # cmake -DCMAKE_INSTALL_PREFIX=/usr ..
 482 # make
 483 # make install
 484 @endverbatim
 485
 486 \note <b>Naming rule:</b> The output library name is <b>"libug-helloUG-efl.so"</b>, and we use <b>"helloUG-efl"</b> as UI gadget name except prefix <b>"libug-"</b> and postfix ".so" In other word, when you make an UI gadget, the name of library MUST be <b>"libug-XXXXXX.so"</b>
 487 \note <b>Installation directory:</b> UI gadgets MUST be installed in "${PREFIX}/lib/ug/"
 488
 489 Finally, we made our first UI gadget, "helloUG-efl." Let's test it using <i>ug-launcher</i> which is simple UI gadget launcher. Because we are using beat style buttons in our UI gadget, we specify "beat" as ELM_THEME.
 490 Fullview test
 491 @verbatim
 492 # ELM_THEME=beat ug-launcher -n helloUG-efl
 493 @endverbatim
 494 Frameview test
 495 @verbatim
 496 # ELM_THEME=beat ug-launcher -n helloUG-efl -f
 497 @endverbatim
 498
 499 \note <b>How to install UG launcher</b>
 500 @verbatim
 501 # apt-get install ui-gadget-tools
 502 @endverbatim
 503 \note <b>How to use UG launcher</b>
 504 @verbatim
 505 # ug-launcher [-F] [-f] -n <UG_NAME> [-d <Argument>]
 506 @endverbatim
 507 - -d: argument, key, value pair.
 508 - -F: Fullview mode (default)
 509 - -f: frameview mode
 510 \note <b> Example: </b>
 511 @verbatim
 512 # ug-launcher -F -n helloUG-efl -d "name,John doe" -d "age,30"
 513 @endverbatim
 514
 515 \image html SLP_UI_Gadget_PG_image03.png "Picture 3. helloUG-efl test: Fullview (left) and Frameview (right)
 516
 517 <br>
 518 <h2 class="pg">How to use UI gadget</h2>
 519 Now, we are going to use "helloUG-efl" of previous section.
 520
 521 <br>
 522 <h3 class="pg">Initialize</h3>
 523
 524 If you are UI gadget developer who is trying to use UI gadgets, please skip this section. This section is for application developers who use UI gadgets.
 525 You have to initialize UI gadget manager before you use UI gadgets. To initialize, use <b>ug_init()</b> with arguments: <i>disp, xid, win and opt</i>. <i>disp</i> is default display, and <i>xid</i> is X window id of win. <i>win</i> is window evas object for UI gadgets, and it is usually main window. <i>opti</i> is rotation and indicator option for your application (see <i>Rotation and indicator section</i>.)
 526
 527 The <i>disp</i> and <i>xid</i> are used for indicator management. If you don't know how to get display and X window ID, just use following macro: <b>UG_INIT_EFL(win, opt);</b>
 528
 529 \note <b>Prototype of ug_init():</b>
 530 @code
 531 int ug_init (Display *disp, Window xid, void *win, enum ug_option opt);
 532 @endcode
 533 \note <b>Macros for convenience (see 3 API reference quide):</b>
 534 @code
 535 UG_INIT_EFL(win, opt);
 536 @endcode
 537
 538 <br>
 539 <h3 class="pg">Create UI gadget instance</h3>
 540
 541 To create UI gadget instance, you have to invoke <b>ug_create()</b> which has five arguments: <i>parent, name, mode, data, and cbs.</i>
 542
 543 First, the <i>parent</i> is provided for specifying parent UI gadget, and it helps UI gadget manager to manage UI gadget tree (see <i>Management section.</i>) For instance, if the UI gadget 'A' uses other UI gadgets,  the parent has to be the 'A.' Otherwise, if an application uses UI gadgets, the <i>parent</i> has to be NULL.
 544
 545 Second, the <i>name</i> is the UI gadget's name (ex. "helloUG-efl")
 546
 547 Third, the <i>mode</i> could be UG_MODE_FULLVIEW to show the UI gadget as fullview, or UG_MODE_FRAMEVIEW to show it as frameview.
 548
 549 Fourth, the <i>data</i> is arguments for the UI gadget which is bundle type (see \ref bundle_PG "bundle programming guide")
 550
 551 \warning After create UI gadget, you have to release the argument using <b>bundle_free()</b> API.
 552
 553 Fifth, the <i>cbs</i> is data describing layout callback, result callback, destroy callback, and private data. In detail, layout callback is used for layout arrangement, and it invoked after the UI gadget is created, and result callback is invoked to receive result from the UI gadget. And destroy callback is invoked to deal with destroy request from the UI gadget.
 554
 555 \warning Result data of the result callback is bundle type data, named <i>result</i>. <b>Because the result data is released after result callback is finished</b>, if you want to keep using it, please use <b>bundle_dup()</b> which duplicates given bundle data (see \ref bundle_PG "bundle programming guide")
 556
 557 \note <b>Prototype of ug_create():</b>
 558 @code
 559 struct ui_gadget *ug_create (struct ui_gadget *parent,
 560                         const char *name,
 561                         enum ug_mode mode,
 562                         bundle *data,
 563                         struct ug_cbs *cbs);
 564
 565 \note <b>struct ug_cbs</b> is describing some callbacks and private data:
 566 @code
 567 struct ug_cbs {
 568         void (*layout_cb)(struct ui_gadget *ug, enum ug_mode mode, void *priv);
 569         void (*result_cb)(struct ui_gadget *ug, bundle *result, void *priv);
 570         void (*destroy_cb)(struct ui_gadget *ug, void *priv);
 571         void *priv;
 572 };
 573 @endcode
 574
 575 Here are some examples:
 576
 577 @code
 578 // FULLVIEW example
 579 struct my_data {
 580         struct ui_gadget *ug;
 581 };
 582
 583 static void layout_cb(struct ui_gadget *ug, enum ug_mode mode, void *priv)
 584 {
 585         Evas_Object *base, *win;
 586
 587         if (!ug || !priv)
 588                 return;
 589
 590         base = ug_get_layout(ug);
 591         if (!base)
 592                 return;
 593
 594         win = ug_get_window();
 595
 596         switch (mode) {
 597                 case UG_MODE_FULLVIEW:
 598                         evas_object_size_hint_weight_set(base, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
 599                         elm_win_resize_object_add(win, base);
 600                         evas_object_show(base);
 601                         break;
 602                 default:
 603                         break;
 604         }
 605 }
 606
 607 static void result_cb(struct ui_gadget *ug, bundle *result, void *priv)
 608 {
 609         struct my_data *mydata;
 610         const char *val;
 611
 612         if (!ug || !priv)
 613                 return;
 614
 615         mydata = priv;
 616         if (result) {
 617                 val = bundle_get_val(result, "name");
 618                 if (val)
 619                         fprintf(stderr, "The name of UI gadget that sends result is %s\n", val);
 620         }
 621         ug_destroy(ug);
 622         mydata->ug = NULL;
 623
 624 }
 625
 626 static void destroy_cb(struct ui_gadget *ug, void *priv)
 627 {
 628         struct my_data *mydata;
 629
 630         if (!ug || !priv)
 631                 return;
 632
 633         mydata = priv;
 634
 635         ug_destroy(ug);
 636         mydata->ug = NULL;
 637 }
 638
 639 struct ui_gadget *create_ug(struct my_data *data)
 640 {
 641         struct ui_gadget *ug;
 642         struct ug_cbs cbs = {0, };
 643
 644         cbs.layout_cb = layout_cb;
 645         cbs.result_cb = result_cb;
 646         cbs.destroy_cb = destroy_cb;
 647         cbs.priv = (void *)data;
 648
 649         ug = ug_create(NULL, "helloUG-efl", UG_MODE_FULLVIEW, NULL, &cbs);
 650
 651         return ug;
 652 }
 653 @endcode
 654
 655 @code
 656 // FRAMEVIEW example
 657 struct my_data {
 658         struct ui_gadget *ug;
 659         Evas_Object *main_layout;
 660 };
 661
 662 static void layout_cb(struct ui_gadget *ug, enum ug_mode mode, void *priv)
 663 {
 664         Evas_Object *base, *win;
 665         struct my_data *mydata;
 666
 667         if (!ug || !priv)
 668                 return;
 669
 670         mydata = priv;
 671
 672         base = ug_get_layout(ug);
 673         if (!base)
 674                 return;
 675
 676         win = ug_get_window();
 677
 678         switch (mode) {
 679                 case UG_MODE_FRAMEVIEW:
 680                         elm_layout_content_set(mydata->main_layout, "content", base);
 681                         break;
 682                 default:
 683                         break;
 684         }
 685 }
 686
 687 static void result_cb(struct ui_gadget *ug, bundle *result, void *priv)
 688 {
 689         struct my_data *mydata;
 690         const char *val;
 691
 692         if (!ug || !priv)
 693                 return;
 694
 695         mydata = priv;
 696
 697         if (result) {
 698                 val = bundle_get_val(result, "name");
 699                 if (val)
 700                         fprintf(stderr, "The name of UI gadget that sends result is %s\n", val);
 701         }
 702
 703         ug_destroy(ug);
 704         mydata->ug = NULL;
 705
 706 }
 707
 708 static void destroy_cb(struct ui_gadget *ug, void *priv)
 709 {
 710         struct my_data *mydata;
 711
 712         if (!ug || !priv)
 713                 return;
 714
 715         mydata = priv;
 716
 717         ug_destroy(ug);
 718         mydata->ug = NULL;
 719 }
 720
 721 struct ui_gadget *create_ug(struct my_data *data)
 722 {
 723         struct ui_gadget *ug;
 724         struct ug_cbs cbs = {0, };
 725
 726         cbs.layout_cb = layout_cb;
 727         cbs.result_cb = result_cb;
 728         cbs.destroy_cb = destroy_cb;
 729         cbs.priv = (void *)data;
 730
 731         ug = ug_create(NULL, "helloUG-efl", UG_MODE_FRAMEVIEW, NULL, &cbs);
 732
 733         return ug;
 734 }
 735 @endcode
 736
 737 <br>
 738 <h2 class="pg">Send message</h2>
 739
 740 We provide API for sending message: <b>ug_send_message()</b>. When you send a message, you have to use bundle type data (see \ref bundle_PG "bundle programming guide").
 741
 742 \note <b>Prototype of ug_send_message():</b>
 743 @code
 744 int ug_send_message (struct ui_gadget *ug, bundle *msg);
 745 @endcode
 746
 747 \warning After send your message, you have to release it using <b>bundle_free()</b> API.
 748 @code
 749 //example
 750 bundle *b;
 751
 752 b = bundle_create();
 753 if (!b)
 754         return;
 755
 756         bundle_add(b, "name", "helloUG-efl");
 757         bundle_add(b, "type", "test message");
 758
 759         //Send message
 760         ug_send_message(ug b);
 761
 762         //release bundle
 763         bundle_free(b);
 764
 765 @endcode
 766
 767 <br>
 768 <h2 class="pg">Propagate event</h2>
 769
 770 If you are UI gadget developer who is trying to use UI gadgets, please skip this section. This section is for application developers who use UI gadgets.
 771
 772 We provide some APIs for event propagation: <b>ug_pause(), ug_resume(), and ug_send_event()</b>. <b>ug_pause()</b> and <b>ug_resume()</b> are used for task-managing. If the application is put into background, invoke <b>ug_pause()</b>, otherwise, if the application is brought to the foreground, invoke <b>ug_resume()</b>. <b>ug_send_event()</b> is used for system event: <i>low memory, low battery, language change, rotate portrait, rotate portrait upside-down, rotate landscape, and rotate landscape upside-down.</i>
 773
 774 \note <b>Prototype of ug_pause(), ug_resume(), and ug_send_event():</b>
 775 @code
 776 int ug_pause (void);
 777 int ug_resume (void);
 778 int ug_send_event (enum ug_event event);
 779 @endcode
 780
 781 <br>
 782 <h2 class="pg">Destroy all UI gadgets</h2>
 783
 784 If you are UI gadget developer who is trying to use UI gadgets, please skip this section. This section is for application developers who use UI gadgets.
 785
 786 When you terminate your application, destroy all UI gadgets using <b>ug_destroy_all()</b>.
 787
 788 \note <b>Prototype of ug_destroy_all: </b>
 789 @code
 790 int ug_destroy_all (void);
 791 @endcode
 792
 793  * @}
 794  */