Tizen 2.1 base
[framework/uifw/elementary.git] / src / lib / elm_table.h
1 /**
2  * @defgroup Table Table
3  * @ingroup Elementary
4  *
5  * @image html table_inheritance_tree.png
6  * @image latex table_inheritance_tree.eps
7  *
8  * A container widget to arrange other widgets in a table where items can
9  * span multiple columns or rows - even overlap (and then be raised or
10  * lowered accordingly to adjust stacking if they do overlap).
11  *
12  * The row and column count is not fixed. The table widget adjusts itself when
13  * subobjects are added to it dynamically.
14  *
15  * The most common way to use a table is:
16  * @code
17  * table = elm_table_add(win);
18  * evas_object_show(table);
19  * elm_table_padding_set(table, space_between_columns, space_between_rows);
20  * elm_table_pack(table, table_content_object, x_coord, y_coord, colspan, rowspan);
21  * elm_table_pack(table, table_content_object, next_x_coord, next_y_coord, colspan, rowspan);
22  * elm_table_pack(table, table_content_object, other_x_coord, other_y_coord, colspan, rowspan);
23  * @endcode
24  *
25  * The following are examples of how to use a table:
26  * @li @ref tutorial_table_01
27  * @li @ref tutorial_table_02
28  *
29  * @{
30  */
31
32 /**
33  * @brief Add a new table to the parent
34  *
35  * @param parent The parent object
36  * @return The new object or NULL if it cannot be created
37  *
38  * @ingroup Table
39  */
40 EAPI Evas_Object *elm_table_add(Evas_Object *parent);
41
42 /**
43  * @brief Set the homogeneous layout in the table
44  *
45  * @param obj The layout object
46  * @param homogeneous A boolean to set if the layout is homogeneous in the
47  * table (EINA_TRUE = homogeneous,  EINA_FALSE = no homogeneous)
48  *
49  * @ingroup Table
50  */
51 EAPI void      elm_table_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous);
52
53 /**
54  * @brief Get the current table homogeneous mode.
55  *
56  * @param obj The table object
57  * @return A boolean to indicating if the layout is homogeneous in the table
58  * (EINA_TRUE = homogeneous,  EINA_FALSE = no homogeneous)
59  *
60  * @ingroup Table
61  */
62 EAPI Eina_Bool elm_table_homogeneous_get(const Evas_Object *obj);
63
64 /**
65  * @brief Set padding between cells.
66  *
67  * @param obj The layout object.
68  * @param horizontal set the horizontal padding.
69  * @param vertical set the vertical padding.
70  *
71  * Default value is 0.
72  *
73  * @ingroup Table
74  */
75 EAPI void      elm_table_padding_set(Evas_Object *obj, Evas_Coord horizontal, Evas_Coord vertical);
76
77 /**
78  * @brief Get padding between cells.
79  *
80  * @param obj The layout object.
81  * @param horizontal set the horizontal padding.
82  * @param vertical set the vertical padding.
83  *
84  * @ingroup Table
85  */
86 EAPI void      elm_table_padding_get(const Evas_Object *obj, Evas_Coord *horizontal, Evas_Coord *vertical);
87
88 /**
89  * @brief Add a subobject on the table with the coordinates passed
90  *
91  * @param obj The table object
92  * @param subobj The subobject to be added to the table
93  * @param x Row number
94  * @param y Column number
95  * @param w colspan
96  * @param h rowspan
97  *
98  * @note All positioning inside the table is relative to rows and columns, so
99  * a value of 0 for x and y, means the top left cell of the table, and a
100  * value of 1 for w and h means @p subobj only takes that 1 cell.
101  *
102  * @ingroup Table
103  */
104 EAPI void      elm_table_pack(Evas_Object *obj, Evas_Object *subobj, int x, int y, int w, int h);
105
106 /**
107  * @brief Remove child from table.
108  *
109  * @param obj The table object
110  * @param subobj The subobject
111  *
112  * @ingroup Table
113  */
114 EAPI void      elm_table_unpack(Evas_Object *obj, Evas_Object *subobj);
115
116 /**
117  * @brief Faster way to remove all child objects from a table object.
118  *
119  * @param obj The table object
120  * @param clear If true, will delete children, else just remove from table.
121  *
122  * @ingroup Table
123  */
124 EAPI void      elm_table_clear(Evas_Object *obj, Eina_Bool clear);
125
126 /**
127  * @brief Set the packing location of an existing child of the table
128  *
129  * @param subobj The subobject to be modified in the table
130  * @param x Row number
131  * @param y Column number
132  * @param w rowspan
133  * @param h colspan
134  *
135  * Modifies the position of an object already in the table.
136  *
137  * @note All positioning inside the table is relative to rows and columns, so
138  * a value of 0 for x and y, means the top left cell of the table, and a
139  * value of 1 for w and h means @p subobj only takes that 1 cell.
140  *
141  * @ingroup Table
142  */
143 EAPI void      elm_table_pack_set(Evas_Object *subobj, int x, int y, int w, int h);
144
145 /**
146  * @brief Get the packing location of an existing child of the table
147  *
148  * @param subobj The subobject to be modified in the table
149  * @param x Row number
150  * @param y Column number
151  * @param w rowspan
152  * @param h colspan
153  *
154  * @see elm_table_pack_set()
155  *
156  * @ingroup Table
157  */
158 EAPI void      elm_table_pack_get(Evas_Object *subobj, int *x, int *y, int *w, int *h);
159
160 /**
161  * @}
162  */