include/widget.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 <widget_service.h>
  18
  19 #ifndef __WIDGET_UILITY_H
  20 #define __WIDGET_UILITY_H
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /**
  27  * @file widget.h
  28  * @brief This file declares API of libwidget library
  29  * @since_tizen 2.4
  30  */
  31
  32 /**
  33  * @addtogroup CAPI_WIDGET_UTILITY_MODULE
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Event information type for widget_content_event()
  39  * @details definition is in widget_service.h file
  40  * @since_tizen 2.4
  41  */
  42 typedef struct widget_event_info *widget_event_info_t;
  43
  44 /**
  45  * @brief Creates an Object to create an elm_win object.
  46  * @details Creating a new Object using widget frame buffer.
  47  * @since_tizen 2.4
  48  * @param[in] id Instance Id
  49  * @param[in] gbar 1 if this object is created for Glance Bar or 0 (for widget)
  50  * @privlevel public
  51  * @privilege %http://tizen.org/privilege/widget.provider
  52  * @feature http://tizen.org/feature/shell.appwidget
  53  * @return void* Object type
  54  * @retval Address Valid evas object
  55  * @retval @c NULL failed to create, widget_last_status() will returns reason of failure
  56  */
  57 extern void *widget_get_evas_object(const char *id, int gbar);
  58
  59 /**
  60  * @brief Set extra information for updated content.
  61  * @details
  62  *      If the provider should give some hints to the viewer,
  63  *      such as title, icon and name, this function can set them.
  64  *      provider will send those information to the viewer when the
  65  *      content is updated.
  66  * @since_tizen 2.4
  67  * @privlevel N/P
  68  * @feature http://tizen.org/feature/shell.appwidget
  69  * @remarks This function only works with the buffer type inhouse provider.
  70  * @param[in] id widget Instance Id
  71  * @param[in] content Content string that will pass to a widget via widget_create interface when it is re-created.
  72  * @param[in] title Human readable text for accessitility, summarized text for representing the content of a box.
  73  * @param[in] icon Path of icon image file - alternative image content
  74  * @param[in] name Name of a box - alternative text content
  75  * @return #WIDGET_STATUS_ERROR_NONE on success,
  76  *          otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
  77  * @retval #WIDGET_STATUS_ERROR_OUT_OF_MEMORY Out of memory
  78  * @retval #WIDGET_STATUS_ERROR_INVALID_PARAMETER Invalid parameters
  79  * @retval #WIDGET_STATUS_ERROR_FAULT Unrecoverable error
  80  * @retval #WIDGET_STATUS_ERROR_NONE Successfully sent
  81  */
  82 extern int widget_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 widget programming interfaces: Operation is successfully done.
  86  * @since_tizen 2.4
  87  * @feature http://tizen.org/feature/shell.appwidget
  88  */
  89 extern const int WIDGET_DONE;
  90
  91 /**
  92  * @brief Return values of widget programming interfaces: Contents are updated.
  93  * @since_tizen 2.4
  94  * @feature http://tizen.org/feature/shell.appwidget
  95  */
  96 extern const int WIDGET_OUTPUT_UPDATED;
  97
  98 /**
  99  * @brief Return values of widget programming interfaces: Need to call the widget_need_to_update and widget_update_content.
 100  * @since_tizen 2.4
 101  * @feature http://tizen.org/feature/shell.appwidget
 102  */
 103 extern const int WIDGET_NEED_TO_SCHEDULE;
 104
 105 /**
 106  * @internal
 107  * @brief Return values of widget programming interfaces: Need to create a new instance.
 108  * @since_tizen 2.4
 109  */
 110 extern const int WIDGET_NEED_TO_CREATE;
 111
 112 /**
 113  * @brief Return values of widget programming interfaces: Need to do force update.
 114  * @since_tizen 2.4
 115  * @feature http://tizen.org/feature/shell.appwidget
 116  */
 117 extern const int WIDGET_FORCE_TO_SCHEDULE;
 118
 119 /**
 120  * @brief Return values of widget programming interfaces: Need to destroy this instance.
 121  * @since_tizen 2.4
 122  * @feature http://tizen.org/feature/shell.appwidget
 123  */
 124 extern const int WIDGET_NEED_TO_DESTROY;
 125
 126 /**
 127  * @brief Return values of widget programming interfaces: Need to update.
 128  * @since_tizen 2.4
 129  * @feature http://tizen.org/feature/shell.appwidget
 130  */
 131 extern const int WIDGET_NEED_TO_UPDATE;
 132
 133 /**
 134  * @brief System event type: System font is changed.
 135  * @since_tizen 2.4
 136  * @feature http://tizen.org/feature/shell.appwidget
 137  */
 138 extern const int WIDGET_SYS_EVENT_FONT_CHANGED;
 139
 140 /**
 141  * @brief System event type: System language is changed.
 142  * @since_tizen 2.4
 143  * @feature http://tizen.org/feature/shell.appwidget
 144  */
 145 extern const int WIDGET_SYS_EVENT_LANG_CHANGED;
 146
 147 /**
 148  * @brief System event type: System time is changed.
 149  * @since_tizen 2.4
 150  * @feature http://tizen.org/feature/shell.appwidget
 151  */
 152 extern const int WIDGET_SYS_EVENT_TIME_CHANGED;
 153
 154 /**
 155  * @brief System event type: MMC Status change event.
 156  * @since_tizen 2.4
 157  * @feature http://tizen.org/feature/shell.appwidget
 158  */
 159 extern const int WIDGET_SYS_EVENT_MMC_STATUS_CHANGED;
 160
 161 /**
 162  * @brief System event type: Region changed.
 163  * @since_tizen 2.4
 164  * @feature http://tizen.org/feature/shell.appwidget
 165  */
 166 extern const int WIDGET_SYS_EVENT_REGION_CHANGED;
 167
 168 /**
 169  * @brief System event type: Accessibility mode changed.
 170  * @since_tizen 2.4
 171  * @feature http://tizen.org/feature/shell.appwidget
 172  */
 173 extern const int WIDGET_SYS_EVENT_TTS_CHANGED;
 174
 175 /**
 176  * @brief System event type: widget is paused.
 177  * @since_tizen 2.4
 178  * @feature http://tizen.org/feature/shell.appwidget
 179  */
 180 extern const int WIDGET_SYS_EVENT_PAUSED;
 181
 182 /**
 183  * @brief System event type: widget is resumed.
 184  * @since_tizen 2.4
 185  * @feature http://tizen.org/feature/shell.appwidget
 186  */
 187 extern const int WIDGET_SYS_EVENT_RESUMED;
 188
 189 /**
 190  * @brief System event type: widget instance is removed from a viewer.
 191  * @since_tizen 2.4
 192  * @feature http://tizen.org/feature/shell.appwidget
 193  */
 194 extern const int WIDGET_SYS_EVENT_DELETED;
 195
 196 /**
 197  * @brief Requests to schedule the update operation to a provider.
 198  *        Your widget will get the update request, if the @a id is specified, specific box only will get it.
 199  * @since_tizen 2.4
 200  * @param[in] id Instance Id which is passed to you via the first parameter of every widget_XXXX interface functions
 201  * @feature http://tizen.org/feature/shell.appwidget
 202  * @return If succes returns 0 or return less than 0
 203  * @retval #WIDGET_STATUS_ERROR_NONE Successfully triggered
 204  * @retval #WIDGET_STATUS_ERROR_INVALID_PARAMETER Invalid argument
 205  * @retval #WIDGET_STATUS_ERROR_OUT_OF_MEMORY Not enough memory
 206  * @retval #WIDGET_STATUS_ERROR_NOT_EXIST Given id instance is not exist
 207  * @retval #WIDGET_STATUS_ERROR_PERMISSION_DENIED Permission denied
 208  * @retval #WIDGET_STATUS_ERROR_DISABLED in case of direct request for updating is disabled
 209  */
 210 extern int widget_request_update(const char *id);
 211
 212 /**
 213  * @brief Send a freeze request to the viewer (homescreen)
 214  * @details
 215  *        The viewer will get this request via event callback.
 216  *        Then it should freeze its scroller or stop moving the widget.
 217  * @since_tizen 2.4
 218  * @remarks If the viewer doesn't care this request, this will has no effect.
 219  * @param[in] widgetid widget Package Id
 220  * @param[in] id Instance Id which is passed to you via the first parameter of every widget_XXXX interface functions
 221  * @privlevel public
 222  * @privilege %http://tizen.org/privilege/widget.provider
 223  * @feature http://tizen.org/feature/shell.appwidget
 224  * @return #WIDGET_STATUS_ERROR_NONE on success,
 225  *          otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
 226  * @retval #WIDGET_STATUS_ERROR_INVALID_PARAMETER Invalid parameters
 227  * @retval #WIDGET_STATUS_ERROR_OUT_OF_MEMORY Out of memory
 228  * @retval #WIDGET_STATUS_ERROR_PERMISSION_DENIED Permission denied
 229  * @retval #WIDGET_STATUS_ERROR_FAULT Failed to send requet
 230  * @retval #WIDGET_STATUS_ERROR_NONE Successfully requested
 231  * @see widget_release_scroller()
 232  */
 233 extern int widget_freeze_scroller(const char *widgetid, const char *id);
 234
 235 /**
 236  * @brief Send a release request to the viewer (homescreen)
 237  * @details
 238  *        The viewer will get this request via event callback.
 239  *        Then it should release its scroller or continue moving the widget.
 240  * @since_tizen 2.4
 241  * @remarks If the viewer doesn't care this request, this will has no effect.
 242  * @param[in] widgetid widget Package Id
 243  * @param[in] id Instance Id which is passed to you via the first parameter of every widget_XXXX interface functions
 244  * @privlevel public
 245  * @privilege %http://tizen.org/privilege/widget.provider
 246  * @feature http://tizen.org/feature/shell.appwidget
 247  * @return #WIDGET_STATUS_ERROR_NONE on success,
 248  *          otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
 249  * @retval #WIDGET_STATUS_ERROR_PERMISSION_DENIED Permission denied
 250  * @retval #WIDGET_STATUS_ERROR_INVALID_PARAMETER Invalid parameters
 251  * @retval #WIDGET_STATUS_ERROR_OUT_OF_MEMORY Out of memory
 252  * @retval #WIDGET_STATUS_ERROR_FAULT Failed to send requet
 253  * @retval #WIDGET_STATUS_ERROR_NONE Successfully requested
 254  * @see widget_freeze_scroller()
 255  */
 256 extern int widget_thaw_scroller(const char *widgetid, const char *id);
 257
 258 /**
 259  * @}
 260  */
 261
 262 #ifdef __cplusplus
 263 }
 264 #endif
 265
 266 #endif
 267 /* End of a file */