livebox/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 #ifndef __DYNAMICBOX_UILITY_H
  18 #define __DYNAMICBOX_UILITY_H
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 #include <Evas.h>
  25
  26 /**
  27  * @file dynamicbox.h
  28  * @brief This file declares API of libdynamicbox library
  29  * @since_tizen 2.3
  30  */
  31
  32 /**
  33  * @addtogroup CAPI_DYNAMICBOX_UTILITY_MODULE
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Definition for COLOR BLOCK.
  39  * @since_tizen 2.3
  40  */
  41 #define DBOX_DESC_TYPE_COLOR "color"
  42
  43 /**
  44  * @brief Definition for TEXT BLOCK.
  45  * @since_tizen 2.3
  46  */
  47 #define DBOX_DESC_TYPE_TEXT "text"
  48
  49 /**
  50  * @brief Definition for IMAGE BLOCK.
  51  * @since_tizen 2.3
  52  */
  53 #define DBOX_DESC_TYPE_IMAGE "image"
  54
  55 /**
  56  * @brief Definition for SIGNAL BLOCK.
  57  * @since_tizen 2.3
  58  */
  59 #define DBOX_DESC_TYPE_SIGNAL "signal"
  60
  61 /**
  62  * @brief Definition for INFO BLOCK.
  63  * @since_tizen 2.3
  64  */
  65 #define DBOX_DESC_TYPE_INFO "info"
  66
  67 /**
  68  * @brief Definition for DRAG BLOCK.
  69  * @since_tizen 2.3
  70  */
  71 #define DBOX_DESC_TYPE_DRAG "drag"
  72
  73 /**
  74  * @brief Definition for SCRIPT SCRIPT.
  75  * @since_tizen 2.3
  76  */
  77 #define DBOX_DESC_TYPE_SCRIPT "script"
  78
  79 /**
  80  * @brief Definition for ACCESSIBILITY INFORMATION BLOCK.
  81  * @since_tizen 2.3
  82  */
  83 #define DBOX_DESC_TYPE_ACCESS "access"
  84
  85 /**
  86  * @brief Definition for accessibility operation.
  87  * @since_tizen 2.3
  88  */
  89 #define DBOX_DESC_TYPE_ACCESS_OPERATION "access,operation"
  90
  91 /**
  92  * @brief Definition for set highlight on specified part.
  93  * @since_tizen 2.3
  94  */
  95 #define DBOX_DESC_DATA_ACCESS_OPERATION_HL_SET "set,hl"
  96
  97 /**
  98  * @brief Definition for remove highlight from specified part.
  99  * @since_tizen 2.3
 100  */
 101 #define DBOX_DESC_DATA_ACCESS_OPERATION_HL_UNSET "unset,hl"
 102
 103 /**
 104  * @brief Definition for move the highlight to next part.
 105  * @since_tizen 2.3
 106  */
 107 #define DBOX_DESC_DATA_ACCESS_OPERATION_HL_NEXT "next,hl"
 108
 109 /**
 110  * @brief Definition for move the highlight to previous part.
 111  * @since_tizen 2.3
 112  */
 113 #define DBOX_DESC_DATA_ACCESS_OPERATION_HL_PREV "prev,hl"
 114
 115 /**
 116  * @brief Definition for reset the chain of accessibility highlight list.
 117  * @since_tizen 2.3
 118  */
 119 #define DBOX_DESC_DATA_ACCESS_OPERATION_RESET "reset,focus"
 120
 121 /**
 122  * @brief Definition for specify the highlight move option.
 123  * @details If the highlight list reaches to the last object, move back to the first object.
 124  * @since_tizen 2.3
 125  */
 126 #define DBOX_DESC_OPTION_ACCESS_HL_LOOP "cycle"
 127
 128 /**
 129  * @brief Definition for specify the highlight move option.
 130  * @details If the highlight list reaches to the last object(or the first object),
 131  * the "prev,hl", "next,hl" will be failed.
 132  * @since_tizen 2.3
 133  */
 134 #define DBOX_DESC_OPTION_ACCESS_HL_NOLOOP "no,cycle"
 135
 136 /**
 137  * @brief Dynamic Box description data handle.
 138  * @since_tizen 2.3
 139  */
 140 struct dynamicbox_desc;
 141
 142 /**
 143  * @brief Updates a description file.
 144  * @since_tizen 2.3
 145  * @remarks Must be used only by Inhouse Dynamic Box.
 146  * @param[in] id Dynamic Box Instance Id
 147  * @param[in] gbar 1 for Glance Bar or 0
 148  * @privlevel public
 149  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 150  * @return Handle of desc instance
 151  * @pre Should be loaded by data-provider-slave.
 152  * @post Should be destroyed(flushed) using dynamicbox_desc_close() API.
 153  * @see dynamicbox_desc_close()
 154  */
 155 extern struct dynamicbox_desc *dynamicbox_desc_open(const char *id, int gbar);
 156
 157 /**
 158  * @brief Completes the description file update.
 159  * @details Only if this API is called, the description data will be applied to the content of Dynamic Box (or GBar).
 160  * @since_tizen 2.3
 161  * @remarks Must be used only by Inhouse Dynamic Box.
 162  * @param[in] handle Handle which is created by dynamicbox_desc_open() function
 163  * @privlevel public
 164  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 165  * @return int type
 166  * @retval #DBOX_STATUS_ERROR_NONE If the flushing description data is successfully done
 167  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER If the given handle is not valid
 168  * @pre Handle must be created by dynamicbox_desc_open()
 169  * @post Handle must not be used after return from this function.
 170  * @see dynamicbox_desc_open()
 171  */
 172 extern int dynamicbox_desc_close(struct dynamicbox_desc *handle);
 173
 174 /**
 175  * @brief Sets the category information of current description data.
 176  * @details Creates a new description block for updating category information of layout object.
 177  * @since_tizen 2.3
 178  * @param[in] handle Handle which is created by dynamicbox_desc_open() function
 179  * @param[in] id Id string of target object
 180  * @param[in] category Category string that will be used by layout object
 181  * @return int type
 182  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid handle
 183  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Memory is not enough to add this block
 184  * @retval index Index(>=0) of added block, which can be used by dynamicbox_desc_set_id()
 185  * @pre Must be called after create a handle using dynamicbox_desc_open()
 186  * @see dynamicbox_desc_set_id()
 187  */
 188 extern int dynamicbox_desc_set_category(struct dynamicbox_desc *handle, const char *id, const char *category);
 189
 190 /**
 191  * @brief Sets the content size.
 192  * @details Sets the content size of layout.
 193  * @since_tizen 2.3
 194  * @param[in] handle Handle which is created by dynamicbox_desc_open() function
 195  * @param[in] id Id string of target object
 196  * @param[in] w Width in pixel
 197  * @param[in] h Height in pixel
 198  * @return int type
 199  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 200  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Not enough memory to add a new block
 201  * @retval index Index(>=0) of added block Successfully added
 202  * @see dynamicbox_desc_open()
 203  * @see dynamicbox_desc_set_id()
 204  */
 205 extern int dynamicbox_desc_set_size(struct dynamicbox_desc *handle, const char *id, int w, int h);
 206
 207 /**
 208  * @brief Sets the target id of the given block.
 209  * @details Only available for the script block.
 210  * @since_tizen 2.3
 211  * @param[in] handle Handle which is created by dynamicbox_desc_open() function
 212  * @param[in] idx Index of target block
 213  * @param[in] id Id String which will be used by other dynamicbox_desc_XXX functions
 214  * @return int type
 215  * @retval #DBOX_STATUS_ERROR_NONE Id is successfully updated for given idx of desc block
 216  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 217  * @retval #DBOX_STATUS_ERROR_NOT_EXIST Given index of desc block is not exists
 218  * @pre Desc block should be exists which has given index "idx".
 219  * @post Specified Id string("id") can be used by other dynamicbox_desc_XXXX functions.
 220  * @see dynamicbox_desc_open()
 221  * @see dynamicbox_desc_set_id()
 222  */
 223 extern int dynamicbox_desc_set_id(struct dynamicbox_desc *handle, int idx, const char *id);
 224
 225 /**
 226  * @brief Adds a new block.
 227  * @since_tizen 2.3
 228  * @param[in] handle Handle which is created by the dynamicbox_desc_open() function
 229  * @param[in] id ID of source script object
 230  * @param[in] type Type (image|text|script|signal|.. etc)
 231  * @param[in] part Target part to update with given content(data)
 232  * @param[in] data Content for specified part
 233  * @param[in] option Option for the block. (script: group, image: option, ...)
 234  * @return Index of current description block
 235  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 236  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Not enough memory to add a new desc block
 237  * @retval index Index(>=0) of added desc block
 238  * @pre Handle must be created using dynamicbox_desc_open.
 239  * @see dynamicbox_desc_set_id()
 240  * @see dynamicbox_desc_del_block()
 241  */
 242 extern int dynamicbox_desc_add_block(struct dynamicbox_desc *handle, const char *id, const char *type, const char *part, const char *data, const char *option);
 243
 244 /**
 245  * @brief Deletes an added block.
 246  * @since_tizen 2.3
 247  * @details If you discard the added desc block, use this API and the index of the created desc block.
 248  * @param[in] handle Handle which is created by dynamicbox_desc_open() function
 249  * @param[in] idx Index of added block, returned from dynamicbox_desc_add_block(), dynamicbox_desc_set_size(), dynamicbox_desc_set_category(), etc
 250  * @return int type
 251  * @retval #DBOX_STATUS_ERROR_NONE Successfully deleted
 252  * @retval #DBOX_STATUS_ERROR_NOT_EXIST Given index of desc block is not exists
 253  * @pre Index must be exists.
 254  * @see dynamicbox_desc_add_block()
 255  * @see dynamicbox_desc_open()
 256  */
 257 extern int dynamicbox_desc_del_block(struct dynamicbox_desc *handle, int idx);
 258
 259 /**
 260  * @brief Creates an Evas_Object to create an elm_win object.
 261  * @details Creating a new Evas_Object using Dynamic Box frame buffer.
 262  * @since_tizen 2.3
 263  * @param[in] id Instance Id
 264  * @param[in] gbar 1 if this object is created for Glance Bar or 0 (for Dynamic Box)
 265  * @privlevel public
 266  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 267  * @return Evas_Object* Evas Object type
 268  * @retval Address Valid evas object
 269  * @retval @c NULL failed to create
 270  */
 271 extern Evas_Object *dynamicbox_get_evas_object(const char *id, int gbar);
 272
 273 /**
 274  * @brief Set extra information for updated content.
 275  * @details
 276  *      If the provider should give some hints to the viewer,
 277  *      such as title, icon and name, this function can set them.
 278  *      provider will send those information to the viewer when the
 279  *      content is updated.
 280  * @since_tizen 2.3
 281  * @remarks This function only works with the buffer type inhouse provider.
 282  * @param[in] id Dynamic Box Instance Id
 283  * @param[in] content Content string that will pass to a Dynamic Box via dynamicbox_create interface when it is re-created.
 284  * @param[in] title Human readable text for accessitility, summarized text for representing the content of a box.
 285  * @param[in] icon Path of icon image file - alternative image content
 286  * @param[in] name Name of a box - alternative text content
 287  * @return int type
 288  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Out of memory
 289  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid parameters
 290  * @retval #DBOX_STATUS_ERROR_FAULT Unrecoverable error
 291  * @retval #DBOX_STATUS_ERROR_NONE Successfully sent
 292  */
 293 extern int dynamicbox_set_extra_info(const char *id, const char *content, const char *title, const char *icon, const char *name);
 294
 295
 296 /**
 297  * @internal
 298  * @brief Structure for a Dynamic Box buffer defined by a provider.
 299  * @since_tizen 2.3
 300  */
 301 struct dynamicbox_buffer;
 302
 303 /**
 304  * @internal
 305  * @brief Return values of dynamicbox programming interfaces: Operation is successfully done.
 306  * @since_tizen 2.3
 307  */
 308 extern const int DONE;
 309
 310 /**
 311  * @internal
 312  * @brief Return values of dynamicbox programming interfaces: Contents are updated.
 313  * @since_tizen 2.3
 314  */
 315 extern const int OUTPUT_UPDATED;
 316
 317 /**
 318  * @internal
 319  * @brief Return values of dynamicbox programming interfaces: Need to call the dynamicbox_need_to_update and dynamicbox_update_content.
 320  * @since_tizen 2.3
 321  */
 322 extern const int NEED_TO_SCHEDULE;
 323
 324 /**
 325  * @internal
 326  * @brief Return values of dynamicbox programming interfaces: Need to do force update.
 327  * @since_tizen 2.3
 328  */
 329 extern const int FORCE_TO_SCHEDULE;
 330
 331 /**
 332  * @internal
 333  * @brief Return values of dynamicbox programming interfaces: Need to create a new instance.
 334  * @since_tizen 2.3
 335  */
 336 extern const int NEED_TO_CREATE;
 337
 338 /**
 339  * @internal
 340  * @brief Return values of dynamicbox programming interfaces: Need to destroy this instance.
 341  * @since_tizen 2.3
 342  */
 343 extern const int NEED_TO_DESTROY;
 344
 345 /**
 346  * @internal
 347  * @brief Return values of dynamicbox programming interfaces: Need to update.
 348  * @since_tizen 2.3
 349  */
 350 extern const int NEED_TO_UPDATE;
 351
 352 /**
 353  * @internal
 354  * @brief Return values of dynamicbox programming interfaces: Using network.
 355  * @since_tizen 2.3
 356  */
 357 extern const int USE_NET;
 358
 359 /**
 360  * @internal
 361  * @brief System event type: System font is changed.
 362  * @since_tizen 2.3
 363  */
 364 extern const int DBOX_SYS_EVENT_FONT_CHANGED;
 365
 366 /**
 367  * @internal
 368  * @brief System event type: System language is changed.
 369  * @since_tizen 2.3
 370  */
 371 extern const int DBOX_SYS_EVENT_LANG_CHANGED;
 372
 373 /**
 374  * @internal
 375  * @brief System event type: System time is changed.
 376  * @since_tizen 2.3
 377  */
 378 extern const int DBOX_SYS_EVENT_TIME_CHANGED;
 379
 380 /**
 381  * @internal
 382  * @brief System event type: Region changed.
 383  * @since_tizen 2.3
 384  */
 385 extern const int DBOX_SYS_EVENT_REGION_CHANGED;
 386
 387 /**
 388  * @internal
 389  * @brief System event type: Accessibility mode changed.
 390  * @since_tizen 2.3
 391  */
 392 extern const int DBOX_SYS_EVENT_TTS_CHANGED;
 393
 394 /**
 395  * @internal
 396  * @brief System event type: Dynamic Box is paused.
 397  * @since_tizen 2.3
 398  */
 399 extern const int DBOX_SYS_EVENT_PAUSED;
 400
 401 /**
 402  * @internal
 403  * @brief System event type: Dynamic Box is resumed.
 404  * @since_tizen 2.3
 405  */
 406 extern const int DBOX_SYS_EVENT_RESUMED;
 407
 408 /**
 409  * @internal
 410  * @brief System event type: MMC Status change event.
 411  * @since_tizen 2.3
 412  */
 413 extern const int DBOX_SYS_EVENT_MMC_STATUS_CHANGED;
 414
 415 /**
 416  * @internal
 417  * @brief System event type: Dynamic Box instance is removed from a viewer.
 418  * @since_tizen 2.3
 419  */
 420 extern const int DBOX_SYS_EVENT_DELETED;
 421
 422 /**
 423  * @internal
 424  * @brief Structure for extra event information for dynamicbox_content_event interface function.
 425  * @since_tizen 2.3
 426  */
 427 #if !defined(__SCRIPT_EVENT_INFO)
 428 #define __SCRIPT_EVENT_INFO
 429
 430 /**
 431  * @internal
 432  * @brief
 433  * Text signal & Content event uses this data structure.
 434  * @since_tizen 2.3
 435  */
 436 struct event_info {
 437         struct _pointer {
 438                 double x; /**< X value of current mouse(touch) position */
 439                 double y; /**< Y value of current mouse(touch) position */
 440                 int down; /**< Is it pressed(1) or not(0) */
 441         } pointer;
 442
 443         struct _part {
 444                 double sx; /**< Pressed object's left top X */
 445                 double sy; /**< Pressed object's left top Y */
 446                 double ex; /**< Pressed object's right bottom X */
 447                 double ey; /**< Pressed object's right bottom Y */
 448         } part;
 449 };
 450 #endif
 451
 452 /**
 453  * @internal
 454  * @brief Notifies the updated content to the provider.
 455  * @details Forcedly notifies the updated contents.
 456  *    This function can be used from async callback function to notify the updated content.
 457  * @since_tizen 2.3
 458  * @param[in] id Instance Id which is passed to you via the first parameter of every dynamicbox_XXXX interface functions
 459  * @param[in] gbar 1 for updating content of Glance Bar or 0(for content of Dynamic Box)
 460  * @return int type
 461  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Not enough memory
 462  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 463  * @retval #DBOX_STATUS_ERROR_IO_ERROR I/O failed, Cannot access given resource file(id)
 464  * @retval #DBOX_STATUS_ERROR_NONE Successfully notified
 465  * @pre This API only can be used after loaded into the data-provider-slave process.
 466  */
 467 extern int dynamicbox_content_is_updated(const char *id, int gbar);
 468
 469 /**
 470  * @internal
 471  * @brief Replaces "\n" (new line character) with &lt;br&gt; tag.
 472  * @details This utility function is used to replace all NEW LINE CHARACTER ("\n") with &lt;br&gt; tag.
 473  * @since_tizen 2.3
 474  * @param[in] str Source string
 475  * @return char * type
 476  * @retval string Allocted in the heap
 477  * @retval @c NULL If it fails to replace string
 478  * @post Returned string must has to be free'd by user manually.
 479  */
 480 extern char *dynamicbox_util_nl2br(const char *str);
 481
 482 /**
 483  * @internal
 484  * @brief Interfaces for direct buffer management (Available only for the GBar area).
 485  * @since_tizen 2.3
 486  */
 487 #ifndef __DBOX_PROVIDER_BUFFER_H
 488 /**
 489  * @internal
 490  * @brief Enumeration for value should be sync'd with provider.
 491  * @since_tizen 2.3
 492  */
 493 enum dbox_buffer_event {
 494         DBOX_BUFFER_EVENT_ENTER, /**< Mouse cursor enter */
 495         DBOX_BUFFER_EVENT_LEAVE, /**< Mouse cursor leave */
 496         DBOX_BUFFER_EVENT_DOWN, /**< Mouse down */
 497         DBOX_BUFFER_EVENT_MOVE, /**< Mouse move */
 498         DBOX_BUFFER_EVENT_UP, /**< Mouse up */
 499
 500         DBOX_BUFFER_EVENT_KEY_DOWN, /**< Key down */
 501         DBOX_BUFFER_EVENT_KEY_UP, /**< Key up */
 502         DBOX_BUFFER_EVENT_KEY_FOCUS_IN, /**< Key focus in */
 503         DBOX_BUFFER_EVENT_KEY_FOCUS_OUT, /**< Key focus out */
 504
 505         DBOX_BUFFER_EVENT_HIGHLIGHT, /**< Accessibility - Highlight */
 506         DBOX_BUFFER_EVENT_HIGHLIGHT_NEXT, /**< Accessibility - Move highlight to next */
 507         DBOX_BUFFER_EVENT_HIGHLIGHT_PREV, /**< Accessibility - Move highlight to prev */
 508         DBOX_BUFFER_EVENT_ACTIVATE, /**< Accessibility - Activate the highlighted object */
 509         DBOX_BUFFER_EVENT_ACTION_UP, /**< Accessibility - Make UP action */
 510         DBOX_BUFFER_EVENT_ACTION_DOWN, /**< Accessibility - Make Down action */
 511         DBOX_BUFFER_EVENT_SCROLL_UP, /**< Accessibility - Scroll up */
 512         DBOX_BUFFER_EVENT_SCROLL_MOVE, /**< Accessibility - Scroll move */
 513         DBOX_BUFFER_EVENT_SCROLL_DOWN, /**< Accessibility - Scroll down */
 514         DBOX_BUFFER_EVENT_UNHIGHLIGHT, /**< Accessibility - Remove highlight */
 515
 516         DBOX_BUFFER_EVENT_ON_HOLD,      /**< To prevent from generating mouse clicked event */
 517         DBOX_BUFFER_EVENT_OFF_HOLD,     /**< Stopped holding. */
 518         DBOX_BUFFER_EVENT_ON_SCROLL, /**< On scrolling */
 519         DBOX_BUFFER_EVENT_OFF_SCROLL, /**< Scrolling stopped */
 520
 521         DBOX_BUFFER_EVENT_ACCESS_VALUE_CHANGE, /**< */
 522         DBOX_BUFFER_EVENT_ACCESS_MOUSE, /**< give mouse event to highlight object */
 523         DBOX_BUFFER_EVENT_ACCESS_BACK, /**< go back to a previous view ex: pop naviframe item */
 524         DBOX_BUFFER_EVENT_ACCESS_OVER, /**< mouse over an object */
 525         DBOX_BUFFER_EVENT_ACCESS_READ, /**< highlight an object */
 526         DBOX_BUFFER_EVENT_ACCESS_ENABLE, /**< enable highlight and read ability */
 527         DBOX_BUFFER_EVENT_ACCESS_DISABLE /**< disable highlight and read ability */
 528 };
 529
 530 /**
 531  * @internal
 532  * @brief Event info
 533  * @since_tizen 2.3
 534  */
 535 struct dbox_buffer_event_data {
 536         enum dbox_buffer_event type; /**< Mouse, Keyboard, Accessibility event type */
 537         double timestamp; /**< Timestamp of events */
 538
 539         union _input_data {
 540                 struct _mouse {
 541                         int x; /**< If the event type is for accessibility or mouse, coordinates of X for pointer */
 542                         int y; /**< If the event type is for accessibility or mouse, coordinates of Y for pointer */
 543                 } pointer;
 544
 545                 struct _access {
 546                         int x; /**< Accessibility event X coordinate */
 547                         int y; /**< Accessibility event Y coordinate */
 548                         unsigned int mouse_type; /**< 0: down, 1: move, 2: up | 0: cur, 1: next, 2: prev, 3: off */
 549                         unsigned int action_type; /**< reserved for protocol */
 550                         unsigned int action_by; /**< reserved for protocol */
 551                         int cycle; /**< reserved for protocol */
 552                 } access;
 553
 554                 unsigned int keycode; /**< If the event type is for keyboard, the value of keycode */
 555         } info;
 556 };
 557 #endif
 558
 559 /**
 560  * @internal
 561  * @brief Acquires a buffer for GBar or DBox, currently only the GBar is supported.
 562  * @since_tizen 2.3
 563  * @param[in] id Instance Id which is passed to you via the first parameter of every dynamicbox_XXXX interface functions
 564  * @param[in] gbar 1 for Glance Bar or 0 for Dynamic Box
 565  * @param[in] width Width in pixel
 566  * @param[in] height Height in pixel
 567  * @param[in] pixels Size of a pixel in bytes
 568  * @param[in] handler Event handling callback
 569  * @param[in] data User data for event handling callback
 570  * @privlevel public
 571  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 572  * @return Buffer handle
 573  * @retval @c NULL Failed to acquire buffer
 574  * @retval handler Handle object
 575  * @pre Given instance must be specify its type as buffer. or this API will be fail.
 576  * @post Allocated buffer object must be released via dynamicbox_release_buffer().
 577  * @see dynamicbox_release_buffer()
 578  */
 579 extern struct dynamicbox_buffer *dynamicbox_acquire_buffer(const char *id, int gbar, int width, int height, int pixels, int auto_align, int (*handler)(struct dynamicbox_buffer *, struct dbox_buffer_event_data *, void *), void *data);
 580
 581 /**
 582  * @internal
 583  * @brief Acquires the Id of Resource (window system).
 584  * @details Only if the provider uses Resource for providing render buffer.
 585  * @since_tizen 2.3
 586  * @remarks Pixmap Id can be destroyed if you call the dynamicbox_release_buffer(). Then this Resource Id is not guaranteed to use.
 587  * @param[in] handle Buffer handle
 588  * @return unsigned int Resource Id
 589  * @retval >0 Resource Id
 590  * @retval 0 Failed to get Resource Id
 591  * @pre The system must be set to use the Resource Id method for content sharing.
 592  * @see dynamicbox_acquire_buffer()
 593  */
 594 extern unsigned int dynamicbox_resource_id(struct dynamicbox_buffer *handle);
 595
 596 /**
 597  * @internal
 598  * @brief Releases the buffer of dynamicbox.
 599  * @since_tizen 2.3
 600  * @param[in] handle Buffer handle
 601  * @privlevel public
 602  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 603  * @return int type
 604  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 605  * @retval #DBOX_STATUS_ERROR_NONE Successfully released
 606  * @pre Handle must be created using dynamicbox_acquire_buffer().
 607  * @see dynamicbox_acquire_buffer()
 608  */
 609 extern int dynamicbox_release_buffer(struct dynamicbox_buffer *handle);
 610
 611 /**
 612  * @internal
 613  * @brief Gets the address of buffer for S/W rendering.
 614  * @details If you try to use this, after dynamicbox_create_hw_buffer(), you will get @c NULL.
 615  * @since_tizen 2.3
 616  * @param[in] handle Buffer handle
 617  * @privlevel public
 618  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 619  * @return void* address of the render buffer
 620  * @retval @c NULL If it falis to get buffer address
 621  * @retval address If it succeed to get the buffer address
 622  * @see dynamicbox_unref_buffer()
 623  */
 624 extern void *dynamicbox_ref_buffer(struct dynamicbox_buffer *handle);
 625
 626 /**
 627  * @internal
 628  * @brief Releases the S/W render buffer.
 629  * @since_tizen 2.3
 630  * @param[in] buffer Address of render buffer
 631  * @privlevel public
 632  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 633  * @return int type
 634  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid handle
 635  * @retval #DBOX_STATUS_ERROR_NONE Successfully unreference
 636  * @pre dynamicbox_ref_buffer() must be called.
 637  * @see dynamicbox_ref_buffer()
 638  */
 639 extern int dynamicbox_unref_buffer(void *buffer);
 640
 641 /**
 642  * @internal
 643  * @brief Synchronizes the updated buffer.
 644  * @details This is only needed for non-H/W accelerated buffer.
 645  * @since_tizen 2.3
 646  * @param[in] handle Buffer handle
 647  * @privlevel public
 648  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 649  * @return int type
 650  * @retval #DBOX_STATUS_ERROR_NONE Successfully sync'd
 651  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 652  * @see dynamicbox_acquire_buffer()
 653  */
 654 extern int dynamicbox_sync_buffer(struct dynamicbox_buffer *handle);
 655
 656 /**
 657  * @internal
 658  * @brief Requests to schedule the update operation to a provider.
 659  * @since_tizen 2.3
 660  * @param[in] id Instance Id which is passed to you via the first parameter of every dynamicbox_XXXX interface functions
 661  * @privlevel public
 662  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 663  * @return If succes returns 0 or return less than 0
 664  * @retval #DBOX_STATUS_ERROR_NONE Successfully triggered
 665  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 666  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Not enough memory
 667  * @retval #DBOX_STATUS_ERROR_NOT_EXIST Given id instance is not exist
 668  */
 669 extern int dynamicbox_request_update(const char *id);
 670
 671 /**
 672  * @internal
 673  * @brief Checks whether the dynamicbox supports H/W acceleration or not.
 674  * @since_tizen 2.3
 675  * @param[in] handle Buffer handle
 676  * @return int type
 677  * @retval 1 If the buffer handle support the H/W acceleration buffer
 678  * @retval 0 If it doesn not supported
 679  * @see dynamicbox_acquire_buffer()
 680  */
 681 extern int dynamicbox_support_hw_buffer(struct dynamicbox_buffer *handle);
 682
 683 /**
 684  * @internal
 685  * @brief Creates the H/W accelerated buffer.
 686  * @since_tizen 2.3
 687  * @param[in] handle Buffer handle
 688  * @privlevel public
 689  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 690  * @return int type
 691  * @retval #DBOX_STATUS_ERROR_ALREADY H/W buffer is already created
 692  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 693  * @retval #DBOX_STATUS_ERROR_NONE Successfully created
 694  * @pre Must be checked whether the H/W buffer is supported or not.
 695  * @post Must be destroyed if it is not necessary.
 696  * @see dynamicbox_support_hw_buffer()
 697  */
 698 extern int dynamicbox_create_hw_buffer(struct dynamicbox_buffer *handle);
 699
 700 /**
 701  * @internal
 702  * @brief Destroys the H/W accelerated buffer.
 703  * @since_tizen 2.3
 704  * @param[in] handle Buffer handle
 705  * @privlevel public
 706  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 707  * @return int type
 708  * @retval #DBOX_STATUS_ERROR_NONE Successfully destroyed
 709  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 710  * @pre Must be created h/w buffer using dynamicbox_create_hw_buffer.
 711  * @see dynamicbox_create_hw_buffer()
 712  */
 713 extern int dynamicbox_destroy_hw_buffer(struct dynamicbox_buffer *handle);
 714
 715 /**
 716  * @internal
 717  * @brief Gets the address of the accelerated H/W buffer.
 718  * @since_tizen 2.3
 719  * @param[in] handle Buffer handle
 720  * @privlevel public
 721  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 722  * @return void* type
 723  * @retval @c NULL Failed to get H/W accelerated buffer address
 724  * @retval addr H/W accelerated buffer address
 725  * @see dynamicbox_create_hw_buffer()
 726  */
 727 extern void *dynamicbox_buffer_hw_buffer(struct dynamicbox_buffer *handle);
 728
 729 /**
 730  * @internal
 731  * @brief Get the stride information from the buffer info
 732  * @since_tizen 2.3
 733  * @param[in] handle Buffer handle
 734  * @return int stride size
 735  * @retval positive_value length of stride
 736  * @return DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid parameter
 737  * @return DBOX_STATUS_ERROR_FAULT Unrecoverable error
 738  * @see dynamicbox_create_hw_buffer()
 739  */
 740 extern int dynamicbox_buffer_stride(struct dynamicbox_buffer *handle);
 741
 742 /**
 743  * @internal
 744  * @brief Pre-processes for rendering content.
 745  * @details This is only needed for accessing H/W accelerated buffer.
 746  * @since_tizen 2.3
 747  * @param[in] handle Buffer handle
 748  * @privlevel public
 749  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 750  * @return int type
 751  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid handle
 752  * @retval #DBOX_STATUS_ERROR_NONE Successfully done
 753  * @post dynamicbox_buffer_post_render must be called after the rendering (accessing buffer) is completed.
 754  * @see dynamicbox_support_hw_buffer()
 755  * @see dynamicbox_buffer_post_render()
 756  */
 757 extern int dynamicbox_buffer_pre_render(struct dynamicbox_buffer *handle);
 758
 759 /**
 760  * @internal
 761  * @brief Post-processes for rendering content.
 762  * @since_tizen 2.3
 763  * @param[in] handle Buffer handle
 764  * @privlevel public
 765  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 766  * @return If succes returns 0 or return less than 0
 767  * @retval #DBOX_STATUS_ERROR_NONE If succeed
 768  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 769  * @pre dynamicbox_buffer_pre_render must be called.
 770  * @see dynamicbox_support_hw_buffer()
 771  * @see dynamicbox_buffer_pre_render()
 772  */
 773 extern int dynamicbox_buffer_post_render(struct dynamicbox_buffer *handle);
 774
 775 /**
 776  * @internal
 777  * @brief Sends a request to the viewer (homescreen) to close the GBar.
 778  * @details Even though you call this function. the homescreen can ignore it.
 779  * @since_tizen 2.3
 780  * @param[in] dboxid Dynamic Box Package Id
 781  * @param[in] id Instance Id which is passed to you via the first parameter of every dynamicbox_XXXX interface functions
 782  * @param[in] reason DBOX_STATUS_ERROR_NONE(0)
 783  * @privlevel public
 784  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 785  * @return int type
 786  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid parameters
 787  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Out of memory
 788  * @retval #DBOX_STATUS_ERROR_FAULT Failed to send a request
 789  * @retval #DBOX_STATUS_ERROR_NONE Successfully requested
 790  */
 791 extern int dynamicbox_request_close_gbar(const char *dboxid, const char *id, int reason);
 792
 793 /**
 794  * @internal
 795  * @brief Send a freeze request to the viewer (homescreen)
 796  * @details
 797  *        The viewer will get this request via event callback.
 798  *        Then it should freeze its scroller or stop moving the dynamicbox.
 799  * @since_tizen 2.3
 800  * @remarks If the viewer doesn't care this request, this will has no effect.
 801  * @param[in] dboxid Dynamic Box Package Id
 802  * @param[in] id Instance Id which is passed to you via the first parameter of every dynamicbox_XXXX interface functions
 803  * @privlevel public
 804  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 805  * @return int type
 806  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid parameters
 807  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Out of memory
 808  * @retval #DBOX_STATUS_ERROR_FAULT Failed to send requet
 809  * @retval #DBOX_STATUS_ERROR_NONE Successfully requested
 810  * @see dynamicbox_release_scroller()
 811  */
 812 extern int dynamicbox_freeze_scroller(const char *dboxid, const char *id);
 813
 814 /**
 815  * @internal
 816  * @brief Send a release request to the viewer (homescreen)
 817  * @details
 818  *        The viewer will get this request via event callback.
 819  *        Then it should release its scroller or continue moving the dynamicbox.
 820  * @since_tizen 2.3
 821  * @remarks If the viewer doesn't care this request, this will has no effect.
 822  * @param[in] dboxid Dynamic Box Package Id
 823  * @param[in] id Instance Id which is passed to you via the first parameter of every dynamicbox_XXXX interface functions
 824  * @privlevel public
 825  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 826  * @return int type
 827  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid parameters
 828  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Out of memory
 829  * @retval #DBOX_STATUS_ERROR_FAULT Failed to send requet
 830  * @retval #DBOX_STATUS_ERROR_NONE Successfully requested
 831  * @see dynamicbox_freeze_scroller()
 832  */
 833 extern int dynamicbox_thaw_scroller(const char *dboxid, const char *id);
 834
 835 /**
 836  * @internal
 837  * @brief Get the configuration value for premultiplied alpha.
 838  * @details
 839  *      If the system uses the premultiplied alpha for content,
 840  *      This function will returns 1.
 841  * @since_tizen 2.3
 842  * @remarks This function only works with the inhouse provider.
 843  * @return status of premultiplied alpha.
 844  * @retval 1 Content rendered with premultiplied alpha.
 845  * @retval 0 Content doesn't rendered with premultiplied alpha.
 846  */
 847 extern int dynamicbox_conf_premultiplied_alpha(void);
 848
 849 /**
 850  * @internal
 851  * @brief Get the configuration value for AUTO Alignment of canvas buffer.
 852  * @details
 853  *      If the UIFW does not support the STRIDE information for rendering frame,
 854  *      This function will returns 1, then the dynamicbox will automatically aligning the buffer.
 855  * @since_tizen 2.3
 856  * @return status of auto alignment.
 857  * @retval 1 Content will be automatically aligned by dynamicbox.
 858  * @retval 0 Content will be aligned by UIFW, using stride information.
 859  */
 860 extern int dynamicbox_conf_auto_align(void);
 861
 862 /**
 863  * @}
 864  */
 865
 866 #ifdef __cplusplus
 867 }
 868 #endif
 869
 870 #endif
 871 /* End of a file */