fixed plugin image size problem
[framework/uifw/elementary.git] / src / lib / elm_segment_control.h
1 /**
2  * @defgroup SegmentControl SegmentControl
3  * @ingroup Elementary
4  *
5  * @image html img/widget/segment_control/preview-00.png
6  * @image latex img/widget/segment_control/preview-00.eps width=\textwidth
7  *
8  * @image html img/segment_control.png
9  * @image latex img/segment_control.eps width=\textwidth
10  *
11  * Segment control widget is a horizontal control made of multiple segment
12  * items, each segment item functioning similar to discrete two state button.
13  * A segment control groups the items together and provides compact
14  * single button with multiple equal size segments.
15  *
16  * Segment item size is determined by base widget
17  * size and the number of items added.
18  * Only one segment item can be at selected state. A segment item can display
19  * combination of Text and any Evas_Object like Images or other widget.
20  *
21  * Smart callbacks one can listen to:
22  * - "changed" - When the user clicks on a segment item which is not
23  *   previously selected and get selected. The event_info parameter is the
24  *   segment item pointer.
25  *
26  * Available styles for it:
27  * - @c "default"
28  *
29  * Default content parts of the segment control items that you can use for are:
30  * @li "icon" - An icon in a segment control item
31  *
32  * Default text parts of the segment control items that you can use for are:
33  * @li "default" - Title label in a segment control item
34  *
35  * Supported elm_object common APIs.
36  * @li elm_object_disabled_set
37  * @li elm_object_disabled_get
38  *
39  * Supported elm_object_item common APIs.
40  * @li @ref elm_object_item_part_text_set
41  * @li @ref elm_object_item_part_text_get
42  * @li @ref elm_object_item_part_content_set
43  * @li @ref elm_object_item_part_content_get
44  *
45  * Here is an example on its usage:
46  * @li @ref segment_control_example
47  *
48  */
49
50 /**
51  * @addtogroup SegmentControl
52  * @{
53  */
54
55 /**
56  * Add a new segment control widget to the given parent Elementary
57  * (container) object.
58  *
59  * @param parent The parent object.
60  * @return a new segment control widget handle or @c NULL, on errors.
61  *
62  * This function inserts a new segment control widget on the canvas.
63  *
64  * @ingroup SegmentControl
65  */
66 EAPI Evas_Object      *elm_segment_control_add(Evas_Object *parent);
67
68 /**
69  * Append a new item to the segment control object.
70  *
71  * @param obj The segment control object.
72  * @param icon The icon object to use for the left side of the item. An
73  * icon can be any Evas object, but usually it is an icon created
74  * with elm_icon_add().
75  * @param label The label of the item.
76  *        Note that, NULL is different from empty string "".
77  * @return The created item or @c NULL upon failure.
78  *
79  * A new item will be created and appended to the segment control, i.e., will
80  * be set as @b last item.
81  *
82  * If it should be inserted at another position,
83  * elm_segment_control_item_insert_at() should be used instead.
84  *
85  * Items created with this function can be deleted with function
86  * elm_object_item_del() or elm_object_item_del_at().
87  *
88  * @note @p label set to @c NULL is different from empty string "".
89  * If an item
90  * only has icon, it will be displayed bigger and centered. If it has
91  * icon and label, even that an empty string, icon will be smaller and
92  * positioned at left.
93  *
94  * Simple example:
95  * @code
96  * sc = elm_segment_control_add(win);
97  * ic = elm_icon_add(win);
98  * elm_icon_file_set(ic, "path/to/image", NULL);
99  * elm_icon_resizable_set(ic, EINA_TRUE, EINA_TRUE);
100  * elm_segment_control_item_add(sc, ic, "label");
101  * evas_object_show(sc);
102  * @endcode
103  *
104  * @see elm_segment_control_item_insert_at()
105  * @see elm_object_item_del()
106  *
107  * @ingroup SegmentControl
108  */
109 EAPI Elm_Object_Item *elm_segment_control_item_add(Evas_Object *obj, Evas_Object *icon, const char *label);
110
111 /**
112  * Insert a new item to the segment control object at specified position.
113  *
114  * @param obj The segment control object.
115  * @param icon The icon object to use for the left side of the item. An
116  * icon can be any Evas object, but usually it is an icon created
117  * with elm_icon_add().
118  * @param label The label of the item.
119  * @param index Item position. Value should be between 0 and items count.
120  * @return The created item or @c NULL upon failure.
121
122  * Index values must be between @c 0, when item will be prepended to
123  * segment control, and items count, that can be get with
124  * elm_segment_control_item_count_get(), case when item will be appended
125  * to segment control, just like elm_segment_control_item_add().
126  *
127  * Items created with this function can be deleted with function
128  * elm_object_item_del() or elm_segment_control_item_del_at().
129  *
130  * @note @p label set to @c NULL is different from empty string "".
131  * If an item
132  * only has icon, it will be displayed bigger and centered. If it has
133  * icon and label, even that an empty string, icon will be smaller and
134  * positioned at left.
135  *
136  * @see elm_segment_control_item_add()
137  * @see elm_segment_control_item_count_get()
138  * @see elm_object_item_del()
139  *
140  * @ingroup SegmentControl
141  */
142 EAPI Elm_Object_Item *elm_segment_control_item_insert_at(Evas_Object *obj, Evas_Object *icon, const char *label, int index);
143
144 /**
145  * Remove a segment control item at given index from its parent,
146  * deleting it.
147  *
148  * @param obj The segment control object.
149  * @param index The position of the segment control item to be deleted.
150  *
151  * Items can be added with elm_segment_control_item_add() or
152  * elm_segment_control_item_insert_at().
153  *
154  * @ingroup SegmentControl
155  */
156 EAPI void              elm_segment_control_item_del_at(Evas_Object *obj, int index);
157
158 /**
159  * Get the Segment items count from segment control.
160  *
161  * @param obj The segment control object.
162  * @return Segment items count.
163  *
164  * It will just return the number of items added to segment control @p obj.
165  *
166  * @ingroup SegmentControl
167  */
168 EAPI int               elm_segment_control_item_count_get(const Evas_Object *obj);
169
170 /**
171  * Get the item placed at specified index.
172  *
173  * @param obj The segment control object.
174  * @param index The index of the segment item.
175  * @return The segment control item or @c NULL on failure.
176  *
177  * Index is the position of an item in segment control widget. Its
178  * range is from @c 0 to <tt> count - 1 </tt>.
179  * Count is the number of items, that can be get with
180  * elm_segment_control_item_count_get().
181  *
182  * @ingroup SegmentControl
183  */
184 EAPI Elm_Object_Item *elm_segment_control_item_get(const Evas_Object *obj, int index);
185
186 /**
187  * Get the label of item.
188  *
189  * @param obj The segment control object.
190  * @param index The index of the segment item.
191  * @return The label of the item at @p index.
192  *
193  * The return value is a pointer to the label associated to the item when
194  * it was created, with function elm_segment_control_item_add(), or later
195  * with function elm_object_item_text_set. If no label
196  * was passed as argument, it will return @c NULL.
197  *
198  * @see elm_object_item_text_set() for more details.
199  * @see elm_segment_control_item_add()
200  *
201  * @ingroup SegmentControl
202  */
203 EAPI const char       *elm_segment_control_item_label_get(const Evas_Object *obj, int index);
204
205 /**
206  * Get the icon associated to the item.
207  *
208  * @param obj The segment control object.
209  * @param index The index of the segment item.
210  * @return The left side icon associated to the item at @p index.
211  *
212  * The return value is a pointer to the icon associated to the item when
213  * it was created, with function elm_segment_control_item_add(), or later
214  * with function elm_object_item_part_content_set(). If no icon
215  * was passed as argument, it will return @c NULL.
216  *
217  * @see elm_segment_control_item_add()
218  * @see elm_object_item_part_content_set()
219  *
220  * @ingroup SegmentControl
221  */
222 EAPI Evas_Object      *elm_segment_control_item_icon_get(const Evas_Object *obj, int index);
223
224 /**
225  * Get the index of an item.
226  *
227  * @param it The segment control item.
228  * @return The position of item in segment control widget.
229  *
230  * Index is the position of an item in segment control widget. Its
231  * range is from @c 0 to <tt> count - 1 </tt>.
232  * Count is the number of items, that can be get with
233  * elm_segment_control_item_count_get().
234  *
235  * @ingroup SegmentControl
236  */
237 EAPI int               elm_segment_control_item_index_get(const Elm_Object_Item *it);
238
239 /**
240  * Get the base object of the item.
241  *
242  * @param it The segment control item.
243  * @return The base object associated with @p it.
244  *
245  * Base object is the @c Evas_Object that represents that item.
246  *
247  * @ingroup SegmentControl
248  */
249 EAPI Evas_Object      *elm_segment_control_item_object_get(const Elm_Object_Item *it);
250
251 /**
252  * Get the selected item.
253  *
254  * @param obj The segment control object.
255  * @return The selected item or @c NULL if none of segment items is
256  * selected.
257  *
258  * The selected item can be unselected with function
259  * elm_segment_control_item_selected_set().
260  *
261  * The selected item always will be highlighted on segment control.
262  *
263  * @ingroup SegmentControl
264  */
265 EAPI Elm_Object_Item *elm_segment_control_item_selected_get(const Evas_Object *obj);
266
267 /**
268  * Set the selected state of an item.
269  *
270  * @param it The segment control item
271  * @param select The selected state
272  *
273  * This sets the selected state of the given item @p it.
274  * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
275  *
276  * If a new item is selected the previously selected will be unselected.
277  * Selected item can be got with function
278  * elm_segment_control_item_selected_get().
279  *
280  * The selected item always will be highlighted on segment control.
281  *
282  * @see elm_segment_control_item_selected_get()
283  *
284  * @ingroup SegmentControl
285  */
286 EAPI void              elm_segment_control_item_selected_set(Elm_Object_Item *it, Eina_Bool select);
287
288 /**
289  * @}
290  */