include/widget_internal.h

   1 /*
   2  * Copyright 2013  Samsung Electronics Co., Ltd
   3  *
   4  * Licensed under the Flora License, Version 1.1 (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://floralicense.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  * Export by widget_service
  19  */
  20 #include <widget_buffer.h>
  21 #include <widget_script.h>
  22
  23 #ifndef __WIDGET_UILITY_INTERNAL_H
  24 #define __WIDGET_UILITY_INTERNAL_H
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31  * @file widget_internal.h
  32  * @brief This file declares API of libwidget library
  33  * @since_tizen 2.3.1
  34  */
  35
  36 /**
  37  * @addtogroup CAPI_WIDGET_UTILITY_MODULE
  38  * @{
  39  */
  40
  41 /**
  42  * @internal
  43  * @brief Definition for COLOR BLOCK.
  44  * @since_tizen 2.3.1
  45  */
  46 #define WIDGET_DESC_TYPE_COLOR "color"
  47
  48 /**
  49  * @internal
  50  * @brief Definition for TEXT BLOCK.
  51  * @since_tizen 2.3.1
  52  */
  53 #define WIDGET_DESC_TYPE_TEXT "text"
  54
  55 /**
  56  * @internal
  57  * @brief Definition for IMAGE BLOCK.
  58  * @since_tizen 2.3.1
  59  */
  60 #define WIDGET_DESC_TYPE_IMAGE "image"
  61
  62 /**
  63  * @internal
  64  * @brief Definition for SIGNAL BLOCK.
  65  * @since_tizen 2.3.1
  66  */
  67 #define WIDGET_DESC_TYPE_SIGNAL "signal"
  68
  69 /**
  70  * @internal
  71  * @brief Definition for INFO BLOCK.
  72  * @since_tizen 2.3.1
  73  */
  74 #define WIDGET_DESC_TYPE_INFO "info"
  75
  76 /**
  77  * @internal
  78  * @brief Definition for DRAG BLOCK.
  79  * @since_tizen 2.3.1
  80  */
  81 #define WIDGET_DESC_TYPE_DRAG "drag"
  82
  83 /**
  84  * @internal
  85  * @brief Definition for SCRIPT SCRIPT.
  86  * @since_tizen 2.3.1
  87  */
  88 #define WIDGET_DESC_TYPE_SCRIPT "script"
  89
  90 /**
  91  * @internal
  92  * @brief Definition for ACCESSIBILITY INFORMATION BLOCK.
  93  * @since_tizen 2.3.1
  94  */
  95 #define WIDGET_DESC_TYPE_ACCESS "access"
  96
  97 /**
  98  * @internal
  99  * @brief Definition for accessibility operation.
 100  * @since_tizen 2.3.1
 101  */
 102 #define WIDGET_DESC_TYPE_ACCESS_OPERATION "access,operation"
 103
 104 /**
 105  * @internal
 106  * @brief Definition for set highlight on specified part.
 107  * @since_tizen 2.3.1
 108  */
 109 #define WIDGET_DESC_DATA_ACCESS_OPERATION_HL_SET "set,hl"
 110
 111 /**
 112  * @internal
 113  * @brief Definition for remove highlight from specified part.
 114  * @since_tizen 2.3.1
 115  */
 116 #define WIDGET_DESC_DATA_ACCESS_OPERATION_HL_UNSET "unset,hl"
 117
 118 /**
 119  * @internal
 120  * @brief Definition for move the highlight to next part.
 121  * @since_tizen 2.3.1
 122  */
 123 #define WIDGET_DESC_DATA_ACCESS_OPERATION_HL_NEXT "next,hl"
 124
 125 /**
 126  * @internal
 127  * @brief Definition for move the highlight to previous part.
 128  * @since_tizen 2.3.1
 129  */
 130 #define WIDGET_DESC_DATA_ACCESS_OPERATION_HL_PREV "prev,hl"
 131
 132 /**
 133  * @internal
 134  * @brief Definition for reset the chain of accessibility highlight list.
 135  * @since_tizen 2.3.1
 136  */
 137 #define WIDGET_DESC_DATA_ACCESS_OPERATION_RESET "reset,focus"
 138
 139 /**
 140  * @internal
 141  * @brief Definition for specify the highlight move option.
 142  * @details If the highlight list reaches to the last object, move back to the first object.
 143  * @since_tizen 2.3.1
 144  */
 145 #define WIDGET_DESC_OPTION_ACCESS_HL_LOOP "cycle"
 146
 147 /**
 148  * @internal
 149  * @brief Definition for specify the highlight move option.
 150  * @details If the highlight list reaches to the last object(or the first object),
 151  * the "prev,hl", "next,hl" will be failed.
 152  * @since_tizen 2.3.1
 153  */
 154 #define WIDGET_DESC_OPTION_ACCESS_HL_NOLOOP "no,cycle"
 155
 156 /**
 157  * @internal
 158  * @brief Return values of widget programming interfaces for the plug-in type widgets
 159  * @since_tizen 2.3.1
 160  * @feature http://tizen.org/feature/shell.appwidget
 161  */
 162 typedef enum widget_api_result {
 163         WIDGET_DONE = 0x00, /**< Operation is successfully done. */
 164         WIDGET_OUTPUT_UPDATED = 0x01,  /**< Contents are updated. */
 165         WIDGET_NEED_TO_SCHEDULE = 0x02, /**< Need to call the widget_need_to_update and widget_update_content. */
 166         WIDGET_NEED_TO_CREATE = 0x04, /**< Need to create a new instance. */
 167         WIDGET_NEED_TO_DESTROY = 0x08, /**< Need to destroy this instance. */
 168         WIDGET_FORCE_TO_SCHEDULE = 0x10, /**< Need to do force update. */
 169 } widget_api_result_e;
 170
 171 /**
 172  * @internal
 173  * @brief System event type for the plug-in type widgets
 174  * @since_tizen 2.3.1
 175  * @feature http://tizen.org/feature/shell.appwidget
 176  */
 177 typedef enum widget_system_event {
 178         WIDGET_SYS_EVENT_FONT_CHANGED = 0x01, /**< System font is changed. */
 179         WIDGET_SYS_EVENT_LANG_CHANGED = 0x02, /**< System language is changed. */
 180         WIDGET_SYS_EVENT_TIME_CHANGED = 0x04, /**< System time is changed. */
 181         WIDGET_SYS_EVENT_REGION_CHANGED = 0x08, /**< Region changed. */
 182         WIDGET_SYS_EVENT_TTS_CHANGED = 0x10, /**< Accessibility mode changed. */
 183         WIDGET_SYS_EVENT_PAUSED = 0x0100, /**< widget is paused. */
 184         WIDGET_SYS_EVENT_RESUMED = 0x0200, /**< widget is resumed. */
 185         WIDGET_SYS_EVENT_MMC_STATUS_CHANGED = 0x0400, /**< MMC Status change event. */
 186         WIDGET_SYS_EVENT_DELETED = 0x0800, /**< widget instance is removed from a viewer. */
 187 } widget_system_event_e;
 188
 189 /**
 190  * @internal
 191  * @brief widget description data handle.
 192  * @since_tizen 2.3.1
 193  */
 194 typedef struct widget_desc *widget_desc_h;
 195
 196 /**
 197  * @internal
 198  * @brief Flush Callback for snapshot window
 199  * @since_tizen 2.3.1
 200  */
 201 typedef void (*widget_flush_cb)(void *snapshot_window, const char *id, int status, void *data);
 202
 203 /**
 204  * @internal
 205  * @brief Updates a description file.
 206  * @since_tizen 2.3.1
 207  * @remarks Must be used only by Inhouse widget.
 208  * @param[in] id widget Instance Id
 209  * @param[in] gbar 1 for Glance Bar or 0
 210  * @privlevel public
 211  * @privilege %http://tizen.org/privilege/widget.provider
 212  * @feature http://tizen.org/feature/shell.appwidget
 213  * @return Handle of desc instance
 214  * @retval @c NULL Failed to create a desc instance, get_last_result() will returns reason of failure
 215  * @pre Should be loaded by data-provider-slave.
 216  * @post Should be destroyed(flushed) using widget_desc_close() API.
 217  * @see widget_desc_close()
 218  */
 219 extern widget_desc_h widget_desc_open(const char *id, int gbar);
 220
 221 /**
 222  * @internal
 223  * @brief Completes the description file update.
 224  * @details Only if this API is called, the description data will be applied to the content of widget (or GBar).
 225  * @since_tizen 2.3.1
 226  * @remarks Must be used only by Inhouse widget.
 227  * @param[in] handle Handle which is created by widget_desc_open() function
 228  * @privlevel public
 229  * @privilege %http://tizen.org/privilege/widget.provider
 230  * @feature http://tizen.org/feature/shell.appwidget
 231  * @return #WIDGET_ERROR_NONE on success,
 232  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 233  * @retval #WIDGET_ERROR_NONE If the flushing description data is successfully done
 234  * @retval #WIDGET_ERROR_INVALID_PARAMETER If the given handle is not valid
 235  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 236  * @pre Handle must be created by widget_desc_open()
 237  * @post Handle must not be used after return from this function.
 238  * @see widget_desc_open()
 239  */
 240 extern int widget_desc_close(widget_desc_h handle);
 241
 242 /**
 243  * @internal
 244  * @brief Sets the category information of current description data.
 245  * @details Creates a new description block for updating category information of layout object.
 246  * @since_tizen 2.3.1
 247  * @param[in] handle Handle which is created by widget_desc_open() function
 248  * @param[in] id Id string of target object
 249  * @param[in] category Category string that will be used by layout object
 250  * @return #WIDGET_ERROR_NONE on success,
 251  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 252  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid handle
 253  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Memory is not enough to add this block
 254  * @retval index Index(>=0) of added block, which can be used by widget_desc_set_id()
 255  * @pre Must be called after create a handle using widget_desc_open()
 256  * @see widget_desc_set_id()
 257  */
 258 extern int widget_desc_set_category(widget_desc_h handle, const char *id, const char *category);
 259
 260 /**
 261  * @internal
 262  * @brief Sets the content size.
 263  * @details Sets the content size of layout.
 264  * @since_tizen 2.3.1
 265  * @param[in] handle Handle which is created by widget_desc_open() function
 266  * @param[in] id Id string of target object
 267  * @param[in] w Width in pixel
 268  * @param[in] h Height in pixel
 269  * @return #WIDGET_ERROR_NONE on success,
 270  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 271  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 272  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Not enough memory to add a new block
 273  * @retval index Index(>=0) of added block Successfully added
 274  * @see widget_desc_open()
 275  * @see widget_desc_set_id()
 276  */
 277 extern int widget_desc_set_size(widget_desc_h handle, const char *id, int w, int h);
 278
 279 /**
 280  * @internal
 281  * @brief Sets the target id of the given block.
 282  * @details Only available for the script block.
 283  * @since_tizen 2.3.1
 284  * @param[in] handle Handle which is created by widget_desc_open() function
 285  * @param[in] idx Index of target block
 286  * @param[in] id Id String which will be used by other widget_desc_XXX functions
 287  * @return #WIDGET_ERROR_NONE on success,
 288  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 289  * @retval #WIDGET_ERROR_NONE Id is successfully updated for given idx of desc block
 290  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 291  * @retval #WIDGET_ERROR_NOT_EXIST Given index of desc block is not exists
 292  * @pre Desc block should be exists which has given index "idx".
 293  * @post Specified Id string("id") can be used by other widget_desc_XXXX functions.
 294  * @see widget_desc_open()
 295  * @see widget_desc_set_id()
 296  */
 297 extern int widget_desc_set_id(widget_desc_h handle, int idx, const char *id);
 298
 299 /**
 300  * @internal
 301  * @brief Adds a new block.
 302  * @since_tizen 2.3.1
 303  * @param[in] handle Handle which is created by the widget_desc_open() function
 304  * @param[in] id ID of source script object
 305  * @param[in] type Type (image|text|script|signal|.. etc)
 306  * @param[in] part Target part to update with given content(data)
 307  * @param[in] data Content for specified part
 308  * @param[in] option Option for the block. (script: group, image: option, ...)
 309  * @return Index of current description block
 310  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 311  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Not enough memory to add a new desc block
 312  * @retval index Index(>=0) of added desc block
 313  * @pre Handle must be created using widget_desc_open.
 314  * @see widget_desc_set_id()
 315  * @see widget_desc_del_block()
 316  */
 317 extern int widget_desc_add_block(widget_desc_h handle, const char *id, const char *type, const char *part, const char *data, const char *option);
 318
 319 /**
 320  * @internal
 321  * @brief Deletes an added block.
 322  * @since_tizen 2.3.1
 323  * @details If you discard the added desc block, use this API and the index of the created desc block.
 324  * @param[in] handle Handle which is created by widget_desc_open() function
 325  * @param[in] idx Index of added block, returned from widget_desc_add_block(), widget_desc_set_size(), widget_desc_set_category(), etc
 326  * @return #WIDGET_ERROR_NONE on success,
 327  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 328  * @retval #WIDGET_ERROR_NONE Successfully deleted
 329  * @retval #WIDGET_ERROR_NOT_EXIST Given index of desc block is not exists
 330  * @pre Index must be exists.
 331  * @see widget_desc_add_block()
 332  * @see widget_desc_open()
 333  */
 334 extern int widget_desc_del_block(widget_desc_h handle, int idx);
 335
 336 /**
 337  * @internal
 338  * @brief Structure for a widget buffer defined by a provider.
 339  * @since_tizen 2.3.1
 340  */
 341 typedef struct widget_buffer *widget_buffer_h;
 342
 343 /**
 344  * @internal
 345  * @brief Return values of widget programming interfaces: Using network.
 346  * @since_tizen 2.3.1
 347  */
 348 extern const int WIDGET_USE_NET;
 349
 350 /**
 351  * @internal
 352  * @brief Notifies the updated content to the provider.
 353  * @details Forcedly notifies the updated contents.
 354  *    This function can be used from async callback function to notify the updated content.
 355  * @since_tizen 2.3.1
 356  * @param[in] id Instance Id which is passed to you via the first parameter of every widget_XXXX interface functions
 357  * @param[in] gbar 1 for updating content of Glance Bar or 0(for content of widget)
 358  * @return #WIDGET_ERROR_NONE on success,
 359  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 360  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Not enough memory
 361  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 362  * @retval #WIDGET_ERROR_IO_ERROR I/O failed, Cannot access given resource file(id)
 363  * @retval #WIDGET_ERROR_NONE Successfully notified
 364  * @pre This API only can be used after loaded into the data-provider-slave process.
 365  */
 366 extern int widget_content_is_updated(const char *id, int gbar);
 367
 368 /**
 369  * @internal
 370  * @brief Acquires a buffer for GBar or widget, currently only the GBar is supported.
 371  * @since_tizen 2.3.1
 372  * @param[in] id Instance Id which is passed to you via the first parameter of every widget_XXXX interface functions
 373  * @param[in] gbar 1 for Glance Bar or 0 for widget
 374  * @param[in] width Width in pixel
 375  * @param[in] height Height in pixel
 376  * @param[in] pixels Size of a pixel in bytes
 377  * @param[in] handler Event handling callback
 378  * @param[in] data User data for event handling callback
 379  * @privlevel public
 380  * @privilege %http://tizen.org/privilege/widget.provider
 381  * @feature http://tizen.org/feature/shell.appwidget
 382  * @return Buffer handle
 383  * @retval @c NULL Failed to acquire buffer, get_last_result() will returns reason of failure.
 384  * @retval handler Handle object
 385  * @pre Given instance must be specify its type as buffer. or this API will be fail.
 386  * @post Allocated buffer object must be released via widget_release_buffer().
 387  * @see widget_release_buffer()
 388  */
 389 extern widget_buffer_h widget_create_buffer(const char *id, int gbar, int auto_align, int (*handler)(widget_buffer_h, widget_buffer_event_data_t, void *), void *data);
 390
 391 /**
 392  * @internal
 393  * @brief Acquire a buffer for GBar or widget.
 394  * @since_tizen 2.3.1
 395  * @param[in] handle Buffer handle
 396  * @param[in] idx Index of a buffer, WIDGET_PRIMARY_BUFFER is used for accessing primary buffer
 397  * @param[in] width Width of a buffer
 398  * @param[in] height Height of a buffer
 399  * @param[in] pixels Pixel size in byte
 400  * @privlevel public
 401  * @privilege %http://tizen.org/privilege/widget.provider
 402  * @feature http://tizen.org/feature/shell.appwidget
 403  * @return int status
 404  * @retval #WIDGET_ERROR_NONE Successfully allocated
 405  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
 406  * @retval #WIDGET_ERROR_FAULT Unrecoverable error occurred
 407  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 408  * @pre widget_create_buffer() must be called
 409  * @see widget_create_buffer()
 410  * @see widget_release_buffer()
 411  */
 412 extern int widget_viewer_acquire_buffer(widget_buffer_h handle, int idx, int width, int height, int pixels);
 413
 414 /**
 415  * @internal
 416  * @brief Acquires the Id of Resource (window system).
 417  * @details Only if the provider uses Resource for providing render buffer.
 418  * @since_tizen 2.3.1
 419  * @remarks Pixmap Id can be destroyed if you call the widget_release_buffer(). Then this Resource Id is not guaranteed to use.
 420  * @param[in] handle Buffer handle
 421  * @param[in] idx Index of a buffer, #c WIDGET_PRIMARY_BUFFER is used for accessing the primary buffer
 422  * @return unsigned int Resource Id
 423  * @retval >0 Resource Id
 424  * @retval 0 Failed to get Resource Id
 425  * @pre The system must be set to use the Resource Id method for content sharing.
 426  * @see widget_acquire_buffer()
 427  */
 428 extern unsigned int widget_viewer_get_resource_id(widget_buffer_h handle, int idx);
 429
 430 /**
 431  * @internal
 432  * @brief Releases the buffer of widget.
 433  * @since_tizen 2.3.1
 434  * @param[in] handle Buffer handle
 435  * @param[in] idx Index of a buffer, #c WIDGET_PRIMARY_BUFFER is used for accessing the primary buffer
 436  * @privlevel public
 437  * @privilege %http://tizen.org/privilege/widget.provider
 438  * @feature http://tizen.org/feature/shell.appwidget
 439  * @return int status
 440  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 441  * @retval #WIDGET_ERROR_NONE Successfully released
 442  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 443  * @pre Handle must be created using widget_acquire_buffer().
 444  * @see widget_acquire_buffer()
 445  */
 446 extern int widget_viewer_release_buffer(widget_buffer_h handle, int idx);
 447
 448 /**
 449  * @internal
 450  * @brief Destroy a buffer of widget
 451  * @since_tizen 2.3.1
 452  * @param[in] handle buffer handle
 453  * @privlevel public
 454  * @privilege %http://tizen.org/privilege/widget.provider
 455  * @feature http://tizen.org/feature/shell.appwidget
 456  * @return int status
 457  * @retval #WIDGET_ERROR_INVALID_PARAMTER Invalid argument
 458  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 459  * @retval #WIDGET_ERROR_NONE Successfully destroyed
 460  * @see widget_create_buffer()
 461  */
 462 extern int widget_destroy_buffer(widget_buffer_h handle);
 463
 464 /**
 465  * @internal
 466  * @brief Gets the address of buffer for S/W rendering.
 467  * @details If you try to use this, after widget_create_hw_buffer(), you will get @c NULL.
 468  *          This API only be used for primary buffer. you cannot access the extra buffer
 469  * @since_tizen 2.3.1
 470  * @param[in] handle Buffer handle
 471  * @privlevel public
 472  * @privilege %http://tizen.org/privilege/widget.provider
 473  * @feature http://tizen.org/feature/shell.appwidget
 474  * @return void* address of the render buffer
 475  * @retval @c NULL If it falis to get buffer address, get_last_result() will returns reason of failure.
 476  * @retval address If it succeed to get the buffer address
 477  * @see widget_unref_buffer()
 478  */
 479 extern void *widget_ref_buffer(widget_buffer_h handle);
 480
 481 /**
 482  * @internal
 483  * @brief Releases the S/W render buffer.
 484  * @since_tizen 2.3.1
 485  * @param[in] buffer Address of render buffer
 486  * @privlevel public
 487  * @privilege %http://tizen.org/privilege/widget.provider
 488  * @feature http://tizen.org/feature/shell.appwidget
 489  * @return #WIDGET_ERROR_NONE on success,
 490  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 491  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid handle
 492  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 493  * @retval #WIDGET_ERROR_NONE Successfully unreference
 494  * @pre widget_ref_buffer() must be called.
 495  * @see widget_ref_buffer()
 496  */
 497 extern int widget_unref_buffer(void *buffer);
 498
 499 /**
 500  * @internal
 501  * @brief Synchronizes the updated buffer.
 502  * @details This is only needed for non-H/W accelerated buffer.
 503  *          This API is only supported for primary buffer (#c WIDGET_PRIMARY_BUFFER)
 504  * @since_tizen 2.3.1
 505  * @param[in] handle Buffer handle
 506  * @privlevel public
 507  * @privilege %http://tizen.org/privilege/widget.provider
 508  * @feature http://tizen.org/feature/shell.appwidget
 509  * @return #WIDGET_ERROR_NONE on success,
 510  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 511  * @retval #WIDGET_ERROR_NONE Successfully sync'd
 512  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 513  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 514  * @see widget_acquire_buffer()
 515  */
 516 extern int widget_viewer_sync_buffer(widget_buffer_h handle);
 517
 518 /**
 519  * @internal
 520  * @brief Checks whether the widget supports H/W acceleration or not.
 521  *        This API is only supported for primary buffer (#c WIDGET_PRIMARY_BUFFER)
 522  * @since_tizen 2.3.1
 523  * @param[in] handle Buffer handle
 524  * @return int type
 525  * @retval 1 If the buffer handle support the H/W acceleration buffer
 526  * @retval 0 If it doesn not supported
 527  * @see widget_acquire_buffer()
 528  */
 529 extern int widget_support_hw_buffer(widget_buffer_h handle);
 530
 531 /**
 532  * @internal
 533  * @brief Creates the H/W accelerated buffer.
 534  *        This API is only supported for primary buffer (#c WIDGET_PRIMARY_BUFFER)
 535  * @since_tizen 2.3.1
 536  * @param[in] handle Buffer handle
 537  * @privlevel public
 538  * @privilege %http://tizen.org/privilege/widget.provider
 539  * @feature http://tizen.org/feature/shell.appwidget
 540  * @return #WIDGET_ERROR_NONE on success,
 541  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 542  * @retval #WIDGET_ERROR_ALREADY_EXIST H/W buffer is already created
 543  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 544  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 545  * @retval #WIDGET_ERROR_NONE Successfully created
 546  * @pre Must be checked whether the H/W buffer is supported or not.
 547  * @post Must be destroyed if it is not necessary.
 548  * @see widget_support_hw_buffer()
 549  */
 550 extern int widget_create_hw_buffer(widget_buffer_h handle);
 551
 552 /**
 553  * @internal
 554  * @brief Destroys the H/W accelerated buffer.
 555  *        This API is only supported for primary buffer (#c WIDGET_PRIMARY_BUFFER)
 556  * @since_tizen 2.3.1
 557  * @param[in] handle Buffer handle
 558  * @privlevel public
 559  * @privilege %http://tizen.org/privilege/widget.provider
 560  * @feature http://tizen.org/feature/shell.appwidget
 561  * @return #WIDGET_ERROR_NONE on success,
 562  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 563  * @retval #WIDGET_ERROR_NONE Successfully destroyed
 564  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 565  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 566  * @pre Must be created h/w buffer using widget_create_hw_buffer.
 567  * @see widget_create_hw_buffer()
 568  */
 569 extern int widget_destroy_hw_buffer(widget_buffer_h handle);
 570
 571 /**
 572  * @internal
 573  * @brief Gets the address of the accelerated H/W buffer.
 574  *        This API is only supported for primary buffer (#c WIDGET_PRIMARY_BUFFER)
 575  * @since_tizen 2.3.1
 576  * @param[in] handle Buffer handle
 577  * @privlevel public
 578  * @privilege %http://tizen.org/privilege/widget.provider
 579  * @feature http://tizen.org/feature/shell.appwidget
 580  * @return void* type
 581  * @retval @c NULL Failed to get H/W accelerated buffer address, get_last_result() will returns reason of failure.
 582  * @retval addr H/W accelerated buffer address
 583  * @see widget_create_hw_buffer()
 584  */
 585 extern void *widget_buffer_hw_buffer(widget_buffer_h handle);
 586
 587 /**
 588  * @internal
 589  * @brief Get the stride information from the buffer info
 590  *        This API is only supported for primary buffer (#c WIDGET_PRIMARY_BUFFER)
 591  * @since_tizen 2.3.1
 592  * @param[in] handle Buffer handle
 593  * @return int stride size
 594  * @retval positive_value length of stride
 595  * @return #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
 596  * @return #WIDGET_ERROR_FAULT Unrecoverable error
 597  * @see widget_create_hw_buffer()
 598  */
 599 extern int widget_buffer_stride(widget_buffer_h handle);
 600
 601 /**
 602  * @internal
 603  * @brief Pre-processes for rendering content.
 604  * @details This is only needed for accessing H/W accelerated buffer.
 605  * @since_tizen 2.3.1
 606  * @param[in] handle Buffer handle
 607  * @privlevel public
 608  * @privilege %http://tizen.org/privilege/widget.provider
 609  * @feature http://tizen.org/feature/shell.appwidget
 610  * @return #WIDGET_ERROR_NONE on success,
 611  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 612  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid handle
 613  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 614  * @retval #WIDGET_ERROR_NONE Successfully done
 615  * @post widget_buffer_post_render must be called after the rendering (accessing buffer) is completed.
 616  * @see widget_support_hw_buffer()
 617  * @see widget_buffer_post_render()
 618  */
 619 extern int widget_buffer_pre_render(widget_buffer_h handle);
 620
 621 /**
 622  * @internal
 623  * @brief Post-processes for rendering content.
 624  * @since_tizen 2.3.1
 625  * @param[in] handle Buffer handle
 626  * @privlevel public
 627  * @privilege %http://tizen.org/privilege/widget.provider
 628  * @feature http://tizen.org/feature/shell.appwidget
 629  * @return If succes returns 0 or return less than 0
 630  * @retval #WIDGET_ERROR_NONE If succeed
 631  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 632  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 633  * @pre widget_buffer_pre_render must be called.
 634  * @see widget_support_hw_buffer()
 635  * @see widget_buffer_pre_render()
 636  */
 637 extern int widget_buffer_post_render(widget_buffer_h handle);
 638
 639 /**
 640  * @internal
 641  * @brief Sends a request to the viewer (homescreen) to close the GBar.
 642  * @details Even though you call this function. the homescreen can ignore it.
 643  * @since_tizen 2.3.1
 644  * @param[in] widgetid widget Package Id
 645  * @param[in] id Instance Id which is passed to you via the first parameter of every widget_XXXX interface functions
 646  * @param[in] reason #WIDGET_ERROR_NONE(0)
 647  * @privlevel public
 648  * @privilege %http://tizen.org/privilege/widget.provider
 649  * @feature http://tizen.org/feature/shell.appwidget
 650  * @return #WIDGET_ERROR_NONE on success,
 651  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 652  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 653  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameters
 654  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 655  * @retval #WIDGET_ERROR_FAULT Failed to send a request
 656  * @retval #WIDGET_ERROR_NONE Successfully requested
 657  */
 658 extern int widget_request_close_glance_bar(const char *widgetid, const char *id, int reason);
 659
 660 /**
 661  * @internal
 662  * @brief Create a snapshot window
 663  * @details
 664  *         If you want create a snapshot image of contents, create this snapshot window
 665  *         But it will not renders object asynchronously,
 666  *         So you have to render the objects immediately, the delayed rendering object will not be on the canvas
 667  *         After flush it to a file.
 668  * @since_tizen 2.3.1
 669  * @param[in] id
 670  * @param[in] size_type
 671  * @return void* window
 672  * @retval @c NULL failed to create a snapshot window, get_last_result() will returns reason of failure.
 673  * @retval Object window object (ex, elementary window)
 674  * @see widget_snapshot_window_flush()
 675  */
 676 extern void *widget_snapshot_window_add(const char *id, int size_type);
 677
 678 /**
 679  * @internal
 680  * @brief Flush to a file for snapshot window
 681  * @since_tizen 2.3.1
 682  * @param[in] snapshot_win Snapshot window
 683  * @param[in] timeout After this, the image file will be created
 684  * @param[in] flush_cb Right after flush an image file, this callback will be called
 685  * @param[in] data Callback data for flush_cb
 686  * @return int status
 687  * @retval #WIDGET_ERROR_NONE Successfully flushed (flush timer added)
 688  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid paramter
 689  * @retval #WIDGET_ERROR_FAULT Failed to create a flush timer
 690  * @see widget_snapshot_window_add()
 691  */
 692 extern int widget_snapshot_window_flush(void *snapshot_win, double timeout, widget_flush_cb flush_cb, void *data);
 693
 694 /**
 695  * @internal
 696  * @brief Sending the updated event to the viewer
 697  * @since_tizen 2.3.1
 698  * @param[in] handle widget Buffer Handle
 699  * @param[in] idx Index of a buffer
 700  * @privlevel public
 701  * @privilege %http://tizen.org/privilege/widget.provider
 702  * @feature http://tizen.org/feature/shell.appwidget
 703  * @return int status
 704  * @retval #WIDGET_ERROR_NONE Successfully sent
 705  */
 706 extern int widget_send_updated_by_idx(widget_buffer_h handle, int idx);
 707
 708 /**
 709  * @internal
 710  * @brief Set extra information for updated content.
 711  * @details
 712  *      If the provider should give some hints to the viewer,
 713  *      such as title, icon and name, this function can set them.
 714  *      provider will send those information to the viewer when the
 715  *      content is updated.
 716  * @since_tizen 2.3.1
 717  * @privlevel N/P
 718  * @feature http://tizen.org/feature/shell.appwidget
 719  * @remarks This function only works with the buffer type inhouse provider.
 720  * @param[in] id widget Instance Id
 721  * @param[in] content Content string that will pass to a widget via widget_create interface when it is re-created.
 722  * @param[in] title Human readable text for accessibility, summarized text for representing the content of a box.
 723  * @param[in] icon Path of icon image file - alternative image content
 724  * @param[in] name Name of a box - alternative text content
 725  * @return #WIDGET_ERROR_NONE on success,
 726  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 727  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 728  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameters
 729  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
 730  * @retval #WIDGET_ERROR_NONE Successfully sent
 731  * TODO: plug-in type
 732  */
 733 extern int widget_set_extra_info(const char *id, const char *content, const char *title, const char *icon, const char *name);
 734
 735 /**
 736  * @internal
 737  * @brief Send a freeze request to the viewer (homescreen)
 738  * @details
 739  *        The viewer will get this request via event callback.
 740  *        Then it should freeze its scroller or stop moving the widget.
 741  * @since_tizen 2.3.1
 742  * @remarks If the viewer doesn't care this request, this will has no effect.
 743  * @param[in] widgetid widget Package Id
 744  * @param[in] id Instance Id which is passed to you via the first parameter of every widget_XXXX interface functions
 745  * @privlevel public
 746  * @privilege %http://tizen.org/privilege/widget.provider
 747  * @feature http://tizen.org/feature/shell.appwidget
 748  * @return #WIDGET_ERROR_NONE on success,
 749  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 750  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameters
 751  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 752  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 753  * @retval #WIDGET_ERROR_FAULT Failed to send requet
 754  * @retval #WIDGET_ERROR_NONE Successfully requested
 755  * @see widget_release_scroller()
 756  * TODO: plug-in type
 757  */
 758 extern int widget_freeze_scroller(const char *widgetid, const char *id);
 759
 760 /**
 761  * @inernal
 762  * @brief Send a release request to the viewer (homescreen)
 763  * @details
 764  *        The viewer will get this request via event callback.
 765  *        Then it should release its scroller or continue moving the widget.
 766  * @since_tizen 2.3.1
 767  * @remarks If the viewer doesn't care this request, this will has no effect.
 768  * @param[in] widgetid widget Package Id
 769  * @param[in] id Instance Id which is passed to you via the first parameter of every widget_XXXX interface functions
 770  * @privlevel public
 771  * @privilege %http://tizen.org/privilege/widget.provider
 772  * @feature http://tizen.org/feature/shell.appwidget
 773  * @return #WIDGET_ERROR_NONE on success,
 774  *          otherwise an error code (see #WIDGET_ERROR_XXX) on failure
 775  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 776  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameters
 777  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 778  * @retval #WIDGET_ERROR_FAULT Failed to send requet
 779  * @retval #WIDGET_ERROR_NONE Successfully requested
 780  * @see widget_freeze_scroller()
 781  * TODO: plug-in type
 782  */
 783 extern int widget_thaw_scroller(const char *widgetid, const char *id);
 784
 785 /**
 786  */
 787 extern int widget_del_pre_callback(widget_pre_callback_e type, widget_pre_callback_t cb, void *data);
 788
 789 /**
 790  */
 791 extern int widget_add_pre_callback(widget_pre_callback_e type, widget_pre_callback_t cb, void *data);
 792
 793 /**
 794  * @}
 795  */
 796
 797 #ifdef __cplusplus
 798 }
 799 #endif
 800
 801 #endif
 802 /* End of a file */