include/widget_app.h

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