include/ui-gadget.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 #ifndef __UI_GADGET_H__
  22 #define __UI_GADGET_H__
  23
  24 /**
  25  * @file        ui-gadget.h
  26  * @author      Wonguk Jeong <wonguk.jeong@samsung.com>
  27  * @version     0.1
  28  * @brief       This file contains the public API of the UI gadget library
  29  */
  30
  31 /**
  32  * @addtogroup APPLICATION_FRAMEWORK
  33  * @{
  34  *
  35  * @defgroup    UI_Gadget UI gadget library
  36  * @author      Wonguk Jeong <wonguk.jeong@samsung.com>
  37  * @version     0.1
  38  * @brief       A library to develop/use a UI gadget
  39  */
  40
  41 /**
  42  * @addtogroup UI_Gadget
  43  * @{
  44  *
  45  * @defgroup    UI_Gadget_For_User User API Reference Guide
  46  * @brief       A module to use a UI gadget. Caller uses this module and APIs.
  47  *
  48  * @section Header To Use Them:
  49  * @code
  50  * #include <ui-gadget.h>
  51  * @endcode
  52  */
  53
  54 /**
  55  * @addtogroup UI_Gadget_For_User
  56  * @{
  57  */
  58
  59 #include <bundle.h>
  60 #include <X11/Xlib.h>
  61
  62 #ifdef __cplusplus
  63 extern "C" {
  64 #endif
  65
  66 /**
  67  * struct ui_gadget is an opaque type representing a UI gadget
  68  * @see ug_create(), ug_destroy()
  69  * @see ug_get_layout(), ug_get_parent_layout(), ug_get_mode()
  70  */
  71 struct ui_gadget;
  72
  73 /**
  74  * UI gadget mode
  75  * @see ug_create()
  76  * @see ug_get_mode()
  77  */
  78 enum ug_mode {
  79         UG_MODE_FULLVIEW, /**< Fullview mode */
  80         UG_MODE_FRAMEVIEW, /**< Frameview mode */
  81         UG_MODE_INVALID, /**< Invalid mode */
  82         UG_MODE_MAX
  83 };
  84
  85 /**
  86  * UI gadget event
  87  * @see ug_send_event()
  88  */
  89 enum ug_event {
  90         UG_EVENT_NONE = 0x00,           /**< No event */
  91         UG_EVENT_LOW_MEMORY,            /**< Low memory event */
  92         UG_EVENT_LOW_BATTERY,           /**< Low battery event */
  93         UG_EVENT_LANG_CHANGE,           /**< Language change event */
  94         UG_EVENT_ROTATE_PORTRAIT,       /**< Rotate event: Portrait */
  95         UG_EVENT_ROTATE_PORTRAIT_UPSIDEDOWN,    /**< Rotate event: Portrait upsidedown */
  96         UG_EVENT_ROTATE_LANDSCAPE,      /**< Rotate event: Landscape */
  97         UG_EVENT_ROTATE_LANDSCAPE_UPSIDEDOWN,
  98                         /**< Rotate event: Landscape upsidedown */
  99         UG_EVENT_REGION_CHANGE,         /**< Region change event */
 100         UG_EVENT_MAX
 101 };
 102
 103 /**
 104  * UI gadget key event
 105  * @see ug_send_key_event()
 106  */
 107 enum ug_key_event {
 108         UG_KEY_EVENT_NONE = 0x00,       /**< No event */
 109         UG_KEY_EVENT_END,               /**< End key event */
 110         UG_KEY_EVENT_MAX
 111 };
 112
 113 #define UG_OPT_INDICATOR_MASK (0x03)
 114 #define UG_OPT_INDICATOR(opt) (opt & UG_OPT_INDICATOR_MASK)
 115
 116 /**
 117  * UI gadget option
 118  * - Indicator option: [1, 0] bits
 119  *
 120  * @see ug_init()
 121  */
 122 enum ug_option {
 123         UG_OPT_INDICATOR_ENABLE = 0x00,
 124                         /**< Indicator option:
 125                         Enable with both portrait and landscape window */
 126         UG_OPT_INDICATOR_PORTRAIT_ONLY = 0x01,
 127                         /**< Indicator option: Enable with portrait window */
 128         UG_OPT_INDICATOR_LANDSCAPE_ONLY = 0x02,
 129                         /**< Indicator option: Enable with landscape window */
 130         UG_OPT_INDICATOR_DISABLE = 0x03,
 131                         /**< Indicator option:
 132                         Disable with both portrait and landscape view window */
 133         UG_OPT_MAX
 134 };
 135
 136 /**
 137  * UI gadget callback type
 138  * @see ug_create()
 139  */
 140 struct ug_cbs {
 141         /** layout callback */
 142         void (*layout_cb) (struct ui_gadget *ug, enum ug_mode mode,
 143                                 void *priv);
 144         /** result callback */
 145         void (*result_cb) (struct ui_gadget *ug, bundle *result, void *priv);
 146         /** destroy callback */
 147         void (*destroy_cb) (struct ui_gadget *ug, void *priv);
 148         /** private data */
 149         void *priv;
 150 };
 151
 152 /**
 153  * Easy-to-use macro of ug_init() for EFL
 154  * @see ug_init()
 155  */
 156 #define UG_INIT_EFL(win, opt) \
 157         ug_init((Display *)ecore_x_display_get(), elm_win_xwindow_get(win), \
 158                 win, opt)
 159
 160 /**
 161  * Easy-to-use macro of ug_init() for GTK
 162  * @see ug_init()
 163  */
 164 #define UG_INIT_GTK(win, opt) \
 165         win ?  ug_init(gdk_display_get_default(), win, \
 166         GDK_WINDOW_XWINDOW(GTK_WIDGET(win)->window), win, opt) : -1
 167
 168 /**
 169  * \par Description:
 170  * This function initializes default window, display, xwindow id, and indicator state.
 171  *
 172  * \par Purpose:
 173  * First of all, to use UI gadgets in an application, default window to draw the UI gadgets has to be registered. Besides, to change indicator state for the full-view UI gadget, display and xwindow id have to be registered, and to restore application's indicator state, default indicator option has to be registered. This function is used for registering them.
 174  *
 175  * \par Typical use case:
 176  * Application developers who want to use UI gadget MUST register display, xwindow id, default window, and option with the function at first.
 177  *
 178  * \par Method of function operation:
 179  * Register display, xwindow id, default window, and option.
 180  *
 181  * \par Context of function:
 182  * None
 183  *
 184  * \note If you are unfamiliar with display and xwindow id, please use following macros: UG_INIT_EFL, UG_INIT_GTK. The macros kindly generate proper functions to get display and xwindow id.
 185  *
 186  * @param[in] disp Default display
 187  * @param[in] xid Default xwindow id of default window
 188  * @param[in] win Default window object, it is void pointer for supporting both GTK (GtkWidget *) and EFL (Evas_Object *)
 189  * @param[in] opt Default indicator state to restore application's indicator state
 190  * @return 0 on success, -1 on error
 191  *
 192  * \pre None
 193  * \post None
 194  * \see UG_INIT_EFL(), UG_INIT_GTK()
 195  * \remarks None
 196  *
 197  * \par Sample code:
 198  * \code
 199  * #include <ui-gadget.h>
 200  * ...
 201  * Evas_Object *win;
 202  * ...
 203  * // create window
 204  * ...
 205  * ug_init((Display *)ecore_x_display_get(), elm_win_xwindow_get(win), win, UG_OPT_INDICATOR_ENABLE);
 206  * // for convenience you can use following macro: ELM_INIT_EFL(win, UG_OPT_INDICATOR_ENABLE);
 207  * ...
 208  * \endcode
 209  */
 210 int ug_init(Display *disp, Window xid, void *win, enum ug_option opt);
 211
 212 /**
 213  * \par Description:
 214  * This function creates a UI gadget
 215  *
 216  * \par Purpose:
 217  * This function is used for creating a UI gadget instance. In addition, following callbacks could be registered with the function: layout callback, result callback, and destroy callback. (see struct ug_cbs)
 218  *
 219  * \par Typical use case:
 220  * Anyone who want to create UI gadget could use the function.
 221  *
 222  * \par Method of function operation:
 223  * First, the UI gadget with given name is dynamically loaded(dlopen). Next, state operations of loaded UI gadget are invoked according to its lifecycle. There are three callbacks which could be registered with the function: layout callback, result callback, and destroy callback. If the state is changed to "Create", the layout callback is invoked for layout arrangement. If ug_send_result() is invoked in the loaded UI gadget , the result callback is invoked. And, if ug_destroy_me() is invoked in the loaded UI gadget , the destroy callback is invoked.
 224  *
 225  * \par Context of function:
 226  * This function supposed to be called after successful initialization with ug_init()
 227  *
 228  * @param[in] parent parent's UI gadget. If the UI gadget uses the function, the parent has to be the UI gadget. Otherwise, if an application uses the function, the parent has to be NULL
 229  * @param[in] name name of UI gadget
 230  * @param[in] mode mode of UI gadget (UG_MODE_FULLVIEW | UG_MODE_FRAMEVIEW)
 231  * @param[in] data argument for the UI gadget  (see \ref bundle_PG "bundle programming guide")
 232  * @param[in] cbs callback functions (layout callback, result callback, destroy callback, see struct ug_cbs) and private data.
 233  * @return The pointer of UI gadget, NULL on error
 234  *
 235  * \pre ug_init()
 236  * \post None
 237  * \see struct ug_cbs, enum ug_mode
 238  * \remarks If you passed "data" bundle, you MUST release it using bundle_free() after ug_create()
 239  *
 240  * \par Sample code:
 241  * \code
 242  * #include <ui-gadget.h>
 243  * ...
 244  * bundle *b;
 245  * struct ui_gadget *ug;
 246  * struct ug_cbs cbs = {0, };
 247  *
 248  * // set callbacks: layout callback, result callback, destroy callback
 249  * cbs.layout_cb = _layout_cb;
 250  * cbs.result_cb = _result_cb;
 251  * cbs.destroy_cb = _destroy_cb;
 252  * cbs.priv = user_data;
 253  *
 254  * // create arguments
 255  * b = bundle_create();
 256  * bundle_add(b, "Content", "Hello");
 257  *
 258  * // create "helloUG-efl" UI gadget instance
 259  * ug = ug_create(NULL, "helloUG-efl", UG_MODE_FULLVIEW, b, &cbs);
 260  *
 261  * // release arguments
 262  * bundle_free(b);
 263  * ...
 264  * \endcode
 265  */
 266 struct ui_gadget *ug_create(struct ui_gadget *parent, const char *name,
 267                                         enum ug_mode mode, bundle *data,
 268                                         struct ug_cbs *cbs);
 269
 270 /**
 271  * \par Description:
 272  * This function pauses all UI gadgets
 273  *
 274  * \par Purpose:
 275  * This function is used for pausing UI gadgets with "Running" state. Eventually, state of the UI gadgets would be "Stopped."
 276  *
 277  * \par Typical use case:
 278  * Application developers who want to pause loaded UI gadgets could use the function.
 279  *
 280  * \par Method of function operation:
 281  * "Pause" state operations of UI gadgets with "Running" state in the UI gadget tree are invoked by post-order traversal.
 282  *
 283  * \par Context of function:
 284  * This function supposed to be called after successful initialization with ug_init()
 285  *
 286  * @return 0 on success, -1 on error
 287  *
 288  * \pre ug_init()
 289  * \post None
 290  * \see ug_resume()
 291  * \remarks None
 292  *
 293  * \par Sample code:
 294  * \code
 295  * #include <ui-gadget.h>
 296  * ...
 297  * // pause all UI gadget instances
 298  * ug_pause();
 299  * ...
 300  * \endcode
 301  */
 302 int ug_pause(void);
 303
 304 /**
 305  * \par Description:
 306  * This function resumes all UI gadgets
 307  *
 308  * \par Purpose:
 309  * This function is used for resuming UI gadgets with "Stopped" state. Eventually, state of all UI gadgets would be "Running."
 310  *
 311  * \par Typical use case:
 312  * Application developers who want to resume loaded UI gadgets could use the function.
 313  *
 314  * \par Method of function operation:
 315  * "Resume" state operations of UI gadgets with "Stopped" state in the UI gadget tree are invoked by post-order traversal.
 316  *
 317  * \par Context of function:
 318  * This function supposed to be called after successful initialization with ug_init()
 319  *
 320  * @return 0 on success, -1 on error
 321  *
 322  * \pre ug_init()
 323  * \post None
 324  * \see ug_pause()
 325  * \remarks None
 326  *
 327  * \par Sample code:
 328  * \code
 329  * #include <ui-gadget.h>
 330  * ...
 331  * // resume all UI gadget instances
 332  * ug_resume();
 333  * ...
 334  * \endcode
 335  */
 336 int ug_resume(void);
 337
 338 /**
 339  * \par Description:
 340  * This function destroys the given UI gadget instance
 341  *
 342  * \par Purpose:
 343  * This function is used for destroying given UI gadget instance and its children. Eventually, state of the instance would be "Destroyed."
 344  *
 345  * \par Typical use case:
 346  * Anyone who want to destroy specific UI gadget could use the function.
 347  *
 348  * \par Method of function operation:
 349  * "Destroy" state operations of the given UI gadget instance and its children are invoked.
 350  *
 351  * \par Context of function:
 352  * This function supposed to be called after successful initialization with ug_init() and creation UI gadget with ug_create()
 353  *
 354  * @param[in] ug The UI gadget
 355  * @return 0 on success, -1 on error
 356  *
 357  * \pre ug_init(), ug_create()
 358  * \post None
 359  * \see ug_destroy_all()
 360  * \remarks None
 361  *
 362  * \par Sample code:
 363  * \code
 364  * #include <ui-gadget.h>
 365  * ...
 366  * // destroy UI gadget instance
 367  * ug_destroy(ug);
 368  * ...
 369  * \endcode
 370  */
 371 int ug_destroy(struct ui_gadget *ug);
 372
 373 /**
 374  * \par Description:
 375  * This function destroys all UI gadgets of an application
 376  *
 377  * \par Purpose:
 378  * This function is used for destroying all UI gadgets. Eventually, state of all UI gadgets would be "Destroyed."
 379  *
 380  * \par Typical use case:
 381  * Application developers who want to destroy loaded UI gadgets could use the function.
 382  *
 383  * \par Method of function operation:
 384  * "Destroy" state operations of all UI gadgets in the UI gadget tree are invoked by post-order traversal.
 385  *
 386  * \par Context of function:
 387  * This function supposed to be called after successful initialization with ug_init()
 388  *
 389  * @return 0 on success, -1 on error
 390  *
 391  * \pre ug_init()
 392  * \post None
 393  * \see ug_destroy()
 394  * \remarks None
 395  *
 396  * \par Sample code:
 397  * \code
 398  * #include <ui-gadget.h>
 399  * ...
 400  * // destroy all UI gadget instances
 401  * ug_destroy_all();
 402  * ...
 403  * \endcode
 404  */
 405 int ug_destroy_all(void);
 406
 407 /**
 408  * \par Description:
 409  * This function gets base layout of the given UI gadget instance
 410  *
 411  * \par Purpose:
 412  * This function is used for getting base layout pointer of given UI gadget instance.
 413  *
 414  * \par Typical use case:
 415  * Anyone who want to get base layout of UI gadget could use the function.
 416  *
 417  * \par Method of function operation:
 418  * This function returns base layout pointer which is created in "Create" operation of the given UI gadget instance.
 419  *
 420  * \par Context of function:
 421  * This function supposed to be called after successful initialization with ug_init() and creation UI gadget with ug_create()
 422  *
 423  * @param[in] ug The UI gadget
 424  * @return The pointer of base layout, NULL on error. The result value is void pointer for supporting both GTK (GtkWidget *) and EFL (Evas_Object *)
 425  *
 426  * \pre ug_init(), ug_create()
 427  * \post None
 428  * \see ug_get_parent_layout()
 429  * \remarks None
 430  *
 431  * \par Sample code:
 432  * \code
 433  * #include <ui-gadget.h>
 434  * ...
 435  * Evas_Object *ly;
 436  * // get a base layout
 437  * ly = (Evas_Object *)ug_get_layout(ug);
 438  * ...
 439  * \endcode
 440  */
 441 void *ug_get_layout(struct ui_gadget *ug);
 442
 443 /**
 444  * \par Description:
 445  * This function gets base layout of parent of the given UI gadget instance
 446  *
 447  * \par Purpose:
 448  * This function is used for getting base layout pointer of parent of the given UI gadget instance.
 449  *
 450  * \par Typical use case:
 451  * Anyone who want to get base layout of UI gadget's parent could use the function.
 452  *
 453  * \par Method of function operation:
 454  * This function returns base layout pointer which is created in "Create" operation of parent of the given UI gadget instance.
 455  *
 456  * \par Context of function:
 457  * This function supposed to be called after successful initialization with ug_init() and creation UI gadget with ug_create()
 458  *
 459  * @param[in] ug The UI gadget
 460  * @return The pointer of base layout, NULL on error. The result value is void pointer for supporting both GTK (GtkWidget *) and EFL (Evas_Object *)
 461  *
 462  * \pre ug_init(), ug_create()
 463  * \post None
 464  * \see ug_get_layout()
 465  * \remarks None
 466  *
 467  * \par Sample code:
 468  * \code
 469  * #include <ui-gadget.h>
 470  * ...
 471  * Evas_Object *ly;
 472  * // get a base layout of parent of the given UI gadget instance
 473  * ly = (Evas_Object *)ug_get_parent_layout(ug);
 474  * ...
 475  * \endcode
 476  */
 477 void *ug_get_parent_layout(struct ui_gadget *ug);
 478
 479 /**
 480  * \par Description:
 481  * This function gets default window
 482  *
 483  * \par Purpose:
 484  * This function is used for getting default window which is registered with ug_init()
 485  *
 486  * \par Typical use case:
 487  * Anyone who want to get default window could use the function.
 488  *
 489  * \par Method of function operation:
 490  * This function returns default window pointer which is registered with ug_init()
 491  *
 492  * \par Context of function:
 493  * This function supposed to be called after successful initialization with ug_init()
 494  *
 495  * @return The pointer of default window, NULL on error. The result value is void pointer for supporting both GTK (GtkWidget *) and EFL (Evas_Object *)
 496  *
 497  * \pre ug_init()
 498  * \post None
 499  * \see None
 500  * \remarks None
 501  *
 502  * \par Sample code:
 503  * \code
 504  * #include <ui-gadget.h>
 505  * ...
 506  * Evas_Object *win;
 507  * // get default window
 508  * win = (Evas_Object *)ug_get_window(ug);
 509  * ...
 510  * \endcode
 511  */
 512 void *ug_get_window(void);
 513
 514 /**
 515  * \par Description:
 516  * This function gets mode of the given UI gadget instance
 517  *
 518  * \par Purpose:
 519  * This function is used for getting mode of the given UI gadget instance. Mode could be UG_MODE_FULLVIEW or UG_MODE_FRAMEVIEW.
 520  *
 521  * \par Typical use case:
 522  * Anyone who want to get mode of UI gadget could use the function.
 523  *
 524  * \par Method of function operation:
 525  * This function returns mode which is registered with ug_create()
 526  *
 527  * \par Context of function:
 528  * This function supposed to be called after successful initialization with ug_init() and creation UI gadget with ug_create()
 529  *
 530  * @param[in] ug The UI gadget
 531  * @return UI gadget mode of the given UI gadget instance (UG_MODE_FULLVIEW | UG_MODE_FRAMEVIEW)
 532  *
 533  * \pre ug_init(), ug_create()
 534  * \post None
 535  * \see enum ug_mode
 536  * \remarks None
 537  *
 538  * \par Sample code:
 539  * \code
 540  * #include <ui-gadget.h>
 541  * ...
 542  * enum ug_mode mode;
 543  * // get mode (UG_MODE_FULLVIEW | UG_MODE_FRAMEVIEW)
 544  * mode = ug_get_mode(ug);
 545  * ...
 546  * \endcode
 547  */
 548 enum ug_mode ug_get_mode(struct ui_gadget *ug);
 549
 550 /**
 551  * \par Description:
 552  * This function propagates the given system event to all UI gadgets
 553  *
 554  * \par Purpose:
 555  * This function is used for propagating the given system event. Available system events are low memory, low battery, language changed, and window rotate event.
 556  *
 557  * \par Typical use case:
 558  * Application developers who want to propagate system event to all UI gadgets could use the function.
 559  *
 560  * \par Method of function operation:
 561  * Event operations of all UI gadgets in the UI gadget tree are invoked by post-order traversal.
 562  *
 563  * \par Context of function:
 564  * This function supposed to be called after successful initialization with ug_init()
 565  *
 566  * @param[in] event UI gadget event. (see enum ug_event)
 567  * @return 0 on success, -1 on error
 568  *
 569  * \pre ug_init()
 570  * \post None
 571  * \see enum ug_event
 572  * \remarks None
 573  *
 574  * \par Sample code:
 575  * \code
 576  * #include <ui-gadget.h>
 577  * ...
 578  * // propagate low battery event to all UI gadget instances
 579  * ug_send_event(UG_EVENT_LOW_BATTERY);
 580  * ...
 581  * \endcode
 582  */
 583 int ug_send_event(enum ug_event event);
 584
 585 /**
 586  * \par Description:
 587  * This function send key event to full view top UI gadget
 588  *
 589  * \par Purpose:
 590  * This function is used for sending key event to full view top UI gadget. Available key events are end event.
 591  *
 592  * \par Typical use case:
 593  * Application developers who want to send key event to full view top UI gadget could use the function.
 594  *
 595  * \par Method of function operation:
 596  * Key event operation of full view top UI gadget in the UI gadget tree are invoked.
 597  *
 598  * \par Context of function:
 599  * This function supposed to be called after successful initialization with ug_init()
 600  *
 601  * @param[in] event UI gadget key event. (see enum ug_key_event)
 602  * @return 0 on success, -1 on error
 603  *
 604  * \pre ug_init()
 605  * \post None
 606  * \see enum ug_key_event
 607  * \remarks None
 608  *
 609  * \par Sample code:
 610  * \code
 611  * #include <ui-gadget.h>
 612  * ...
 613  * // send key event callback to full view top UI gadget instances
 614  * ug_send_key_event(UG_KEY_EVENT_END);
 615  * ...
 616  * \endcode
 617  */
 618 int ug_send_key_event(enum ug_key_event event);
 619
 620 /**
 621  * \par Description:
 622  * This function sends message to the given UI gadget instance
 623  *
 624  * \par Purpose:
 625  * This function is used for sending message to created UI gadget. The message have to be composed with bundle library.
 626  *
 627  * \par Typical use case:
 628  * Anyone who want to send message to created UI gadget.
 629  *
 630  * \par Method of function operation:
 631  * Message operation of given UI gadget instance is invoked.
 632  *
 633  * \par Context of function:
 634  * This function supposed to be called after successful initialization with ug_init() and creation UI gadget with ug_create()
 635  *
 636  * @param[in] ug The UI gadget
 637  * @param[in] msg message to send, which is bundle type (see \ref bundle_PG "bundle programming guide")
 638  * @return 0 on success, -1 on error
 639  *
 640  * \pre ug_init(), ug_create()
 641  * \post None
 642  * \see None
 643  * \remarks After send your message, you have to release it using bundle_free()
 644  *
 645  * \par Sample code:
 646  * \code
 647  * #include <ui-gadget.h>
 648  * ...
 649  * // make a message with bundle
 650  * bundle *b;
 651  * b = bundle_create();
 652  * bundle_add(b, "Content", "Hello");
 653  *
 654  * // send the message
 655  * ug_send_message(ug, b);
 656  *
 657  * // release the message
 658  * bundle_free(b);
 659  * ...
 660  * \endcode
 661  */
 662 int ug_send_message(struct ui_gadget *ug, bundle *msg);
 663
 664 /**
 665  * \par Description:
 666  * This function disable transition effect of the given UI gadget instance
 667  *
 668  * \par Purpose:
 669  * This function is used for disabling transition effect of created UI gadget.
 670  *
 671  * \par Typical use case:
 672  * Anyone who want to disable transition effect of created UI gadget.
 673  *
 674  * \par Method of function operation:
 675  * No transition effect of given UI gadget is invoked
 676  *
 677  * \par Context of function:
 678  * This function supposed to be called after successful initialization with ug_init() and creation UI gadget with ug_create()
 679  *
 680  * @param[in] ug The UI gadget
 681  * @return 0 on success, -1 on error
 682  *
 683  * \pre ug_init(), ug_create()
 684  * \post None
 685  * \see None
 686  * \remarks Before show layout of given UI gadget, ug_disable_effect() should be called.
 687  *
 688  * \par Sample code:
 689  * \code
 690  * #include <ui-gadget.h>
 691  * ...
 692  * static void layout_cb(struct ui_gadget *ug, enum ug_mode mode, void *priv)
 693  * {
 694  * ...
 695  * base = ug_get_layout(ug);
 696  * switch (mode) {
 697  * case UG_MODE_FULLVIEW:
 698  * // disable effect
 699  * ug_disable_effect(ug);
 700  * evas_object_show(base);
 701  * ...
 702  * \endcode
 703  */
 704 int ug_disable_effect(struct ui_gadget *ug);
 705
 706 #ifdef __cplusplus
 707 }
 708 #endif
 709 /**
 710  * @} @} @}
 711  */
 712 #endif                          /* __UI_GADGET_H__ */