include/ui-gadget-module.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_MODULE_H__
  22 #define __UI_GADGET_MODULE_H__
  23
  24 /**
  25  * @defgroup    UI_Gadget_For_Developer Developer API Reference Guide
  26  * @ingroup     UI_Gadget
  27  * @brief       A module to develop a UI gadget. Callees (UI gadgets) uses this modules and APIs. (callee -> caller)
  28  *
  29  * @section Header To Use Them:
  30  * @code
  31  * #include <ui-gadget-module.h>
  32  * @endcode
  33  */
  34
  35 /**
  36  * @addtogroup UI_Gadget_For_Developer
  37  * @{
  38  */
  39
  40 #include <bundle.h>
  41 #include "ui-gadget.h"
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 /**
  48  * UI gadget module operation type
  49  * @see @ref lifecycle_sec
  50  */
  51 struct ug_module_ops {
  52         /** create operation */
  53         void *(*create) (struct ui_gadget *ug, enum ug_mode mode, bundle *data,
  54                                         void *priv);
  55         /** start operation */
  56         void (*start) (struct ui_gadget *ug, bundle *data, void *priv);
  57         /** pause operation */
  58         void (*pause) (struct ui_gadget *ug, bundle *data, void *priv);
  59         /** resume operation */
  60         void (*resume) (struct ui_gadget *ug, bundle *data, void *priv);
  61         /** destroy operation */
  62         void (*destroy) (struct ui_gadget *ug, bundle *data, void *priv);
  63         /** message operation */
  64         void (*message) (struct ui_gadget *ug, bundle *msg, bundle *data, void *priv);
  65         /** event operation */
  66         void (*event) (struct ui_gadget *ug, enum ug_event event, bundle *data,
  67                                 void *priv);
  68         /** key event operation */
  69         void (*key_event) (struct ui_gadget *ug, enum ug_key_event event,
  70                                         bundle *data, void *priv);
  71         /** destroying operation */
  72         void (*destroying) (struct ui_gadget *ug, bundle *data, void *priv);
  73         /** reserved operations */
  74         void *reserved[3];
  75
  76         /** private data */
  77         void *priv;
  78
  79         /** option */
  80         enum ug_option opt;
  81 };
  82
  83 /**
  84  * \par Description:
  85  * This function makes a request that caller of the given UI gadget instance destroys the instance.
  86  * It just makes a request, but not destroys UI gadget
  87  *
  88  * \par Purpose:
  89  * This function is used for sending a request that caller of the given UI gadget instance destroys the instance.
  90  *
  91  * \par Typical use case:
  92  * UI gadget developer who want to send a request that caller of the given UI gadget instance destroys the instance could use the function.
  93  *
  94  * \par Method of function operation:
  95  * Destroy callback which is registered by caller with ug_create() is invoked.
  96  *
  97  * \par Context of function:
  98  * This function supposed to be called in the created UI gadget.
  99  *
 100  * @param[in] ug the UI gadget
 101  * @return 0 on success, -1 on error
 102  *
 103  * \pre None
 104  * \post None
 105  * \see None
 106  * \remarks The API just makes a request, but not destroys UI gadget
 107  *
 108  * \par Sample code:
 109  * \code
 110  * #include <ui-gadget-module.h>
 111  * ...
 112  * // send a "destroy me" request
 113  * ug_destroy_me(ug);
 114  * ...
 115  * \endcode
 116  */
 117 int ug_destroy_me(struct ui_gadget *ug);
 118
 119 /**
 120  * \par Description:
 121  * This function sends result to caller of the given UI gadget instance.
 122  *
 123  * \par Purpose:
 124  * This function is used for sending result to caller of the given UI gadget instance. The result have to be composed with bundle library.
 125  *
 126  * \par Typical use case:
 127  * UI gadget developer who want to send result to caller of the given UI gadget instance could use the function.
 128  *
 129  * \par Method of function operation:
 130  * Result callback which is registered by caller with ug_create() is invoked.
 131  *
 132  * \par Context of function:
 133  * This function supposed to be called in the created UI gadget.
 134  *
 135  * @param[in] ug the UI gadget
 136  * @param[in] result the result, which is bundle type (see \ref bundle_PG "bundle programming guide")
 137  * @return 0 on success, -1 on error
 138  *
 139  * \pre None
 140  * \post None
 141  * \see None
 142  * \remarks After send your message, you have to release it using bundle_free()
 143  *
 144  * \par Sample code:
 145  * \code
 146  * #include <ui-gadget-module.h>
 147  * ...
 148  * // make a result with bundle
 149  * bundle *b;
 150  * b = bundle_create();
 151  * bundle_add(b, "Content", "Hello");
 152  *
 153  * // send the result
 154  * ug_send_result(ug, b);
 155  *
 156  * // release the result
 157  * bundle_free(b);
 158  * ...
 159  * \endcode
 160  */
 161 int ug_send_result(struct ui_gadget *ug, bundle *result);
 162
 163 #ifdef __cplusplus
 164 }
 165 #endif
 166 /**
 167  * @}
 168  */
 169 #endif                          /* __UI_GADGET_MODULE_H__ */