1 #ifndef ELM_WIDGET_LAYOUT_H
2 #define ELM_WIDGET_LAYOUT_H
4 #include "elm_widget_container.h"
10 * @section elm-layout-class The Elementary Layout Class
12 * Elementary, besides having the @ref Layout widget, exposes its
13 * foundation -- the Elementary Layout Class -- in order to create
14 * other widgets which are, basically, a certain layout with some more
17 * The idea is to make the creation of that widgets as easy as possible,
18 * factorizing code on this common base. For example, a button is a
19 * layout (that looks like push button) that happens to react on
20 * clicks and keyboard events in a special manner, calling its user
21 * back on those events. That's no surprise, then, that the @ref
22 * Button implementation relies on #Elm_Layout_Smart_Class, if you go
25 * The Layout class inherits from
26 * #Elm_Container_Smart_Class. Container parts, here, map directly to
27 * Edje parts from the layout's Edje group. Besides that, there's a whole
28 * infrastructure around Edje files:
29 * - interfacing by signals,
30 * - setting/retrieving text part values,
31 * - dealing with table and box parts directly,
34 * Take a look at #Elm_Layout_Smart_Class's 'virtual' functions to
35 * understand the whole interface. Finally, layout objects will do
36 * <b>part aliasing</b> for you, if you set it up properly. For that,
37 * take a look at #Elm_Layout_Part_Alias_Description, where it's
38 * explained in detail.
42 * @def ELM_LAYOUT_CLASS
44 * Use this macro to cast whichever subclass of
45 * #Elm_Layout_Smart_Class into it, so to access its fields.
49 #define ELM_LAYOUT_CLASS(x) ((Elm_Layout_Smart_Class *) x)
52 * @def ELM_LAYOUT_DATA
54 * Use this macro to cast whichever subdata of
55 * #Elm_Layout_Smart_Data into it, so to access its fields.
59 #define ELM_LAYOUT_DATA(x) ((Elm_Layout_Smart_Data *) x)
62 * @def ELM_LAYOUT_SMART_CLASS_VERSION
64 * Current version for Elementary layout @b base smart class, a value
65 * which goes to _Elm_Layout_Smart_Class::version.
69 #define ELM_LAYOUT_SMART_CLASS_VERSION 1
72 * @def ELM_LAYOUT_SMART_CLASS_INIT
74 * Initializer for a whole #Elm_Layout_Smart_Class structure, with
75 * @c NULL values on its specific fields.
77 * @param smart_class_init initializer to use for the "base" field
78 * (#Evas_Smart_Class).
80 * @see EVAS_SMART_CLASS_INIT_NULL
81 * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
82 * @see ELM_LAYOUT_SMART_CLASS_INIT_NULL
83 * @see ELM_LAYOUT_SMART_CLASS_INIT_NAME_VERSION
87 #define ELM_LAYOUT_SMART_CLASS_INIT(smart_class_init) \
88 {smart_class_init, ELM_LAYOUT_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, \
89 NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, \
93 * @def ELM_LAYOUT_SMART_CLASS_INIT_NULL
95 * Initializer to zero out a whole #Elm_Layout_Smart_Class structure.
97 * @see ELM_LAYOUT_SMART_CLASS_INIT_NAME_VERSION
98 * @see ELM_LAYOUT_SMART_CLASS_INIT
102 #define ELM_LAYOUT_SMART_CLASS_INIT_NULL \
103 ELM_LAYOUT_SMART_CLASS_INIT(EVAS_SMART_CLASS_INIT_NULL)
106 * @def ELM_LAYOUT_SMART_CLASS_INIT_NAME_VERSION
108 * Initializer to zero out a whole #Elm_Layout_Smart_Class structure and
109 * set its name and version.
111 * This is similar to #ELM_LAYOUT_SMART_CLASS_INIT_NULL, but it will
112 * also set the version field of #Elm_Layout_Smart_Class (base field)
113 * to the latest #ELM_LAYOUT_SMART_CLASS_VERSION and name it to the
116 * It will keep a reference to the name field as a <c>"const char *"</c>,
117 * i.e., the name must be available while the structure is
118 * used (hint: static or global variable!) and must not be modified.
120 * @see ELM_LAYOUT_SMART_CLASS_INIT_NULL
121 * @see ELM_LAYOUT_SMART_CLASS_INIT
125 #define ELM_LAYOUT_SMART_CLASS_INIT_NAME_VERSION(name) \
126 ELM_LAYOUT_SMART_CLASS_INIT \
127 (ELM_CONTAINER_SMART_CLASS_INIT_NAME_VERSION(name))
130 * @typedef Elm_Layout_Part_Alias_Description
132 * A layout part aliasing (proxying) description, used to get part
133 * names aliasing independently of a widgets theme.
137 typedef struct _Elm_Layout_Part_Alias_Description Elm_Layout_Part_Alias_Description;
140 * @struct _Elm_Layout_Part_Alias_Description
142 * Elementary Layout-based widgets may declare part proxies, i.e., aliases
143 * for real theme part names to expose to the API calls:
144 * - elm_layout_text_set()
145 * - elm_layout_text_get()
146 * - elm_layout_content_set()
147 * - elm_layout_content_get()
148 * - elm_layout_content_unset()
149 * and their equivalents. This list must be set on the
150 * @c "_smart_set_user()" function of inheriting widgets, so that part
151 * aliasing is handled automatically for them.
155 struct _Elm_Layout_Part_Alias_Description
157 const char *alias; /**< Alternate name for a given (real) part. Calls receiving this string as a part name will be translated to the string at _Elm_Layout_Part_Proxies_Description::real_part */
159 const char *real_part; /**< Target part name for the alias set on @ref _Elm_Layout_Part_Proxies_Description::real_part. An example of usage would be @c "default" on that field, with @c "elm.content.swallow" on this one */
163 * Elementary layout base smart class. This inherits directly from
164 * #Elm_Container_Smart_Class and is meant to build widgets relying on
165 * an Edje layout as a building block of its visuals.
167 * For instance, the elm_layout @b widget itself is just a realization
168 * of this smart class (see the code for elm_layout_add()). All of the
169 * functions listed on @ref Layout namespace will work for objects
170 * deriving from #Elm_Layout_Smart_Class.
172 typedef struct _Elm_Layout_Smart_Class
174 Elm_Container_Smart_Class base; /**< Elementary container widget class struct, since we're inheriting from it */
176 int version; /**< Version of this smart class definition */
178 void (*sizing_eval)(Evas_Object *obj); /* 'Virtual' function on evalutating the object's final geometry, accounting for its sub-objects */
179 void (*signal)(Evas_Object *obj,
180 const char *emission,
181 const char *source); /* 'Virtual' function on emitting an (Edje) signal to the object, acting on its internal layout */
182 void (*callback_add)(Evas_Object *obj,
183 const char *emission,
186 void *data); /* 'Virtual' function on adding an (Edje) signal callback to the object, proxyed from its internal layout */
187 void * (*callback_del)(Evas_Object * obj,
188 const char *emission,
190 Edje_Signal_Cb func); /* 'Virtual' function on deleting an (Edje) signal callback on the object, proxyed from its internal layout */
191 Eina_Bool (*text_set)(Evas_Object *obj,
193 const char *text); /* 'Virtual' function on setting text on an (Edje) part of the object, from its internal layout */
194 const char *(*text_get)(const Evas_Object * obj,
195 const char *part); /* 'Virtual' function on fetching text from an (Edje) part of the object, on its internal layout */
197 Eina_Bool (*box_append)(Evas_Object *obj,
199 Evas_Object *child); /* 'Virtual' function on appending an object to an (Edje) box part of the object, from its internal layout */
200 Eina_Bool (*box_prepend)(Evas_Object *obj,
202 Evas_Object *child); /* 'Virtual' function on prepending an object to an (Edje) box part of the object, from its internal layout */
203 Eina_Bool (*box_insert_before)(Evas_Object *obj,
206 const Evas_Object *reference); /* 'Virtual' function on inserting an object to an (Edje) box part of the object, from its internal layout. The new child's position in the box is be prior to the one of a relative child already in the box */
207 Eina_Bool (*box_insert_at)(Evas_Object *obj,
210 unsigned int pos); /* 'Virtual' function on inserting an object to an (Edje) box part of the object, from its internal layout. The new child's position number is passed explicitly */
211 Evas_Object *(*box_remove)(Evas_Object * obj,
213 Evas_Object * child); /* 'Virtual' function on removing an object from an (Edje) box part of the object, on its internal layout */
214 Eina_Bool (*box_remove_all)(Evas_Object *obj,
216 Eina_Bool clear); /* 'Virtual' function on removing @b all objects from an (Edje) box part of the object, on its internal layout */
217 Eina_Bool (*table_pack)(Evas_Object *obj,
222 unsigned short colspan,
223 unsigned short rowspan); /* 'Virtual' function on inserting an object to an (Edje) table part of the object, from its internal layout */
224 Evas_Object *(*table_unpack)(Evas_Object * obj,
226 Evas_Object * child); /* 'Virtual' function on removing an object from an (Edje) table part of the object, on its internal layout */
227 Eina_Bool (*table_clear)(Evas_Object *obj,
229 Eina_Bool clear); /* 'Virtual' function on removing @b all objects from an (Edje) table part of the object, on its internal layout */
231 const Elm_Layout_Part_Alias_Description *content_aliases; /**< List of (@c 'SWALLOW') part aliases, <b>@c NULL terminated</b>. If @c NULL is passed as part name, it will be translated to the 1st _Elm_Layout_Part_Proxies_Description::real_part field in the list. */
233 const Elm_Layout_Part_Alias_Description *text_aliases; /**< List of (@c 'TEXT' or 'TEXTBLOCK') part aliases, <b>@c NULL terminated</b>. If @c NULL is passed as part name, it will be translated to the 1st _Elm_Layout_Part_Proxies_Description::real_part field in the list. */
234 } Elm_Layout_Smart_Class;
237 * Base widget smart data extended with layout instance data.
239 typedef struct _Elm_Layout_Smart_Data
241 Elm_Widget_Smart_Data base; /**< Base widget smart data as first member obligatory */
243 Eina_List *subs; /**< List of Elm_Layout_Sub_Object_Data structs, to hold the actual sub objects */
244 Eina_List *edje_signals;
245 Eina_List *parts_cursors;
246 const char *klass, *group;
248 Eina_Bool needs_size_calc : 1;
249 } Elm_Layout_Smart_Data;
255 EAPI extern const char ELM_LAYOUT_SMART_NAME[];
256 EAPI const Elm_Layout_Smart_Class *elm_layout_smart_class_get(void);
258 #define ELM_LAYOUT_DATA_GET(o, sd) \
259 Elm_Layout_Smart_Data * sd = evas_object_smart_data_get(o)
261 #define ELM_LAYOUT_DATA_GET_OR_RETURN(o, ptr) \
262 ELM_LAYOUT_DATA_GET(o, ptr); \
265 CRITICAL("No widget data for object %p (%s)", \
266 o, evas_object_type_get(o)); \
270 #define ELM_LAYOUT_DATA_GET_OR_RETURN_VAL(o, ptr, val) \
271 ELM_LAYOUT_DATA_GET(o, ptr); \
274 CRITICAL("No widget data for object %p (%s)", \
275 o, evas_object_type_get(o)); \
279 #define ELM_LAYOUT_CHECK(obj) \
280 if (!elm_widget_type_check((obj), ELM_LAYOUT_SMART_NAME, __func__)) \