Merge from tizen 2.3.1
[apps/native/widget/widget.git] / doc / widget_doc.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
18 #ifndef __WIDGET_DOC_H__
19 #define __WIDGET_DOC_H__
20
21 /**
22  * @defgroup WIDGET_UTILITY_MODULE widget
23  * @brief Supports APIs for development of inhouse widget
24  * @ingroup CAPI_WIDGET_FRAMEWORK 
25  * @section WIDGET_UTILITY_MODULE_HEADER Required Header
26  *   \#include <widget.h>
27  * @section WIDGET_UTILITY_MODULE_OVERVIEW Overview
28 <H1>widget Utility functions</H1>
29
30 <H2>1. Script type widget</H2>
31 If you choose the Script Type widget, you have to use this.
32
33 widget defines its own syntax to share the content between home application and provider application.
34 It is called "Description Data Syntax"
35
36 To generate it you have to use following functions.
37
38 @code
39 struct widget_desc *desc_handle;
40 int idx;
41
42 desc_handle = widget_desc_open(id, 0);
43 if (!desc_handle) {
44     // Error
45 }
46
47 widget_desc_set_size(desc_handle, id, 720, 360);
48
49 // Loads sub-layout object into main layout
50 idx = widget_desc_add_block(desc_handle, NULL, WIDGET_DESC_TYPE_SCRIPT, "sub,layout", "/usr/apps/com.samsung.my-app/shared/res/widget.edj", "sub,group");
51 widget_desc_set_id(desc_handle, idx, "sub,layout");
52
53 // Set a text for sub-layout object
54 widget_desc_add_block(desc_handle, "sub,layout", WIDGET_DESC_TYPE_TEXT, "sub,layout,text", "Hello World", NULL);
55
56 // Flushes changes, the content will be changed after close this handle.
57 widget_desc_close(desc_handle);
58 desc_handle = NULL;
59 @endcode
60
61 Only after you close the desc_handle, the provider will send changes to the widget manager service.
62 And if it needs to propagate events to the home application, the home application will get changes event.
63
64 <H2>2. Window(buffer) type widget</H2>
65
66 @code
67 Evas_Object *parent;
68 Evas_Object *win;
69
70 parent = widget_get_evas_object(id, 0);
71 if (!parent) {
72     // Error
73 }
74
75 win = elm_win_add(parent, "widget Window", ELM_WIN_DYNAMIC_BOX);
76 evas_object_del(parent);
77 if (!win) {
78     // Error
79 }
80 @endcode
81
82 To create a window for widget,
83 You have to get the parent object using widget_get_evas().
84 And after creating a window for widget, you have to delete it.
85 Its attributes will be passed to the newly created window. So you don't need keep the parent object anymore.
86
87 After creating a window, you can do what you want like an application.
88 Creatig any core-control such as button, list, etc, ....
89
90 <H2>3. Image type widget</H2>
91 This kind of widget should create an image file using given Id.
92 The Id's syntax is "file://ABS_PATH_OF_OUTPUT_FILE", so you should create an image file using this URI.
93 The Id will be assigned to every widget instances.
94 And those are unique.
95
96 If you create an image file, you should notify it to the viewer using widget_provider_app_widget_updated()
97 it is provided by libwidget_provider_app package.
98
99 <H2>4. Text type widget (Experimental)</H2>
100 In case of text type, you may have no window or script file.
101 The text type widget only needs to generate content data using widget_desc_XXXX series APIs.
102 Of course, after you prepare the desc file, you have to call widget_provider_app_widget_updated() function too.
103 Then the viewer will get your updated contents and try to parse it to locate content of widget to its screen.
104 But, unfortunately, this type of widget is not fully supported yet.
105 Because it very highly depends on the viewer implementations.
106 So if the viewer doesn't support this type of widget, you cannot do anything for user.
107
108 To generate the text data, you can use below API set.
109
110  - widget_desc_open()
111  - widget_desc_set_category()
112  - widget_desc_set_size()
113  - widget_desc_set_id()
114  - widget_desc_add_block()
115  - widget_desc_del_block()
116  - widget_desc_close()
117
118 Here is a sample code for you.
119 \code
120 #define FOR_GBAR 1
121 #define FOR_WIDGET 0
122
123 struct widget_desc *handle;
124 int idx;
125
126 handle = widget_desc_open(handle, FOR_GBAR); // The second parameter will help you choose to target, for glance bar or widget?
127 idx = widget_desc_add_block(handle, NULL, WIDGET_DESC_TYPE_SCRIPT, "/opt/usr/apps/your.company.application/shared/resource/edje/script.edj", "sample", NULL);
128 widget_desc_set_id(handle, idx, "sample");
129 widget_desc_close(handle);
130 widget_provider_app_widget_updated(widget_id, 0, 0);
131 \endocde
132
133  */
134
135 #endif /* __WIDGET_DOC_H__ */