1 /** 2 * Set a text of an object 3 * 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 7 * 8 * @note Elementary objects may have many text parts (e.g. Action Slider) 9 * 10 * @ingroup Elm_General 11 */ 12 EAPI void elm_object_part_text_set(Evas_Object *obj, const char *part, const char *text); 13 14 #define elm_object_text_set(obj, text) elm_object_part_text_set((obj), NULL, (text)) 15 16 /** 17 * Get a text of an object 18 * 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 22 * 23 * @note Elementary objects may have many text parts (e.g. Action Slider) 24 * 25 * @ingroup Elm_General 26 */ 27 EAPI const char *elm_object_part_text_get(const Evas_Object *obj, const char *part); 28 29 #define elm_object_text_get(obj) elm_object_part_text_get((obj), NULL) 30 31 /** 32 * Set the text for an object's part, marking it as translatable. 33 * 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(). 39 * 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. 46 * 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 51 * 52 * @since 1.8 53 * 54 * @ingroup Elm_General 55 */ 56 EAPI void elm_object_domain_translatable_part_text_set(Evas_Object *obj, const char *part, const char *domain, const char *text); 57 58 #define elm_object_domain_translatable_text_set(obj, domain, text) elm_object_domain_translatable_part_text_set((obj), NULL, (domain), (text)) 59 60 #define elm_object_translatable_text_set(obj, text) elm_object_domain_translatable_part_text_set((obj), NULL, NULL, (text)) 61 62 #define elm_object_translatable_part_text_set(obj, part, text) elm_object_domain_translatable_part_text_set((obj), (part), NULL, (text)) 63 64 /** 65 * Get the original string set as translatable for an object 66 * 67 * When setting translated strings, the function elm_object_part_text_get() 68 * will return the translation returned by @c gettext(). To get the 69 * original string use this function. 70 * 71 * @param obj The object 72 * @param part The name of the part that was set 73 * 74 * @return The original, untranslated string 75 * 76 * @see elm_object_translatable_part_text_set() 77 * 78 * @since 1.8 79 * 80 * @ingroup Elm_General 81 */ 82 EAPI const char *elm_object_translatable_part_text_get(const Evas_Object *obj, const char *part); 83 84 #define elm_object_translatable_text_get(obj) elm_object_translatable_part_text_get((obj), NULL) 85 86 /** 87 * Mark the part text to be translatable or not. 88 * 89 * Once you mark the part text to be translatable, the text will be translated 90 * internally regardless of elm_object_part_text_set() and 91 * elm_object_domain_translatable_part_text_set(). In other case, if you set the 92 * Elementary policy that all text will be translatable in default, you can set 93 * the part text to not be translated by calling this API. 94 * 95 * @param obj The object containing the text part 96 * @param part The part name of the translatable text 97 * @param domain The translation domain to use 98 * @param translatable @c EINA_TRUE, the part text will be translated 99 * internally. @c EINA_FALSE, otherwise. 100 * 101 * @see elm_object_domain_translatable_part_text_set() 102 * @see elm_object_part_text_set() 103 * @see elm_policy() 104 * 105 * @since 1.8 106 * 107 * @ingroup Elm_General 108 */ 109 EAPI void elm_object_domain_part_text_translatable_set(Evas_Object *obj, const char *part, const char *domain, Eina_Bool translatable); 110 111 #define elm_object_part_text_translatable_set(obj, part, translatable) elm_object_domain_part_text_translatable_set((obj), (part), NULL, (translatable)) 112 113 #define elm_object_domain_text_translatable_set(obj, domain, translatable) elm_object_domain_part_text_translatable_set((obj), NULL, (domain), (translatable)) 114 115 /** 116 * Set the content on part of a given container widget 117 * 118 * @param obj The Elementary container widget 119 * @param part The container's part name to set (some might accept 120 * @c NULL for the default part) 121 * @param content The new content for that part 122 * 123 * All widgets deriving from the @ref elm-container-class may hold 124 * child objects as content at given parts. This sets new content to 125 * a given part. If any object was already set as a content object in 126 * the same part, the previous object will be deleted automatically 127 * with this call. If the @p content is NULL, this call will just delete the 128 * previous object. If the If you wish to preserve it, issue 129 * elm_object_part_content_unset() on it first. 130 * 131 * @see elm_object_part_content_get() 132 * 133 * @ingroup Elm_General 134 */ 135 EAPI void elm_object_part_content_set(Evas_Object *obj, const char *part, Evas_Object *content); 136 137 #define elm_object_content_set(obj, content) elm_object_part_content_set((obj), NULL, (content)) 138 139 /** 140 * Get the content on a part of a given container widget 141 * 142 * @param obj The Elementary container widget 143 * @param part The container's part name to get (some might accept 144 * @c NULL for the default part) 145 * @return content of the object at the given part or @c NULL, on 146 * errors 147 * 148 * @see elm_object_part_content_set() for more details 149 * 150 * @ingroup Elm_General 151 */ 152 EAPI Evas_Object *elm_object_part_content_get(const Evas_Object *obj, const char *part); 153 154 #define elm_object_content_get(obj) elm_object_part_content_get((obj), NULL) 155 156 /** 157 * Unset the content on a part of a given container widget 158 * 159 * @param obj The Elementary container widget 160 * @param part The container's part name to unset (some might accept 161 * @c NULL for the default part) 162 * @return content of the object at the given part or @c NULL, on 163 * errors 164 * 165 * @see elm_object_part_content_set() for more details 166 * 167 * @ingroup Elm_General 168 */ 169 EAPI Evas_Object *elm_object_part_content_unset(Evas_Object *obj, const char *part); 170 171 #define elm_object_content_unset(obj) elm_object_part_content_unset((obj), NULL) 172 173 /** 174 * Set the text to read out when in accessibility mode 175 * 176 * @param obj The object which is to be described 177 * @param txt The text that describes the widget to people with poor or no vision 178 * 179 * @ingroup Elm_General 180 */ 181 EAPI void elm_object_access_info_set(Evas_Object *obj, const char *txt); 182 183 /** 184 * Get the text to read out when in accessibility mode 185 * 186 * @param obj The object which is to be described 187 * @return The text that describes the widget to people with poor or no vision 188 * 189 * @ingroup Elm_General 190 * 191 * @since 1.14 192 */ 193 EAPI const char *elm_object_access_info_get(Evas_Object *obj); 194 195 /** 196 * Get a named object from the children 197 * 198 * @param obj The parent object whose children to look at 199 * @param name The name of the child to find 200 * @param recurse Set to the maximum number of levels to recurse (0 == none, 1 is only look at 1 level of children etc.) 201 * @return The found object of that name, or NULL if none is found 202 * 203 * This function searches the children (or recursively children of 204 * children and so on) of the given @p obj object looking for a child with 205 * the name of @p name. If the child is found the object is returned, or 206 * NULL is returned. You can set the name of an object with 207 * evas_object_name_set(). If the name is not unique within the child 208 * objects (or the tree is @p recurse is greater than 0) then it is 209 * undefined as to which child of that name is returned, so ensure the name 210 * is unique amongst children. If recurse is set to -1 it will recurse 211 * without limit. 212 * 213 * @ingroup Elm_General 214 */ 215 EAPI Evas_Object *elm_object_name_find(const Evas_Object *obj, const char *name, int recurse); 216 217 /** 218 * @defgroup Elm_Styles Styles 219 * 220 * Widgets can have different styles of look. These generic API's 221 * set styles of widgets, if they support them (and if the theme(s) 222 * do). 223 * 224 * @ref general_functions_example_page "This" example contemplates 225 * some of these functions. 226 */ 227 228 /** 229 * Set the style to used by a given widget 230 * 231 * @param obj The Elementary widget to style 232 * @param style The name of the style to use on it 233 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise 234 * 235 * This sets the style (by name) that will define the appearance of a 236 * widget. Styles vary from widget to widget and may also be defined 237 * by other themes by means of extensions and overlays. 238 * 239 * @see elm_theme_extension_add() 240 * @see elm_theme_extension_del() 241 * @see elm_theme_overlay_add() 242 * @see elm_theme_overlay_del() 243 * 244 * @ingroup Elm_Styles 245 */ 246 EAPI Eina_Bool elm_object_style_set(Evas_Object *obj, const char *style); 247 248 /** 249 * Get the style used by the widget 250 * 251 * This gets the style being used for that widget. Note that the string 252 * pointer is only valid as long as the object is valid and the style doesn't 253 * change. 254 * 255 * @param obj The Elementary widget to query for its style 256 * @return The style name used 257 * 258 * @see elm_object_style_set() 259 * 260 * @ingroup Elm_Styles 261 */ 262 EAPI const char *elm_object_style_get(const Evas_Object *obj); 263 264 /** 265 * Set the disabled state of an Elementary object. 266 * 267 * @param obj The Elementary object to operate on 268 * @param disabled The state to put in in: @c EINA_TRUE for 269 * disabled, @c EINA_FALSE for enabled 270 * 271 * Elementary objects can be @b disabled, in which state they won't 272 * receive input and, in general, will be themed differently from 273 * their normal state, usually greyed out. Useful for contexts 274 * where you don't want your users to interact with some of the 275 * parts of you interface. 276 * 277 * This sets the state for the widget, either disabling it or 278 * enabling it back. 279 * 280 * @ingroup Elm_General 281 */ 282 EAPI void elm_object_disabled_set(Evas_Object *obj, Eina_Bool disabled); 283 284 /** 285 * Get the disabled state of an Elementary object. 286 * 287 * @param obj The Elementary object to operate on 288 * @return @c EINA_TRUE, if the widget is disabled, @c EINA_FALSE 289 * if it's enabled (or on errors) 290 * 291 * This gets the state of the widget, which might be enabled or disabled. 292 * 293 * @ingroup Elm_General 294 */ 295 EAPI Eina_Bool elm_object_disabled_get(const Evas_Object *obj); 296 297 /** 298 * @defgroup Elm_WidgetNavigation Widget Tree Navigation 299 * 300 * These functions provide checks for if a Evas_Object is an Elementary widget, 301 * the possibility of getting a widget's parent, top level parent and getting a 302 * string representation of a widget's type. 303 */ 304 305 /** 306 * Check if the given Evas Object is an Elementary widget. 307 * 308 * @param obj the object to query. 309 * @return @c EINA_TRUE if it is an elementary widget variant, 310 * @c EINA_FALSE otherwise 311 * @ingroup Elm_WidgetNavigation 312 */ 313 EAPI Eina_Bool elm_object_widget_check(const Evas_Object *obj); 314 315 /** 316 * Get the first parent of the given object that is an Elementary 317 * widget. 318 * 319 * @param obj the Elementary object to query parent from. 320 * @return the parent object that is an Elementary widget, or @c 321 * NULL, if it was not found. 322 * 323 * Use this to query for an object's parent widget. 324 * 325 * @note Most of Elementary users wouldn't be mixing non-Elementary 326 * smart objects in the objects tree of an application, as this is 327 * an advanced usage of Elementary with Evas. So, except for the 328 * application's window, which is the root of that tree, all other 329 * objects would have valid Elementary widget parents. 330 * 331 * @ingroup Elm_WidgetNavigation 332 */ 333 EAPI Evas_Object *elm_object_parent_widget_get(const Evas_Object *obj); 334 335 /** 336 * Get the top level parent of an Elementary widget. 337 * 338 * @param obj The object to query. 339 * @return The top level Elementary widget, or @c NULL if parent cannot be 340 * found. 341 * @ingroup Elm_WidgetNavigation 342 */ 343 EAPI Evas_Object *elm_object_top_widget_get(const Evas_Object *obj); 344 345 /** 346 * Get the string that represents this Elementary widget. 347 * 348 * @param obj the object to query. 349 * @return Elementary widget name, or @c NULL if not a valid widget. 350 * @ingroup Elm_WidgetNavigation 351 */ 352 EAPI const char *elm_object_widget_type_get(const Evas_Object *obj); 353 354 /** 355 * Send a signal to the widget edje object. 356 * 357 * This function sends a signal to the edje object of the obj. An 358 * edje program can respond to a signal by specifying matching 359 * 'signal' and 'source' fields. 360 * 361 * @param obj The object 362 * @param emission The signal's name. 363 * @param source The signal's source. 364 * @ingroup Elm_General 365 */ 366 EAPI void elm_object_signal_emit(Evas_Object *obj, const char *emission, const char *source); 367 368 /** 369 * Add a callback for a signal emitted by widget edje object. 370 * 371 * This function connects a callback function to a signal emitted by the 372 * edje object of the obj. 373 * Globs can occur in either the emission or source name. 374 * 375 * @param obj The object 376 * @param emission The signal's name. 377 * @param source The signal's source. 378 * @param func The callback function to be executed when the signal is 379 * emitted. 380 * @param data A pointer to data to pass to the callback function. 381 * @ingroup Elm_General 382 */ 383 EAPI void elm_object_signal_callback_add(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func, void *data); 384 385 /** 386 * Remove a signal-triggered callback from a widget edje object. 387 * 388 * @param obj The object handle 389 * @param emission The signal's name. 390 * @param source The signal's source. 391 * @param func The callback function to be executed when the signal is 392 * emitted. 393 * @return The data pointer of the signal callback or @c NULL, on 394 * errors. 395 * 396 * This function removes the @b last callback, previously attached to 397 * a signal emitted by an underlying Edje object of @a obj, whose 398 * parameters @a emission, @a source and @c func match exactly with 399 * those passed to a previous call to 400 * elm_object_signal_callback_add(). The data pointer that was passed 401 * to this call will be returned. 402 * 403 * @ingroup Elm_General 404 */ 405 EAPI void *elm_object_signal_callback_del(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func); 406 407 /** 408 * Add a callback for input events (key up, key down, mouse wheel) 409 * on a given Elementary widget 410 * 411 * @param obj The widget to add an event callback on 412 * @param func The callback function to be executed when the event 413 * happens 414 * @param data Data to pass in to @p func 415 * 416 * Every widget in an Elementary interface set to receive focus, 417 * with elm_object_focus_allow_set(), will propagate @b all of its 418 * key up, key down and mouse wheel input events up to its parent 419 * object, and so on. All of the focusable ones in this chain which 420 * had an event callback set, with this call, will be able to treat 421 * those events. There are two ways of making the propagation of 422 * these event upwards in the tree of widgets to @b cease: 423 * - Just return @c EINA_TRUE on @p func. @c EINA_FALSE will mean 424 * the event was @b not processed, so the propagation will go on. 425 * - The @p event_info pointer passed to @p func will contain the 426 * event's structure and, if you OR its @c event_flags inner 427 * value to @c EVAS_EVENT_FLAG_ON_HOLD, you're telling Elementary 428 * one has already handled it, thus killing the event's 429 * propagation, too. 430 * 431 * @note Your event callback will be issued on those events taking 432 * place only if no other child widget of @p obj has consumed the 433 * event already. 434 * 435 * @note Not to be confused with @c 436 * evas_object_event_callback_add(), which will add event callbacks 437 * per type on general Evas objects (no event propagation 438 * infrastructure taken in account). 439 * 440 * @note Not to be confused with @c 441 * elm_object_signal_callback_add(), which will add callbacks to @b 442 * signals coming from a widget's theme, not input events. 443 * 444 * @note Not to be confused with @c 445 * edje_object_signal_callback_add(), which does the same as 446 * elm_object_signal_callback_add(), but directly on an Edje 447 * object. 448 * 449 * @note Not to be confused with @c 450 * evas_object_smart_callback_add(), which adds callbacks to smart 451 * objects' <b>smart events</b>, and not input events. 452 * 453 * @see elm_object_event_callback_del() 454 * 455 * @ingroup Elm_General 456 */ 457 EAPI void elm_object_event_callback_add(Evas_Object *obj, Elm_Event_Cb func, const void *data); 458 459 /** 460 * Remove an event callback from a widget. 461 * 462 * This function removes a callback, previously attached to event emission 463 * by the @p obj. 464 * The parameters func and data must match exactly those passed to 465 * a previous call to elm_object_event_callback_add(). The data pointer that 466 * was passed to this call will be returned. 467 * 468 * @param obj The object 469 * @param func The callback function to be executed when the event is 470 * emitted. 471 * @param data Data to pass in to the callback function. 472 * @return The data pointer 473 * @ingroup Elm_General 474 */ 475 EAPI void *elm_object_event_callback_del(Evas_Object *obj, Elm_Event_Cb func, const void *data); 476 477 /** 478 * Disable the orientation mode of a given widget. 479 * 480 * Orientation Mode is used for widgets to change it's styles or to send signals 481 * whenever it's window degree is changed. If the orientation mode is enabled 482 * and the widget has different looks and styles for the window degree(0, 90, 483 * 180, 270), it will apply a style that is readied for the current degree, 484 * otherwise, it will send signals to it's own edje to change it's states if 485 * the style doesn't be readied. 486 * 487 * @param obj The Elementary object to operate on orientation mode. 488 * @param disabled The state to put in in: @c EINA_TRUE for disabled, 489 * @c EINA_FALSE for enabled. 490 * 491 * @since 1.8 492 * 493 * @ingroup Elm_General 494 */ 495 EAPI void elm_object_orientation_mode_disabled_set(Evas_Object *obj, Eina_Bool disabled); 496 497 /** 498 * Get the orientation mode of a given widget. 499 * 500 * @param obj The Elementary widget to query for its orientation mode. 501 * @return @c EINA_TRUE, if the orientation mode is disabled, @c EINA_FALSE 502 * if the orientation mode is enabled (or on errors) 503 * @see elm_object_orientation_mode_disabled_set() 504 * 505 * @since 1.8 506 * 507 * @ingroup Elm_General 508 */ 509 EAPI Eina_Bool elm_object_orientation_mode_disabled_get(const Evas_Object *obj); 510 511