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 /**
  25  * @file dynamicbox.h
  26  * @brief This file declares API of libdynamicbox library
  27  * @since_tizen 2.3
  28  */
  29
  30 /**
  31  * @addtogroup CAPI_DYNAMICBOX_UTILITY_MODULE
  32  * @{
  33  */
  34
  35 /**
  36  * @brief Event information type for dynamicbox_content_event()
  37  * @details definition is in dynamicbox_service.h file
  38  * @since_tizen 2.3
  39  */
  40 typedef struct dynamicbox_event_info *dynamicbox_event_info_t;
  41
  42 /**
  43  * @brief Creates an Object to create an elm_win object.
  44  * @details Creating a new Object using Dynamic Box frame buffer.
  45  * @since_tizen 2.3
  46  * @param[in] id Instance Id
  47  * @param[in] gbar 1 if this object is created for Glance Bar or 0 (for Dynamic Box)
  48  * @privlevel public
  49  * @privilege %http://developer.samsung.com/tizen/privilege/dynamicbox.provider
  50  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
  51  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
  52  * @return void* Object type
  53  * @retval Address Valid evas object
  54  * @retval @c NULL failed to create, dynamicbox_last_status() will returns reason of failure
  55  */
  56 extern void *dynamicbox_get_evas_object(const char *id, int gbar);
  57
  58 /**
  59  * @brief Set extra information for updated content.
  60  * @details
  61  *      If the provider should give some hints to the viewer,
  62  *      such as title, icon and name, this function can set them.
  63  *      provider will send those information to the viewer when the
  64  *      content is updated.
  65  * @since_tizen 2.3
  66  * @remarks This function only works with the buffer type inhouse provider.
  67  * @param[in] id Dynamic Box Instance Id
  68  * @param[in] content Content string that will pass to a Dynamic Box via dynamicbox_create interface when it is re-created.
  69  * @param[in] title Human readable text for accessitility, summarized text for representing the content of a box.
  70  * @param[in] icon Path of icon image file - alternative image content
  71  * @param[in] name Name of a box - alternative text content
  72  * @return int type
  73  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
  74  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
  75  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Out of memory
  76  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid parameters
  77  * @retval #DBOX_STATUS_ERROR_FAULT Unrecoverable error
  78  * @retval #DBOX_STATUS_ERROR_NONE Successfully sent
  79  */
  80 extern int dynamicbox_set_extra_info(const char *id, const char *content, const char *title, const char *icon, const char *name);
  81
  82 /**
  83  * @brief Return values of dynamicbox programming interfaces: Operation is successfully done.
  84  * @since_tizen 2.3
  85  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
  86  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
  87  */
  88 extern const int DBOX_DONE;
  89
  90 /**
  91  * @brief Return values of dynamicbox programming interfaces: Contents are updated.
  92  * @since_tizen 2.3
  93  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
  94  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
  95  */
  96 extern const int DBOX_OUTPUT_UPDATED;
  97
  98 /**
  99  * @brief Return values of dynamicbox programming interfaces: Need to call the dynamicbox_need_to_update and dynamicbox_update_content.
 100  * @since_tizen 2.3
 101  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 102  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 103  */
 104 extern const int DBOX_NEED_TO_SCHEDULE;
 105
 106 /**
 107  * @internal
 108  * @brief Return values of dynamicbox programming interfaces: Need to create a new instance.
 109  * @since_tizen 2.3
 110  */
 111 extern const int DBOX_NEED_TO_CREATE;
 112
 113 /**
 114  * @brief Return values of dynamicbox programming interfaces: Need to do force update.
 115  * @since_tizen 2.3
 116  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 117  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 118  */
 119 extern const int DBOX_FORCE_TO_SCHEDULE;
 120
 121 /**
 122  * @brief Return values of dynamicbox programming interfaces: Need to destroy this instance.
 123  * @since_tizen 2.3
 124  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 125  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 126  */
 127 extern const int DBOX_NEED_TO_DESTROY;
 128
 129 /**
 130  * @brief Return values of dynamicbox programming interfaces: Need to update.
 131  * @since_tizen 2.3
 132  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 133  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 134  */
 135 extern const int DBOX_NEED_TO_UPDATE;
 136
 137 /**
 138  * @brief System event type: System font is changed.
 139  * @since_tizen 2.3
 140  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 141  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 142  */
 143 extern const int DBOX_SYS_EVENT_FONT_CHANGED;
 144
 145 /**
 146  * @brief System event type: System language is changed.
 147  * @since_tizen 2.3
 148  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 149  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 150  */
 151 extern const int DBOX_SYS_EVENT_LANG_CHANGED;
 152
 153 /**
 154  * @brief System event type: System time is changed.
 155  * @since_tizen 2.3
 156  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 157  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 158  */
 159 extern const int DBOX_SYS_EVENT_TIME_CHANGED;
 160
 161 /**
 162  * @brief System event type: MMC Status change event.
 163  * @since_tizen 2.3
 164  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 165  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 166  */
 167 extern const int DBOX_SYS_EVENT_MMC_STATUS_CHANGED;
 168
 169 /**
 170  * @brief System event type: Region changed.
 171  * @since_tizen 2.3
 172  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 173  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 174  */
 175 extern const int DBOX_SYS_EVENT_REGION_CHANGED;
 176
 177 /**
 178  * @brief System event type: Accessibility mode changed.
 179  * @since_tizen 2.3
 180  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 181  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 182  */
 183 extern const int DBOX_SYS_EVENT_TTS_CHANGED;
 184
 185 /**
 186  * @brief System event type: Dynamic Box is paused.
 187  * @since_tizen 2.3
 188  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 189  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 190  */
 191 extern const int DBOX_SYS_EVENT_PAUSED;
 192
 193 /**
 194  * @brief System event type: Dynamic Box is resumed.
 195  * @since_tizen 2.3
 196  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 197  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 198  */
 199 extern const int DBOX_SYS_EVENT_RESUMED;
 200
 201 /**
 202  * @brief System event type: Dynamic Box instance is removed from a viewer.
 203  * @since_tizen 2.3
 204  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 205  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 206  */
 207 extern const int DBOX_SYS_EVENT_DELETED;
 208
 209 /**
 210  * @brief Requests to schedule the update operation to a provider.
 211  *        Your DBox will get the update request, if the @a id is specified, specific box only will get it.
 212  * @since_tizen 2.3
 213  * @param[in] id Instance Id which is passed to you via the first parameter of every dynamicbox_XXXX interface functions
 214  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 215  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 216  * @return If succes returns 0 or return less than 0
 217  * @retval #DBOX_STATUS_ERROR_NONE Successfully triggered
 218  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 219  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Not enough memory
 220  * @retval #DBOX_STATUS_ERROR_NOT_EXIST Given id instance is not exist
 221  * @retval #DBOX_STATUS_ERROR_PERMISSION_DENIED Permission denied
 222  * @retval #DBOX_STATUS_ERROR_DISABLED in case of direct request for updating is disabled
 223  */
 224 extern int dynamicbox_request_update(const char *id);
 225
 226 /**
 227  * @brief Send a freeze request to the viewer (homescreen)
 228  * @details
 229  *        The viewer will get this request via event callback.
 230  *        Then it should freeze its scroller or stop moving the dynamicbox.
 231  * @since_tizen 2.3
 232  * @remarks If the viewer doesn't care this request, this will has no effect.
 233  * @param[in] dboxid Dynamic Box Package Id
 234  * @param[in] id Instance Id which is passed to you via the first parameter of every dynamicbox_XXXX interface functions
 235  * @privlevel public
 236  * @privilege %http://developer.samsung.com/tizen/privilege/dynamicbox.provider
 237  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 238  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 239  * @return int type
 240  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid parameters
 241  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Out of memory
 242  * @retval #DBOX_STATUS_ERROR_PERMISSION_DENIED Permission denied
 243  * @retval #DBOX_STATUS_ERROR_FAULT Failed to send requet
 244  * @retval #DBOX_STATUS_ERROR_NONE Successfully requested
 245  * @see dynamicbox_release_scroller()
 246  */
 247 extern int dynamicbox_freeze_scroller(const char *dboxid, const char *id);
 248
 249 /**
 250  * @brief Send a release request to the viewer (homescreen)
 251  * @details
 252  *        The viewer will get this request via event callback.
 253  *        Then it should release its scroller or continue moving the dynamicbox.
 254  * @since_tizen 2.3
 255  * @remarks If the viewer doesn't care this request, this will has no effect.
 256  * @param[in] dboxid Dynamic Box Package Id
 257  * @param[in] id Instance Id which is passed to you via the first parameter of every dynamicbox_XXXX interface functions
 258  * @privlevel public
 259  * @privilege %http://developer.samsung.com/tizen/privilege/dynamicbox.provider
 260  * @feature http://developer.samsung.com/tizen/feature/samsung_extension
 261  * @feature http://developer.samsung.com/tizen/feature/in_house/shell.appwidget
 262  * @return int type
 263  * @retval #DBOX_STATUS_ERROR_PERMISSION_DENIED Permission denied
 264  * @retval #DBOX_STATUS_ERROR_INVALID_PARAMETER Invalid parameters
 265  * @retval #DBOX_STATUS_ERROR_OUT_OF_MEMORY Out of memory
 266  * @retval #DBOX_STATUS_ERROR_FAULT Failed to send requet
 267  * @retval #DBOX_STATUS_ERROR_NONE Successfully requested
 268  * @see dynamicbox_freeze_scroller()
 269  */
 270 extern int dynamicbox_thaw_scroller(const char *dboxid, const char *id);
 271
 272 /**
 273  * @}
 274  */
 275
 276 #ifdef __cplusplus
 277 }
 278 #endif
 279
 280 #endif
 281 /* End of a file */