2 * Copyright 2012 Samsung Electronics Co., Ltd
4 * Licensed under the Flora License, Version 1.0 (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
8 * http://www.tizenopensource.org/license
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.
35 #define DEFAULT_PERIOD -1.0f
37 enum content_event_type {
38 LB_MOUSE_DOWN = 0x0001, /*!< LB mouse down event for livebox */
39 LB_MOUSE_UP = 0x0002, /*!< LB mouse up event for livebox */
40 LB_MOUSE_MOVE = 0x0004, /*!< LB mouse move event for livebox */
41 LB_MOUSE_ENTER = 0x0008, /*!< LB mouse enter event for livebox */
42 LB_MOUSE_LEAVE = 0x0010, /*!< LB mouse leave event for livebox */
44 PD_MOUSE_DOWN = 0x0100, /*!< PD mouse down event for livebox */
45 PD_MOUSE_UP = 0x0200, /*!< PD mouse up event for livebox */
46 PD_MOUSE_MOVE = 0x0400, /*!< PD mouse move event for livebox */
47 PD_MOUSE_ENTER = 0x0800, /*!< PD mouse enter event for livebox */
48 PD_MOUSE_LEAVE = 0x1000, /*!< PD mouse leave event for livebox */
50 PD_EVENT_MAX = 0xFFFFFFFF,
53 /* Exported to user app */
54 enum livebox_lb_type {
55 LB_TYPE_IMAGE = 0x01, /*!< Contents of a livebox is based on the image file */
56 LB_TYPE_BUFFER = 0x02, /*!< Contents of a livebox is based on canvas buffer(shared) */
57 LB_TYPE_TEXT = 0x04, /*!< Contents of a livebox is based on formatted text file */
58 LB_TYPE_PIXMAP = 0x08, /*!< Contens of a livebox is shared by the pixmap(depends on X) */
60 LB_TYPE_INVALID = 0xFF,
63 enum livebox_pd_type {
64 PD_TYPE_BUFFER = 0x01, /*!< Contents of a PD is based on canvas buffer(shared) */
65 PD_TYPE_TEXT = 0x02, /*!< Contents of a PD is based on formatted text file */
66 PD_TYPE_PIXMAP = 0x04, /*!< Contents of a livebox is shared by the pixmap(depends on X) */
68 PD_TYPE_INVALID = 0xFF,
71 enum livebox_event_type { /*!< livebox_event_handler_set Event list */
72 LB_EVENT_LB_UPDATED, /*!< Contents of the given livebox is updated */
73 LB_EVENT_PD_UPDATED, /*!< Contents of the given pd is updated */
75 LB_EVENT_CREATED, /*!< A new livebox is created */
76 LB_EVENT_DELETED, /*!< A livebox is deleted */
78 LB_EVENT_GROUP_CHANGED, /*!< Group (Cluster/Sub-cluster) information is changed */
79 LB_EVENT_PINUP_CHANGED, /*!< PINUP status is changed */
80 LB_EVENT_PERIOD_CHANGED, /*!< Update period is changed */
82 LB_EVENT_PD_CREATED, /*!< If a PD is created even if you didn't call the livebox_create_pd API */
83 LB_EVENT_PD_DESTROYED, /*!< If a PD is destroyed even if you didn't call the livebox_destroy_pd API */
85 LB_EVENT_IGNORED, /*!< Request is ignored */
88 enum livebox_fault_type {
89 LB_FAULT_DEACTIVATED, /*!< Livebox is deactivated by its fault operation */
90 LB_FAULT_PROVIDER_DISCONNECTED, /*!< Provider is disconnected */
93 enum livebox_visible_state { /*!< Must be sync'd with the provider */
94 LB_SHOW = 0x00, /*!< Livebox is showed. Default state */
95 LB_HIDE = 0x01, /*!< Livebox is hide, Update timer is not be freezed. but you cannot receive any updates events. you should refresh(reload) the content of a livebox when you make this show again */
97 LB_HIDE_WITH_PAUSE = 0x02, /*!< Livebix is hide, it will paused the update timer, but if a livebox update its contents, update event will come to you */
99 LB_VISIBLE_ERROR = 0xFFFFFFFF, /* To enlarge the size of this enumeration type */
104 * TEXT type livebox contents handling opertators.
106 struct livebox_script_operators {
107 int (*update_begin)(struct livebox *handle); /*!< Content parser is started */
108 int (*update_end)(struct livebox *handle); /*!< Content parser is stopped */
112 * Listed functions will be called when parser meets each typed component
114 int (*update_text)(struct livebox *handle, const char *id, const char *part, const char *data); /*!< Update text content */
115 int (*update_image)(struct livebox *handle, const char *id, const char *part, const char *data); /*!< Update image content */
116 int (*update_script)(struct livebox *handle, const char *id, const char *part, const char *file, const char *group); /*!< Update script content */
117 int (*update_signal)(struct livebox *handle, const char *id, const char *emission, const char *signal); /*!< Update signal */
118 int (*update_drag)(struct livebox *handle, const char *id, const char *part, double dx, double dy); /*!< Update drag info */
119 int (*update_info_size)(struct livebox *handle, const char *id, int w, int h); /*!< Update content size */
120 int (*update_info_category)(struct livebox *handle, const char *id, const char *category); /*!< Update content category info */
124 * \brief Prototype of the return callback of every async functions.
130 typedef void (*ret_cb_t)(struct livebox *handle, int ret, void *data);
133 * \brief Initialize the livebox system
137 extern int livebox_init(void *disp);
140 * \brief Finalize the livebox system
143 extern int livebox_fini(void);
146 * \brief Add a new livebox
150 * \param[in] category
156 extern struct livebox *livebox_add(const char *pkgname, const char *content, const char *cluster, const char *category, double period, ret_cb_t cb, void *data);
157 extern struct livebox *livebox_add_with_size(const char *pkgname, const char *content, const char *cluster, const char *category, double period, int type, ret_cb_t cb, void *data);
160 * \brief Delete a livebox
162 * \param[in] ret_cb_t return callback
163 * \param[in] data user data for return callback
166 extern int livebox_del(struct livebox *handler, ret_cb_t cb, void *data);
169 * \brief Set a livebox events callback
170 * \param[in] cb Event handler
171 * \param[in] data User data for the event handler
173 * \sa livebox_unset_event_handler
176 extern int livebox_set_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data), void *data);
179 * \brief Unset the livebox event handler
181 * \return void * pointer of 'data' which is registered from the livebox_event_handler_set
182 * \sa livebox_set_event_handler
184 extern void *livebox_unset_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data));
189 * event, pkgname, filename, funcname
191 * \brief Live box fault event handler registeration function
195 * \sa livebox_unset_fault_handler
197 extern int livebox_set_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *), void *data);
200 * \brief Unset the live box fault event handler
202 * \return pointer of 'data'
203 * \sa livebox_set_fault_handler
205 extern void *livebox_unset_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *));
208 * \brief Activate the faulted livebox.
214 extern int livebox_activate(const char *pkgname, ret_cb_t cb, void *data);
217 * \brief Resize the livebox
218 * \param[in] handler Handler of a livebox
219 * \param[in] type Type of a livebox size, LB_SIZE_TYPE_1x1, ...
220 * \param[in] cb Result callback of the resize operation.
221 * \param[in] data User data for return callback
224 extern int livebox_resize(struct livebox *handler, int type, ret_cb_t cb, void *data);
227 * \brief Send the click event for a livebox.
228 * \param[in] handler Handler of a livebox
229 * \param[in] x Rational X of the content width.
230 * \param[in] y Rational Y of the content height.
233 extern int livebox_click(struct livebox *handler, double x, double y);
236 * \brief Change the cluster/sub-cluster name of given livebox handler
237 * \param[in] handler Handler of a livebox
238 * \param[in] cluster New cluster of a livebox
239 * \param[in] category New category of a livebox
240 * \param[in] cb Result callback for changing the cluster/category of a livebox
241 * \param[in] data User data for the result callback
244 extern int livebox_set_group(struct livebox *handler, const char *cluster, const char *category, ret_cb_t cb, void *data);
247 * \brief Get the cluster and category(sub-cluster) name of given livebox (It is not I18N format, only english)
248 * \param[in] handler Handler of a livebox
249 * \param[out] cluster Storage(memory) for containing the cluster name
250 * \param[out] category Storage(memory) for containing the category name
253 extern int livebox_get_group(struct livebox *handler, char ** const cluster, char ** const category);
256 * \brief Get the period of this livebox handler
257 * \param[in] handler Handler of a livebox
258 * \return double Current update period of a livebox
260 extern double livebox_period(struct livebox *handler);
263 * \brief Change the update period
264 * \param[in] handler Handler of a livebox
265 * \param[in] period New update period of a livebox
266 * \param[in] cb Result callback of changing the update period of this livebox
267 * \param[in] data User data for the result callback
270 extern int livebox_set_period(struct livebox *handler, double period, ret_cb_t cb, void *data);
273 * \brief Is this an text type livebox?
275 * \return content_type
277 extern enum livebox_lb_type livebox_lb_type(struct livebox *handler);
280 * \brief Is this livebox is created by a user?
284 extern int livebox_is_user(struct livebox *handler);
287 * \brief Get the content information string of given livebox
291 extern const char *livebox_content(struct livebox *handler);
294 * \brief Get the sub cluster title string of given livebox
296 * \return sub cluster title
298 extern const char *livebox_category_title(struct livebox *handler);
301 * \brief Get the filename of given livebox, if it is an IMAGE type livebox
305 extern const char *livebox_filename(struct livebox *handler);
308 * \brief Get the package name of given livebox handler
312 extern const char *livebox_pkgname(struct livebox *handler);
315 * \brief Get the priority of a current content.
319 extern double livebox_priority(struct livebox *handler);
322 * \brief Acquire the buffer of given livebox (Only for the buffer type)
324 * \return address of a FB
326 extern void *livebox_acquire_fb(struct livebox *handler);
329 * \brief Release the buffer of a livebox (Only for the buffer type)
333 extern int livebox_release_fb(void *buffer);
336 * \brief Get the reference count of Livebox buffer (Only for the buffer type)
340 extern int livebox_fb_refcnt(void *buffer);
343 * \brief Acquire the buffer of a PD frame (Only for the buffer type)
347 extern void *livebox_acquire_pdfb(struct livebox *handler);
350 * \brief Release the acquired buffer of the PD Frame (Only for the buffer type)
354 extern int livebox_release_pdfb(void *buffer);
357 * \brief Reference count of given PD buffer (Only for the buffer type)
361 extern int livebox_pdfb_refcnt(void *buffer);
364 * \brief Get the size of the Livebox
370 extern int livebox_size(struct livebox *handler);
373 * \brief Get the size of the Progressive Disclosure
379 extern int livebox_get_pdsize(struct livebox *handler, int *w, int *h);
382 * \brief List of supported sizes of given handler
389 extern int livebox_get_supported_sizes(struct livebox *handler, int *cnt, int *size_list);
392 * \brief BUFFER SIZE of the livebox if it is a buffer type
396 extern int livebox_lbfb_bufsz(struct livebox *handler);
399 * \brief BUFFER SIZE of the progiressive disclosure if it is a buffer type
403 extern int livebox_pdfb_bufsz(struct livebox *handler);
406 * \brief Send the content event (for buffer type) to provider(livebox)
412 extern int livebox_content_event(struct livebox *handler, enum content_event_type type, double x, double y);
415 * \brief Do pin up or not.
422 extern int livebox_set_pinup(struct livebox *handler, int flag, ret_cb_t cb, void *data);
425 * \brief Check the PIN-UP status of given handler
429 extern int livebox_is_pinned_up(struct livebox *handler);
432 * \brief Check the PINUP feature availability of the given handler
436 extern int livebox_has_pinup(struct livebox *handler);
439 * \brief Check the PD existence of given handler
443 extern int livebox_has_pd(struct livebox *handler);
446 * \brief Create the PD of given handler
452 extern int livebox_create_pd(struct livebox *handler, ret_cb_t cb, void *data);
455 * \brief Create the PD of given handler with the relative position from livebox
457 * \param[in] x 0.0 ~ 1.0
458 * \param[in] y 0.0 ~ 1.0
463 extern int livebox_create_pd_with_position(struct livebox *handler, double x, double y, ret_cb_t cb, void *data);
466 * \brief Destroy the PD of given handler if it is created.
472 extern int livebox_destroy_pd(struct livebox *handler, ret_cb_t cb, void *data);
475 * \brief Check the create status of given livebox handler
479 extern int livebox_pd_is_created(struct livebox *handler);
482 * \brief Check the content type of the progressive disclosure of given handler
486 extern enum livebox_pd_type livebox_pd_type(struct livebox *handler);
489 * \brief Check the existence of a livebox about given package name
493 extern int livebox_is_exists(const char *pkgname);
496 * \brief Set function table for parsing the text content of a livebox
501 extern int livebox_set_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
504 * \brief Set function table for parsing the text content of a Progressive Disclosure
509 extern int livebox_set_pd_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
512 * \brief Emit a text signal to given livebox only if it is a text type.
514 * \param[in] emission
523 extern int livebox_emit_text_signal(struct livebox *handler, const char *emission, const char *source, double sx, double sy, double ex, double ey, ret_cb_t cb, void *data);
526 * \brief Set a private data pointer to carry it using given handler
531 extern int livebox_set_data(struct livebox *handler, void *data);
534 * \brief Get private data pointer which is carried by given handler
538 extern void *livebox_get_data(struct livebox *handler);
541 * \brief Subscribe the event for liveboxes only in given cluster and sub-cluster
542 * \param[in] cluster "*" can be used for subscribe all cluster's liveboxes event.
543 * If you use the "*", value in the category will be ignored.
544 * \param[in] category "*" can be used for subscribe liveboxes events of all category(sub-cluster) in given "cluster"
545 * \return int Success 0, fails error code
547 extern int livebox_subscribe_group(const char *cluster, const char *category);
550 * \brief Unsubscribe the event for the liveboxes, but you will receive already added liveboxes event.
551 * \param[in] cluster "*" can be used for subscribe all cluster's liveboxes event.
552 * If you use the "*", value in the category will be ignored.
553 * \param[in] category "*" can be used for subscribe all sub-cluster's liveboxes event in given "cluster"
554 * \return int Success 0, fails error code
556 extern int livebox_unsubscribe_group(const char *cluster, const char *category);
559 * \brief Refresh the group(cluster/sub-cluser(aka. category))
560 * \param[in] cluster Cluster ID
561 * \param[in] category Sub-cluster ID
562 * \return int Success 0 or negative value
564 extern int livebox_refresh_group(const char *cluster, const char *category);
567 * \brief Pixmap Id of a livebox content
570 * \sa livebox_pd_pixmap
572 extern int livebox_lb_pixmap(const struct livebox *handler);
575 * \brief Pixmap Id of a PD content
578 * \sa livebox_lb_pixmap
580 extern int livebox_pd_pixmap(const struct livebox *handler);
588 * \sa livebox_release_pd_pixmap
589 * \sa livebox_acquire_lb_pixmap
591 extern int livebox_acquire_pd_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
594 * \brief Release the acquired pixmap ID
598 * \sa livebox_acquire_pd_pixmap
599 * \sa livebox_release_lb_pixmap
601 extern int livebox_release_pd_pixmap(struct livebox *handler, int pixmap);
609 * \sa livebox_release_lb_pixmap
610 * \sa livebox_acquire_pd_pixmap
612 extern int livebox_acquire_lb_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
619 * \sa livebox_acquire_lb_pixmap
620 * \sa livebox_release_pd_pixmap
622 extern int livebox_release_lb_pixmap(struct livebox *handler, int pixmap);
625 * \brief Update the visible state of a livebox
626 * \param[in] handler Handler of a livebox
627 * \param[in] state Configure the current visible state of a livebox
630 extern int livebox_set_visibility(struct livebox *handler, enum livebox_visible_state state);
633 * \brief Current visible state of a livebox
634 * \param[in] handler Handler of a livebox
635 * \return enum visible state
637 extern enum livebox_visible_state livebox_visibility(struct livebox *handler);