include/widget_app.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.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.apache.org/licenses/LICENSE-2.0
   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 #ifndef __TIZEN_APPFW_WIDGET_APP_H__
  19 #define __TIZEN_APPFW_WIDGET_APP_H__
  20
  21 #include <tizen.h>
  22 #include <app_control.h>
  23 #include <app_common.h>
  24 #include <bundle.h>
  25 #include <widget_errno.h>
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /**
  32  * @addtogroup CAPI_WIDGET_APP_MODULE
  33  * @{
  34  */
  35
  36 /**
  37  * @brief Destroy type of widget instance.
  38  * @since_tizen 2.3.1
  39  */
  40 typedef enum widget_app_destroy_type {
  41         WIDGET_APP_DESTROY_TYPE_DEFAULT = 0x00,   /**< Deleted */
  42         WIDGET_APP_DESTROY_TYPE_UPGRADE = 0x01,   /**< Deleted for upgrading */
  43         WIDGET_APP_DESTROY_TYPE_UNINSTALL = 0x02, /**< Deleted by uninstalling */
  44         WIDGET_APP_DESTROY_TYPE_TERMINATE = 0x03, /**< Deleted for reboot device */
  45         WIDGET_APP_DESTROY_TYPE_FAULT = 0x04,     /**< Deleted by system-fault */
  46         WIDGET_APP_DESTROY_TYPE_TEMPORARY = 0x05, /**< Temporarly deleted, will be created again */
  47         WIDGET_APP_DESTROY_TYPE_UNKNOWN = 0x06    /**< Undefined reason */
  48 } widget_app_destroy_type_e; /**< Delete type */
  49
  50 /**
  51  * @brief The handle for widget class.
  52  * @since_tizen 2.3.1
  53  */
  54 typedef struct _widget_class* widget_class_h;
  55
  56 /**
  57  * @brief The handle for widget context.
  58  * @since_tizen 2.3.1
  59  */
  60 typedef struct _widget_context* widget_context_h;
  61
  62 /**
  63  * @brief Called when the widget instance starts.
  64  * @since_tizen 2.3.1
  65  *
  66  * @details The callback function is called after widget instance is created.
  67  *          In this callback, you can initialize resources for this instance.
  68  *
  69  * @param[in] context The context of widget instance.
  70  * @param[in] content The data set for the previous status
  71  * @param[in] w The pixel value for widget width
  72  * @param[in] h The pixel value for widget height
  73  * @param[in] user_data The user data passed from widget_app_class_create function
  74  *
  75  * @return #WIDGET_ERROR_NONE on success,
  76  *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  77  */
  78 typedef int (*widget_instance_create_cb)(widget_context_h context, bundle *content, int w, int h, void *user_data);
  79
  80 /**
  81  * @brief Called before the widget instance is destroyed.
  82  * @since_tizen 2.3.1
  83  *
  84  * @details The callback function is called before widget instance is destroyed.
  85  *          In this callback, you can finalize resources for this instance.
  86  *          If reason is not #WIDGET_APP_DESTROY_TYPE_DEFAULT, It should store the current status by using incoming bundle.
  87  *
  88  * @param[in] context The context of widget instance.
  89  * @param[in] reason The reason for destruction
  90  * @param[in,out] content The data set to save
  91  * @param[in] user_data The user data passed from widget_app_class_create function
  92  * @remark Note that the parameter 'content' is used to save the status of the widget instance.
  93  *         As a input parameter, content contains the saved status of the widget instance.
  94  *         You can fill the content parameter with the current status in this callback,
  95  *         then the framework will save the content by receiving it as a output parameter.
  96  *         Consequently, you should not use widget_app_context_set_content_info() api in this callback.
  97  *         The content will be overwritten after this callback returns with the 'content' parameter.
  98  *
  99  * @return #WIDGET_ERROR_NONE on success,
 100  *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
 101  */
 102 typedef int (*widget_instance_destroy_cb)(widget_context_h context, widget_app_destroy_type_e reason, bundle *content, void *user_data);
 103
 104 /**
 105  * @brief Called when the widget is invisible.
 106  * @since_tizen 2.3.1
 107  *
 108  * @details The callback function is called when the widget is invisible.
 109  *          The paused instance may be destroyed by framework.
 110  *
 111  * @param[in] context The context of widget instance
 112  * @param[in] user_data The user data passed from widget_app_class_create function
 113  * @return #WIDGET_ERROR_NONE on success,
 114  *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
 115  */
 116 typedef int (*widget_instance_pause_cb)(widget_context_h context, void *user_data);
 117
 118 /**
 119  * @brief Called when the widget is visible.
 120  * @since_tizen 2.3.1
 121  *
 122  * @details The callback function is called when the widget is visible.
 123  *
 124  * @param[in] context The context of widget instance
 125  * @param[in] user_data The user data passed from widget_app_class_create function
 126  * @return #WIDGET_ERROR_NONE on success,
 127  *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
 128  */
 129 typedef int (*widget_instance_resume_cb)(widget_context_h context, void *user_data);
 130
 131 /**
 132  * @brief Called before the widget size is changed.
 133  * @since_tizen 2.3.1
 134  *
 135  * @details The callback function is called before the widget size is changed.
 136  *
 137  * @param[in] context The context of widget instance
 138  * @param[in] w The pixel value for widget width
 139  * @param[in] h The pixel value for widget height
 140  * @param[in] user_data The user data passed from widget_app_class_create function
 141  * @return #WIDGET_ERROR_NONE on success,
 142  *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
 143  */
 144 typedef int (*widget_instance_resize_cb)(widget_context_h context, int w, int h, void *user_data);
 145
 146 /**
 147  * @brief Called when the event for updating widget is received.
 148  * @since_tizen 2.3.1
 149  *
 150  * @details The callback function is called when the event for updating widget is received.
 151  *
 152  * @param[in] context The context of widget instance.
 153  * @param[in] content The data set for updating this widget. It will be provided by requester.
 154  *                    Requester can use widget_service_trigger_update()
 155  * @param[in] force Although the widget is paused, if it is TRUE, the widget can be updated
 156  * @param[in] user_data The user data passed from widget_app_class_create function
 157  * @return #WIDGET_ERROR_NONE on success,
 158  *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
 159  * @see widget_service_trigger_update()
 160  */
 161 typedef int (*widget_instance_update_cb)(widget_context_h context, bundle *content, int force, void *user_data);
 162
 163 /**
 164  * @brief The structure for lifecycle of a widget instance.
 165  * @since_tizen 2.3.1
 166  */
 167 typedef struct
 168 {
 169         widget_instance_create_cb create; /**< The callback function is called after widget instance is created. */
 170         widget_instance_destroy_cb destroy; /**< The callback function is called before widget instance is destroyed. */
 171         widget_instance_pause_cb pause; /**< The callback function is called when the widget is invisible. */
 172         widget_instance_resume_cb resume; /**< The callback function is called when the widget is visible. */
 173         widget_instance_resize_cb resize; /**< The callback function is called before the widget size is changed. */
 174         widget_instance_update_cb update; /**< The callback function is called when the event for updating widget is received. */
 175 } widget_instance_lifecycle_callback_s;
 176
 177 /**
 178  * @brief Called when the application starts.
 179  * @since_tizen 2.3.1
 180  *
 181  * @details The callback function is called before the main loop of the application starts.
 182  *          In this callback, you can initialize resources which can be shared among widget instances.
 183  *          This function should return the handle for widget class so that it will be used for making instances of widget.
 184  *
 185  * @param[in] user_data The user data passed from the callback registration function
 186  * @return The object of widget class
 187  * @see widget_app_main()
 188  * @code
 189  *
 190  * static widget_class_h __widget_app_created(void *user_data)
 191  * {
 192  *     widget_instance_lifecycle_callback_s callback = { .... };
 193  *
 194  *     return widget_app_class_create(callback);
 195  * }
 196  *
 197  * @endcode
 198  */
 199 typedef widget_class_h (*widget_app_create_cb)(void *user_data);
 200
 201 /**
 202  * @brief Called when the application's main loop exits.
 203  * @details This callback function is called once after the main loop of the application exits.
 204  *          You should release the application's resources in this function.
 205  * @since_tizen 2.3.1
 206  *
 207  * @param[in] user_data The user data passed from the callback registration function
 208  * @see widget_app_main()
 209  */
 210 typedef void (*widget_app_terminate_cb)(void *user_data);
 211
 212 /**
 213  * @brief The structure for lifecycle of a widget application.
 214  * @since_tizen 2.3.1
 215  */
 216 typedef struct
 217 {
 218         widget_app_create_cb create; /**< The callback function is called before the main loop of the application starts. */
 219         widget_app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */
 220 } widget_app_lifecycle_callback_s;
 221
 222 /**
 223  * @brief Called for each widget context.
 224  * @since_tizen 2.3.1
 225  *
 226  * @details This function will be called in the function of widget_app_foreach_context repeatedly.
 227  *
 228  * @param[in] context The context for widget instance
 229  * @param[in] data The data for caller
 230  * @return true to continue with the next iteration of the loop,
 231  *         otherwise false to break out of the loop.
 232  * @see widget_app_foreach_context()
 233  */
 234 typedef bool (*widget_context_cb)(widget_context_h context, void *data);
 235
 236 /**
 237  * @brief Runs the main loop of the application until widget_app_exit() is called.
 238  * @since_tizen 2.3.1
 239  *
 240  * @param[in] argc The argument count
 241  * @param[in] argv The argument vector
 242  * @param[in] callback The set of callback functions to handle application events
 243  * @param[in] user_data The user data to be passed to the callback functions
 244  *
 245  * @return #WIDGET_ERROR_NONE on success,
 246  *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
 247  * @retval #WIDGET_ERROR_NONE Successful
 248  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
 249  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 250  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
 251  * @see widget_app_exit()
 252  */
 253 int widget_app_main(int argc, char **argv, widget_app_lifecycle_callback_s *callback, void *user_data);
 254
 255 /**
 256  * @brief Exits the main loop of the application.
 257  * @details The main loop of the application stops and widget_app_terminate_cb() is invoked.
 258  * @since_tizen 2.3.1
 259  *
 260  * @return #WIDGET_ERROR_NONE on success,
 261  *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
 262  * @retval #WIDGET_ERROR_NONE Successful
 263  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 264  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
 265  * @see widget_app_main()
 266  * @see widget_app_terminate_cb()
 267  */
 268 int widget_app_exit(void);
 269
 270 /**
 271  * @brief Finishes context for the widget instance.
 272  * @since_tizen 2.3.1
 273  *
 274  * @param[in] context The context for widget instance
 275  *
 276  * @return #WIDGET_ERROR_NONE on success,
 277  *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
 278  * @retval #WIDGET_ERROR_NONE Successful
 279  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
 280  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 281  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
 282  */
 283 int widget_app_terminate_context(widget_context_h context);
 284
 285 /**
 286  * @brief Retrieves all widget contexts in this application.
 287  * @since_tizen 2.3.1
 288  *
 289  * @param[in] callback The iteration callback function
 290  * @param[in] data The data for the callback function
 291  *
 292  * @return #WIDGET_ERROR_NONE on success,
 293  *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
 294  * @retval #WIDGET_ERROR_NONE Successful
 295  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
 296  * @retval #WIDGET_ERROR_CANCELED The iteration is canceled
 297  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 298  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
 299  * @see widget_app_foreach_context()
 300  */
 301 int widget_app_foreach_context(widget_context_cb callback, void *data);
 302
 303 /**
 304  * @brief Adds the system event handler.
 305  * @since_tizen 2.3.1
 306  *
 307  * @param[out] event_handler The event handler
 308  * @param[in] event_type The system event type. APP_EVENT_DEVICE_ORIENTATION_CHANGED is not supported
 309  * @param[in] callback The callback function
 310  * @param[in] user_data The user data to be passed to the callback function
 311  *
 312  * @return #WIDGET_ERROR_NONE on success,
 313  *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
 314  * @retval #WIDGET_ERROR_NONE Successful
 315  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
 316  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 317  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 318  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
 319  * @see app_event_type_e
 320  * @see app_event_cb()
 321  * @see watch_app_remove_event_handler()
 322  */
 323 int widget_app_add_event_handler(app_event_handler_h *event_handler, app_event_type_e event_type,
 324                                  app_event_cb callback, void *user_data);
 325
 326 /**
 327  * @brief Removes registered event handler.
 328  * @since_tizen 2.3.1
 329  *
 330  * @param[in] event_handler The event handler
 331  *
 332  * @return #WIDGET_ERROR_NONE on success,
 333  *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
 334  * @retval #WIDGET_ERROR_NONE Successful
 335  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
 336  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 337  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
 338  * @see watch_app_add_event_handler()
 339  */
 340 int widget_app_remove_event_handler(app_event_handler_h event_handler);
 341
 342 /**
 343  * @brief Gets a widget instance id.
 344  * @since_tizen 2.3.1
 345  *
 346  * @param[in] context The context for widget instance
 347  *
 348  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 349  * @return Widget ID on success, otherwise NULL
 350  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
 351  * @exception #WIDGET_ERROR_FAULT Unrecoverable error
 352  * @remark You must not free returned Widget ID
 353  * @see get_last_result()
 354  */
 355 const char* widget_app_get_id(widget_context_h context);
 356
 357 /**
 358  * @brief Makes a class for widget instances.
 359  * @since_tizen 2.3.1
 360  *
 361  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 362  * @param[in] callback The set of lifecycle callbacks
 363  * @param[in] user_data The user data to be passed to the callback functions
 364  * @return The new widget class object. NULL on error
 365  * @exception #WIDGET_ERROR_NONE Successfully added
 366  * @exception #WIDGET_ERROR_INVALID_PARAMETER Not supported
 367  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
 368  * @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 369  * @see get_last_result()
 370  */
 371 widget_class_h widget_app_class_create(widget_instance_lifecycle_callback_s callback, void *user_data);
 372
 373 /**
 374  * @brief Sets a tag in the context.
 375  * @since_tizen 2.3.1
 376  *
 377  * @param[in] context The context for widget instance
 378  * @param[in] tag The value to save
 379  *
 380  * @return #WIDGET_ERROR_NONE on success,
 381  *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
 382  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 383  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
 384  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
 385  */
 386 int widget_app_context_set_tag(widget_context_h context, void *tag);
 387
 388 /**
 389  * @brief Gets the tag in the context.
 390  * @since_tizen 2.3.1
 391  *
 392  * @param[in] context The context for widget instance
 393  * @param[out] tag The value to get
 394  * @return #WIDGET_ERROR_NONE on success,
 395  *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
 396  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 397  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
 398  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
 399  */
 400 int widget_app_context_get_tag(widget_context_h context, void **tag);
 401
 402 /**
 403  * @brief Sets the content info to the widget.
 404  * @since_tizen 2.3.1
 405  * @param[in] context The context for widget instance
 406  * @param[in] content_info The data set to save
 407  * @return #WIDGET_ERROR_NONE on success,
 408  *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
 409  * @retval #WIDGET_ERROR_NONE Successfully sent
 410  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 411  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 412  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 413  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
 414  */
 415 int widget_app_context_set_content_info(widget_context_h context, bundle *content_info);
 416
 417 /**
 418  * @brief Sends the title to the widget.
 419  * @since_tizen 2.3.1
 420  * @param[in] context The context for widget instance
 421  * @param[in] title When an accessibility mode is turned on, this string will be read
 422  * @return #WIDGET_ERROR_NONE on success,
 423  *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
 424  * @retval #WIDGET_ERROR_NONE Successfully sent
 425  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 426  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 427  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 428  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
 429  */
 430 int widget_app_context_set_title(widget_context_h context, const char *title);
 431
 432 /**
 433  * @brief Adds an additional widget class for multi-class of widget instantiation.
 434  * @since_tizen 3.0
 435  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 436  * @param[in] widget_class The result of widget_app_class_create()
 437  * @param[in] class_id The class id of provider
 438  * @param[in] callback The set of lifecycle callbacks
 439  * @param[in] user_data The user data to be passed to the callback functions
 440  * @return The new widget class object. NULL on error
 441  * @exception #WIDGET_ERROR_NONE Successfully added
 442  * @exception #WIDGET_ERROR_INVALID_PARAMETER Not supported
 443  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
 444  * @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 445  * @see get_last_result()
 446  */
 447 widget_class_h widget_app_class_add(widget_class_h widget_class, const char *class_id,
 448                 widget_instance_lifecycle_callback_s callback, void *user_data);
 449
 450 /**
 451  * @}
 452  */
 453
 454 #ifdef __cplusplus
 455 }
 456 #endif
 457
 458 #endif /* __TIZEN_APPFW_WIDGET_APP_H__ */