include/widget_app.h

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