livebox/include/livebox.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 __LIVEBOX_HELPER_H
  18 #define __LIVEBOX_HELPER_H
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 #include <Evas.h>
  25
  26 /**
  27  * @file livebox.h
  28  * @brief This file declares API of liblivebox library
  29  */
  30
  31 /**
  32  * @addtogroup CAPI_LIVEBOX_HELPER_MODULE
  33  * @{
  34  */
  35
  36 /**
  37  * @brief Definition for COLOR BLOCK.
  38  */
  39 #define LB_DESC_TYPE_COLOR "color"
  40
  41 /**
  42  * @brief Definition for TEXT BLOCK.
  43  */
  44 #define LB_DESC_TYPE_TEXT "text"
  45
  46 /**
  47  * @brief Definition for IMAGE BLOCK.
  48  */
  49 #define LB_DESC_TYPE_IMAGE "image"
  50
  51 /**
  52  * @brief Definition for SIGNAL BLOCK.
  53  */
  54 #define LB_DESC_TYPE_SIGNAL "signal"
  55
  56 /**
  57  * @brief Definition for INFO BLOCK.
  58  */
  59 #define LB_DESC_TYPE_INFO "info"
  60
  61 /**
  62  * @brief Definition for DRAG BLOCK.
  63  */
  64 #define LB_DESC_TYPE_DRAG "drag"
  65
  66 /**
  67  * @brief Definition for SCRIPT SCRIPT.
  68  */
  69 #define LB_DESC_TYPE_SCRIPT "script"
  70
  71 /**
  72  * @brief Definition for ACCESSIBILITY INFORMATION BLOCK.
  73  */
  74 #define LB_DESC_TYPE_ACCESS "access"
  75
  76 /**
  77  * @brief Definition for accessibility operation.
  78  */
  79 #define LB_DESC_TYPE_ACCESS_OPERATION   "access,operation"
  80
  81 /**
  82  * @brief Definition for set highlight on specified part.
  83  */
  84 #define LB_DESC_DATA_ACCESS_OPERATION_HL_SET "set,hl"
  85
  86 /**
  87  * @brief Definition for remove highlight from specified part.
  88  */
  89 #define LB_DESC_DATA_ACCESS_OPERATION_HL_UNSET "unset,hl"
  90
  91 /**
  92  * @brief Definition for move the highlight to next part.
  93  */
  94 #define LB_DESC_DATA_ACCESS_OPERATION_HL_NEXT "next,hl"
  95
  96 /**
  97  * @brief Definition for move the highlight to previous part.
  98  */
  99 #define LB_DESC_DATA_ACCESS_OPERATION_HL_PREV "prev,hl"
 100
 101 /**
 102  * @brief Definition for reset the chain of accessibility highlight list.
 103  */
 104 #define LB_DESC_DATA_ACCESS_OPERATION_RESET "reset,focus"
 105
 106 /**
 107  * @brief Definition for specify the highlight move option.
 108  * @details If the highlight list reaches to the last object, move back to the first object.
 109  */
 110 #define LB_DESC_OPTION_ACCESS_HL_LOOP "cycle"
 111
 112 /**
 113  * @brief Definition for specify the highlight move option.
 114  * @details If the highlight list reaches to the last object(or the first object),
 115  * the "prev,hl", "next,hl" will be failed.
 116  */
 117 #define LB_DESC_OPTION_ACCESS_HL_NOLOOP "no,cycle"
 118
 119 /**
 120  * @brief Livebox description data handle.
 121  */
 122 struct livebox_desc;
 123
 124 /**
 125  * @brief Updates a description file.
 126  * @remarks Must be used only by Inhouse livebox.
 127  * @param[in] filename
 128  * @param[in] for_pd
 129  * @privlevel public
 130  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 131  * @return Handle of desc instance
 132  * @pre Should be loaded by data-provider-slave.
 133  * @post Should be destroyed(flushed) using livebox_desc_close() API.
 134  * @see livebox_desc_close()
 135  */
 136 extern struct livebox_desc *livebox_desc_open(const char *filename, int for_pd);
 137
 138 /**
 139  * @brief Completes the description file update.
 140  * @details Only if this API is called, the description data will be applied to the content of livebox (or PD).
 141  * @remarks Must be used only by Inhouse livebox.
 142  * @param[in] handle Handle which is created by livebox_desc_open() function
 143  * @privlevel public
 144  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 145  * @return int type
 146  * @retval #LB_STATUS_SUCCESS If the flushing description data is successfully done
 147  * @retval #LB_STATUS_ERROR_INVALID If the given handle is not valid
 148  * @pre Handle must be created by livebox_desc_open()
 149  * @post Handle must not be used after return from this function.
 150  * @see livebox_desc_open()
 151  */
 152 extern int livebox_desc_close(struct livebox_desc *handle);
 153
 154 /**
 155  * @brief Sets the category information of current description data.
 156  * @details Creates a new description block for updating category information of layout object.
 157  * @param[in] handle Handle which is created by livebox_desc_open() function
 158  * @param[in] id Id string of target object
 159  * @param[in] category Category string that will be used by layout object
 160  * @privlevel N/P
 161  * @return int type
 162  * @retval #LB_STATUS_ERROR_INVALID Invalid handle
 163  * @retval #LB_STATUS_ERROR_MEMORY Memory is not enough to add this block
 164  * @retval index Index(>=0) of added block, which can be used by livebox_desc_set_id()
 165  * @pre Must be called after create a handle using livebox_desc_open()
 166  * @see livebox_desc_set_id()
 167  */
 168 extern int livebox_desc_set_category(struct livebox_desc *handle, const char *id, const char *category);
 169
 170 /**
 171  * @brief Sets the content size.
 172  * @details Sets the content size of layout.
 173  * @param[in] handle Handle which is created by livebox_desc_open() function
 174  * @param[in] id Id string of target object
 175  * @param[in] w Width in pixel
 176  * @param[in] h Height in pixel
 177  * @privlevel N/P
 178  * @return int type
 179  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 180  * @retval #LB_STATUS_ERROR_MEMORY Not enough memory to add a new block
 181  * @retval index Index(>=0) of added block Successfully added
 182  * @see livebox_desc_open()
 183  * @see livebox_desc_set_id()
 184  */
 185 extern int livebox_desc_set_size(struct livebox_desc *handle, const char *id, int w, int h);
 186
 187 /**
 188  * @brief Sets the target id of the given block.
 189  * @details Only available for the script block.
 190  * @param[in] handle Handle which is created by livebox_desc_open() function
 191  * @param[in] idx Index of target block
 192  * @param[in] id Id String which will be used by other livebox_desc_XXX functions
 193  * @privlevel N/P
 194  * @return int type
 195  * @retval #LB_STATUS_SUCCESS Id is successfully updated for given idx of desc block
 196  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 197  * @retval #LB_STATUS_ERROR_NOT_EXIST Given index of desc block is not exists
 198  * @pre Desc block should be exists which has given index "idx".
 199  * @post Specified Id string("id") can be used by other livebox_desc_XXXX functions.
 200  * @see livebox_desc_open()
 201  * @see livebox_desc_set_id()
 202  */
 203 extern int livebox_desc_set_id(struct livebox_desc *handle, int idx, const char *id);
 204
 205 /**
 206  * @brief Adds a new block.
 207  * @param[in] handle Handle which is created by the livebox_desc_open() function
 208  * @param[in] id ID of source script object
 209  * @param[in] type Type (image|text|script|signal|.. etc)
 210  * @param[in] part Target part to update with given content(data)
 211  * @param[in] data Content for specified part
 212  * @param[in] option Option for the block. (script: group, image: option, ...)
 213  * @privlevel N/P
 214  * @return Index of current description block
 215  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 216  * @retval #LB_STATUS_ERROR_MEMORY Not enough memory to add a new desc block
 217  * @retval index Index(>=0) of added desc block
 218  * @pre Handle must be created using livebox_desc_open.
 219  * @see livebox_desc_set_id()
 220  * @see livebox_desc_del_block()
 221  */
 222 extern int livebox_desc_add_block(struct livebox_desc *handle, const char *id, const char *type, const char *part, const char *data, const char *option);
 223
 224 /**
 225  * @brief Deletes an added block.
 226  * @details If you discard the added desc block, use this API and the index of the created desc block.
 227  * @param[in] handle Handle which is created by livebox_desc_open() function
 228  * @param[in] idx Index of added block, returned from livebox_desc_add_block(), livebox_desc_set_size(), livebox_desc_set_category(), etc
 229  * @privlevel N/P
 230  * @return int type
 231  * @retval #LB_STATUS_SUCCESS Successfully deleted
 232  * @retval #LB_STATUS_ERROR_NOT_EXIST Given index of desc block is not exists
 233  * @pre Index must be exists.
 234  * @see livebox_desc_add_block()
 235  * @see livebox_desc_open()
 236  */
 237 extern int livebox_desc_del_block(struct livebox_desc *handle, int idx);
 238
 239 /**
 240  * @brief Creates an Evas_Object to create an elm_win object.
 241  * @details Creating a new Evas_Object using livebox frame buffer.
 242  * @param[in] id Instance Id
 243  * @param[in] is_pd 1 if this object is created for PD or 0 (for LB)
 244  * @privlevel public
 245  * @privilege %http://tizen.org/privilege/core/dynamicbox.provider
 246  * @return Evas_Object* Evas Object type
 247  * @retval Address Valid evas object
 248  * @retval @c NULL failed to create
 249  */
 250 extern Evas_Object *livebox_get_evas_object(const char *id, int is_pd);
 251
 252 /**
 253  * @brief Set extra information for updated content.
 254  * @details
 255  *      If the provider should give some hints to the viewer,
 256  *      such as title, icon and name, this function can set them.
 257  *      provider will send those information to the viewer when the
 258  *      content is updated.
 259  * @remarks This function only works with the buffer type inhouse provider.
 260  * @param[in] id Livebox Instance Id
 261  * @param[in] content Content string that will pass to a livebox via livebox_create interface when it is re-created.
 262  * @param[in] title Human readable text for accessitility, summarized text for representing the content of a box.
 263  * @param[in] icon Path of icon image file - alternative image content
 264  * @param[in] name Name of a box - alternative text content
 265  * @privlevel N/P
 266  * @return int type
 267  * @retval #LB_STATUS_ERROR_MEMORY Out of memory
 268  * @retval #LB_STATUS_ERROR_INVALID Invalid parameters
 269  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error
 270  * @retval #LB_STATUS_SUCCESS Successfully sent
 271  */
 272 extern int livebox_set_extra_info(const char *id, const char *content, const char *title, const char *icon, const char *name);
 273
 274 /**
 275  * @}
 276  */
 277
 278 #ifdef __cplusplus
 279 }
 280 #endif
 281
 282 #endif
 283 /* End of a file */