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