2 * Set a text of an object
4 * @param obj The Elementary object
5 * @param part The text part name to set (NULL for the default part)
6 * @param text The new text of the part
8 * @note Elementary objects may have many text parts (e.g. Action Slider)
12 EAPI void elm_object_part_text_set(Evas_Object *obj, const char *part, const char *text);
14 #define elm_object_text_set(obj, text) elm_object_part_text_set((obj), NULL, (text))
17 * Get a text of an object
19 * @param obj The Elementary object
20 * @param part The text part name to get (NULL for the default part)
21 * @return text of the part or NULL for any error
23 * @note Elementary objects may have many text parts (e.g. Action Slider)
27 EAPI const char *elm_object_part_text_get(const Evas_Object *obj, const char *part);
29 #define elm_object_text_get(obj) elm_object_part_text_get((obj), NULL)
32 * Set the text for an object's part, marking it as translatable.
34 * The string to set as @p text must be the original one. Do not pass the
35 * return of @c gettext() here. Elementary will translate the string
36 * internally and set it on the object using elm_object_part_text_set(),
37 * also storing the original string so that it can be automatically
38 * translated when the language is changed with elm_language_set().
40 * The @p domain will be stored along to find the translation in the
41 * correct catalog. It can be NULL, in which case it will use whatever
42 * domain was set by the application with @c textdomain(). This is useful
43 * in case you are building a library on top of Elementary that will have
44 * its own translatable strings, that should not be mixed with those of
45 * programs using the library.
47 * @param obj The object containing the text part
48 * @param part The name of the part to set
49 * @param domain The translation domain to use
50 * @param text The original, non-translated text to set
56 EAPI void elm_object_domain_translatable_part_text_set(Evas_Object *obj, const char *part, const char *domain, const char *text);
58 #define elm_object_domain_translatable_text_set(obj, domain, text) elm_object_domain_translatable_part_text_set((obj), NULL, (domain), (text))
60 #define elm_object_translatable_text_set(obj, text) elm_object_domain_translatable_part_text_set((obj), NULL, NULL, (text))
63 * Gets the original string set as translatable for an object
65 * When setting translated strings, the function elm_object_part_text_get()
66 * will return the translation returned by @c gettext(). To get the
67 * original string use this function.
69 * @param obj The object
70 * @param part The name of the part that was set
72 * @return The original, untranslated string
74 * @see elm_object_translatable_part_text_set()
80 EAPI const char *elm_object_translatable_part_text_get(const Evas_Object *obj, const char *part);
82 #define elm_object_translatable_text_get(obj) elm_object_translatable_part_text_get((obj), NULL)
85 * Set the content on part of a given container widget
87 * @param obj The Elementary container widget
88 * @param part The container's part name to set (some might accept
89 * @c NULL for the default part)
90 * @param content The new content for that part
92 * All widgets deriving from the @ref elm-container-class may hold
93 * child objects as content at given parts. This sets new content to
94 * a given part. If any object was already set as a content object in
95 * the same part, the previous object will be deleted automatically
96 * with this call. If you wish to preserve it, issue
97 * elm_object_part_content_unset() on it first.
99 * @see elm_object_part_content_set()
103 EAPI void elm_object_part_content_set(Evas_Object *obj, const char *part, Evas_Object *content);
105 #define elm_object_content_set(obj, content) elm_object_part_content_set((obj), NULL, (content))
108 * Get the content on a part of a given container widget
110 * @param obj The Elementary container widget
111 * @param part The container's part name to get (some might accept
112 * @c NULL for the default part)
113 * @return content of the object at the given part or @c NULL, on
116 * @see elm_object_part_content_set() for more details
120 EAPI Evas_Object *elm_object_part_content_get(const Evas_Object *obj, const char *part);
122 #define elm_object_content_get(obj) elm_object_part_content_get((obj), NULL)
125 * Unset the content on a part of a given container widget
127 * @param obj The Elementary container widget
128 * @param part The container's part name to unset (some might accept
129 * @c NULL for the default part)
130 * @return content of the object at the given part or @c NULL, on
133 * @see elm_object_part_content_set() for more details
137 EAPI Evas_Object *elm_object_part_content_unset(Evas_Object *obj, const char *part);
139 #define elm_object_content_unset(obj) elm_object_part_content_unset((obj), NULL)
142 * Set the text to read out when in accessibility mode
144 * @param obj The object which is to be described
145 * @param txt The text that describes the widget to people with poor or no vision
149 EAPI void elm_object_access_info_set(Evas_Object *obj, const char *txt);
152 * Get a named object from the children
154 * @param obj The parent object whose children to look at
155 * @param name The name of the child to find
156 * @param recurse Set to the maximum number of levels to recurse (0 == none, 1 is only look at 1 level of children etc.)
157 * @return The found object of that name, or NULL if none is found
159 * This function searches the children (or recursively children of
160 * children and so on) of the given @p obj object looking for a child with
161 * the name of @p name. If the child is found the object is returned, or
162 * NULL is returned. You can set the name of an object with
163 * evas_object_name_set(). If the name is not unique within the child
164 * objects (or the tree is @p recurse is greater than 0) then it is
165 * undefined as to which child of that name is returned, so ensure the name
166 * is unique amongst children. If recurse is set to -1 it will recurse
171 EAPI Evas_Object *elm_object_name_find(const Evas_Object *obj, const char *name, int recurse);
174 * @defgroup Styles Styles
176 * Widgets can have different styles of look. These generic API's
177 * set styles of widgets, if they support them (and if the theme(s)
180 * @ref general_functions_example_page "This" example contemplates
181 * some of these functions.
185 * Set the style to used by a given widget
187 * @param obj The Elementary widget to style
188 * @param style The name of the style to use on it
189 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
191 * This sets the style (by name) that will define the appearance of a
192 * widget. Styles vary from widget to widget and may also be defined
193 * by other themes by means of extensions and overlays.
195 * @see elm_theme_extension_add()
196 * @see elm_theme_extension_del()
197 * @see elm_theme_overlay_add()
198 * @see elm_theme_overlay_del()
202 EAPI Eina_Bool elm_object_style_set(Evas_Object *obj, const char *style);
205 * Get the style used by the widget
207 * This gets the style being used for that widget. Note that the string
208 * pointer is only valid as long as the object is valid and the style doesn't
211 * @param obj The Elementary widget to query for its style
212 * @return The style name used
214 * @see elm_object_style_set()
218 EAPI const char *elm_object_style_get(const Evas_Object *obj);
221 * Set the disabled state of an Elementary object.
223 * @param obj The Elementary object to operate on
224 * @param disabled The state to put in in: @c EINA_TRUE for
225 * disabled, @c EINA_FALSE for enabled
227 * Elementary objects can be @b disabled, in which state they won't
228 * receive input and, in general, will be themed differently from
229 * their normal state, usually greyed out. Useful for contexts
230 * where you don't want your users to interact with some of the
231 * parts of you interface.
233 * This sets the state for the widget, either disabling it or
238 EAPI void elm_object_disabled_set(Evas_Object *obj, Eina_Bool disabled);
241 * Get the disabled state of an Elementary object.
243 * @param obj The Elementary object to operate on
244 * @return @c EINA_TRUE, if the widget is disabled, @c EINA_FALSE
245 * if it's enabled (or on errors)
247 * This gets the state of the widget, which might be enabled or disabled.
251 EAPI Eina_Bool elm_object_disabled_get(const Evas_Object *obj);
254 * @defgroup WidgetNavigation Widget Tree Navigation
256 * These functions provide checks for if a Evas_Object is an Elementary widget,
257 * the possibility of getting a widget's parent, top level parent and getting a
258 * string representation of a widget's type.
262 * Check if the given Evas Object is an Elementary widget.
264 * @param obj the object to query.
265 * @return @c EINA_TRUE if it is an elementary widget variant,
266 * @c EINA_FALSE otherwise
267 * @ingroup WidgetNavigation
269 EAPI Eina_Bool elm_object_widget_check(const Evas_Object *obj);
272 * Get the first parent of the given object that is an Elementary
275 * @param obj the Elementary object to query parent from.
276 * @return the parent object that is an Elementary widget, or @c
277 * NULL, if it was not found.
279 * Use this to query for an object's parent widget.
281 * @note Most of Elementary users wouldn't be mixing non-Elementary
282 * smart objects in the objects tree of an application, as this is
283 * an advanced usage of Elementary with Evas. So, except for the
284 * application's window, which is the root of that tree, all other
285 * objects would have valid Elementary widget parents.
287 * @ingroup WidgetNavigation
289 EAPI Evas_Object *elm_object_parent_widget_get(const Evas_Object *obj);
292 * Get the top level parent of an Elementary widget.
294 * @param obj The object to query.
295 * @return The top level Elementary widget, or @c NULL if parent cannot be
297 * @ingroup WidgetNavigation
299 EAPI Evas_Object *elm_object_top_widget_get(const Evas_Object *obj);
302 * Get the string that represents this Elementary widget.
304 * @note Elementary is weird and exposes itself as a single
305 * Evas_Object_Smart_Class of type "elm_widget", so
306 * evas_object_type_get() always return that, making debug and
307 * language bindings hard. This function tries to mitigate this
308 * problem, but the solution is to change Elementary to use
309 * proper inheritance.
311 * @param obj the object to query.
312 * @return Elementary widget name, or @c NULL if not a valid widget.
313 * @ingroup WidgetNavigation
315 EAPI const char *elm_object_widget_type_get(const Evas_Object *obj);
318 * Send a signal to the widget edje object.
320 * This function sends a signal to the edje object of the obj. An
321 * edje program can respond to a signal by specifying matching
322 * 'signal' and 'source' fields.
324 * @param obj The object
325 * @param emission The signal's name.
326 * @param source The signal's source.
329 EAPI void elm_object_signal_emit(Evas_Object *obj, const char *emission, const char *source);
332 * Add a callback for a signal emitted by widget edje object.
334 * This function connects a callback function to a signal emitted by the
335 * edje object of the obj.
336 * Globs can occur in either the emission or source name.
338 * @param obj The object
339 * @param emission The signal's name.
340 * @param source The signal's source.
341 * @param func The callback function to be executed when the signal is
343 * @param data A pointer to data to pass in to the callback function.
346 EAPI void elm_object_signal_callback_add(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func, void *data);
349 * Remove a signal-triggered callback from a widget edje object.
351 * @param obj The object handle
352 * @param emission The signal's name.
353 * @param source The signal's source.
354 * @param func The callback function to be executed when the signal is
356 * @return The data pointer of the signal callback or @c NULL, on
359 * This function removes the @b last callback, previously attached to
360 * a signal emitted by an undelying Edje object of @a obj, whose
361 * parameters @a emission, @a source and @c func match exactly with
362 * those passed to a previous call to
363 * elm_object_signal_callback_add(). The data pointer that was passed
364 * to this call will be returned.
368 EAPI void *elm_object_signal_callback_del(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func);
371 * Add a callback for input events (key up, key down, mouse wheel)
372 * on a given Elementary widget
374 * @param obj The widget to add an event callback on
375 * @param func The callback function to be executed when the event
377 * @param data Data to pass in to @p func
379 * Every widget in an Elementary interface set to receive focus,
380 * with elm_object_focus_allow_set(), will propagate @b all of its
381 * key up, key down and mouse wheel input events up to its parent
382 * object, and so on. All of the focusable ones in this chain which
383 * had an event callback set, with this call, will be able to treat
384 * those events. There are two ways of making the propagation of
385 * these event upwards in the tree of widgets to @b cease:
386 * - Just return @c EINA_TRUE on @p func. @c EINA_FALSE will mean
387 * the event was @b not processed, so the propagation will go on.
388 * - The @c event_info pointer passed to @p func will contain the
389 * event's structure and, if you OR its @c event_flags inner
390 * value to @c EVAS_EVENT_FLAG_ON_HOLD, you're telling Elementary
391 * one has already handled it, thus killing the event's
394 * @note Your event callback will be issued on those events taking
395 * place only if no other child widget of @p obj has consumed the
398 * @note Not to be confused with @c
399 * evas_object_event_callback_add(), which will add event callbacks
400 * per type on general Evas objects (no event propagation
401 * infrastructure taken in account).
403 * @note Not to be confused with @c
404 * elm_object_signal_callback_add(), which will add callbacks to @b
405 * signals coming from a widget's theme, not input events.
407 * @note Not to be confused with @c
408 * edje_object_signal_callback_add(), which does the same as
409 * elm_object_signal_callback_add(), but directly on an Edje
412 * @note Not to be confused with @c
413 * evas_object_smart_callback_add(), which adds callbacks to smart
414 * objects' <b>smart events</b>, and not input events.
416 * @see elm_object_event_callback_del()
420 EAPI void elm_object_event_callback_add(Evas_Object *obj, Elm_Event_Cb func, const void *data);
423 * Remove an event callback from a widget.
425 * This function removes a callback, previously attached to event emission
427 * The parameters func and data must match exactly those passed to
428 * a previous call to elm_object_event_callback_add(). The data pointer that
429 * was passed to this call will be returned.
431 * @param obj The object
432 * @param func The callback function to be executed when the event is
434 * @param data Data to pass in to the callback function.
435 * @return The data pointer
438 EAPI void *elm_object_event_callback_del(Evas_Object *obj, Elm_Event_Cb func, const void *data);
441 * Disable the orientation mode of a given widget.
443 * Orientation Mode is used for widgets to change it's styles or to send signals
444 * whenever it's window degree is changed. If the orientation mode is enabled
445 * and the widget has different looks and styles for the window degree(0, 90,
446 * 180, 270), it will apply a style that is readied for the current degree,
447 * otherwise, it will send signals to it's own edje to change it's states if
448 * the style doesn't be readied.
450 * @param obj The Elementary object to operate on orientation mode.
451 * @param disabled The state to put in in: @c EINA_TRUE for disabled,
452 * @c EINA_FALSE for enabled.
458 EAPI void elm_object_orientation_mode_disabled_set(Evas_Object *obj, Eina_Bool disabled);
461 * Get the orientation mode of a given widget.
463 * @param obj The Elementary widget to query for its orientation mode.
464 * @return @c EINA_TRUE, if the orientation mode is disabled, @c EINA_FALSE
465 * if the orientation mode is enabled (or on errors)
466 * @see elm_object_orientation_mode_disabled_set()
472 EAPI Eina_Bool elm_object_orientation_mode_disabled_get(const Evas_Object *obj);