include/ui-gadget.h

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