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