src/lib/elm_object.h

   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 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 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 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 /**
  63  * Gets the original string set as translatable for an object
  64  *
  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.
  68  *
  69  * @param obj The object
  70  * @param part The name of the part that was set
  71  *
  72  * @return The original, untranslated string
  73  *
  74  * @see elm_object_translatable_part_text_set()
  75  *
  76  * @since 1.8
  77  *
  78  * @ingroup General
  79  */
  80 EAPI const char *elm_object_translatable_part_text_get(const Evas_Object *obj, const char *part);
  81
  82 #define elm_object_translatable_text_get(obj) elm_object_translatable_part_text_get((obj), NULL)
  83
  84 /**
  85  * Set the content on part of a given container widget
  86  *
  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
  91  *
  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.
  98  *
  99  * @see elm_object_part_content_set()
 100  *
 101  * @ingroup General
 102  */
 103 EAPI void                         elm_object_part_content_set(Evas_Object *obj, const char *part, Evas_Object *content);
 104
 105 #define elm_object_content_set(obj, content) elm_object_part_content_set((obj), NULL, (content))
 106
 107 /**
 108  * Get the content on a part of a given container widget
 109  *
 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
 114  *         errors
 115  *
 116  * @see elm_object_part_content_set() for more details
 117  *
 118  * @ingroup General
 119  */
 120 EAPI Evas_Object                 *elm_object_part_content_get(const Evas_Object *obj, const char *part);
 121
 122 #define elm_object_content_get(obj) elm_object_part_content_get((obj), NULL)
 123
 124 /**
 125  * Unset the content on a part of a given container widget
 126  *
 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
 131  *         errors
 132  *
 133  * @see elm_object_part_content_set() for more details
 134  *
 135  * @ingroup General
 136  */
 137 EAPI Evas_Object                 *elm_object_part_content_unset(Evas_Object *obj, const char *part);
 138
 139 #define elm_object_content_unset(obj) elm_object_part_content_unset((obj), NULL)
 140
 141 /**
 142  * Set the text to read out when in accessibility mode
 143  *
 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
 146  *
 147  * @ingroup General
 148  */
 149 EAPI void                         elm_object_access_info_set(Evas_Object *obj, const char *txt);
 150
 151 /**
 152  * Get a named object from the children
 153  *
 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
 158  *
 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
 167  * without limit.
 168  *
 169  * @ingroup General
 170  */
 171 EAPI Evas_Object                 *elm_object_name_find(const Evas_Object *obj, const char *name, int recurse);
 172
 173 /**
 174  * @defgroup Styles Styles
 175  *
 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)
 178  * do).
 179  *
 180  * @ref general_functions_example_page "This" example contemplates
 181  * some of these functions.
 182  */
 183
 184 /**
 185  * Set the style to used by a given widget
 186  *
 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
 190  *
 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.
 194  *
 195  * @see elm_theme_extension_add()
 196  * @see elm_theme_extension_del()
 197  * @see elm_theme_overlay_add()
 198  * @see elm_theme_overlay_del()
 199  *
 200  * @ingroup Styles
 201  */
 202 EAPI Eina_Bool    elm_object_style_set(Evas_Object *obj, const char *style);
 203
 204 /**
 205  * Get the style used by the widget
 206  *
 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
 209  * change.
 210  *
 211  * @param obj The Elementary widget to query for its style
 212  * @return The style name used
 213  *
 214  * @see elm_object_style_set()
 215  *
 216  * @ingroup Styles
 217  */
 218 EAPI const char  *elm_object_style_get(const Evas_Object *obj);
 219
 220 /**
 221  * Set the disabled state of an Elementary object.
 222  *
 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
 226  *
 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.
 232  *
 233  * This sets the state for the widget, either disabling it or
 234  * enabling it back.
 235  *
 236  * @ingroup Styles
 237  */
 238 EAPI void         elm_object_disabled_set(Evas_Object *obj, Eina_Bool disabled);
 239
 240 /**
 241  * Get the disabled state of an Elementary object.
 242  *
 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)
 246  *
 247  * This gets the state of the widget, which might be enabled or disabled.
 248  *
 249  * @ingroup Styles
 250  */
 251 EAPI Eina_Bool    elm_object_disabled_get(const Evas_Object *obj);
 252
 253 /**
 254  * @defgroup WidgetNavigation Widget Tree Navigation
 255  *
 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.
 259  */
 260
 261 /**
 262  * Check if the given Evas Object is an Elementary widget.
 263  *
 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
 268  */
 269 EAPI Eina_Bool    elm_object_widget_check(const Evas_Object *obj);
 270
 271 /**
 272  * Get the first parent of the given object that is an Elementary
 273  * widget.
 274  *
 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.
 278  *
 279  * Use this to query for an object's parent widget.
 280  *
 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.
 286  *
 287  * @ingroup WidgetNavigation
 288  */
 289 EAPI Evas_Object *elm_object_parent_widget_get(const Evas_Object *obj);
 290
 291 /**
 292  * Get the top level parent of an Elementary widget.
 293  *
 294  * @param obj The object to query.
 295  * @return The top level Elementary widget, or @c NULL if parent cannot be
 296  * found.
 297  * @ingroup WidgetNavigation
 298  */
 299 EAPI Evas_Object *elm_object_top_widget_get(const Evas_Object *obj);
 300
 301 /**
 302  * Get the string that represents this Elementary widget.
 303  *
 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.
 310  *
 311  * @param obj the object to query.
 312  * @return Elementary widget name, or @c NULL if not a valid widget.
 313  * @ingroup WidgetNavigation
 314  */
 315 EAPI const char  *elm_object_widget_type_get(const Evas_Object *obj);
 316
 317 /**
 318  * Send a signal to the widget edje object.
 319  *
 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.
 323  *
 324  * @param obj The object
 325  * @param emission The signal's name.
 326  * @param source The signal's source.
 327  * @ingroup General
 328  */
 329 EAPI void         elm_object_signal_emit(Evas_Object *obj, const char *emission, const char *source);
 330
 331 /**
 332  * Add a callback for a signal emitted by widget edje object.
 333  *
 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.
 337  *
 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
 342  * emitted.
 343  * @param data A pointer to data to pass in to the callback function.
 344  * @ingroup General
 345  */
 346 EAPI void         elm_object_signal_callback_add(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func, void *data);
 347
 348 /**
 349  * Remove a signal-triggered callback from a widget edje object.
 350  *
 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
 355  * emitted.
 356  * @return The data pointer of the signal callback or @c NULL, on
 357  * errors.
 358  *
 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.
 365  *
 366  * @ingroup General
 367  */
 368 EAPI void        *elm_object_signal_callback_del(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func);
 369
 370 /**
 371  * Add a callback for input events (key up, key down, mouse wheel)
 372  * on a given Elementary widget
 373  *
 374  * @param obj The widget to add an event callback on
 375  * @param func The callback function to be executed when the event
 376  * happens
 377  * @param data Data to pass in to @p func
 378  *
 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
 392  *   propagation, too.
 393  *
 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
 396  * event already.
 397  *
 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).
 402  *
 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.
 406  *
 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
 410  * object.
 411  *
 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.
 415  *
 416  * @see elm_object_event_callback_del()
 417  *
 418  * @ingroup General
 419  */
 420 EAPI void         elm_object_event_callback_add(Evas_Object *obj, Elm_Event_Cb func, const void *data);
 421
 422 /**
 423  * Remove an event callback from a widget.
 424  *
 425  * This function removes a callback, previously attached to event emission
 426  * by the @p obj.
 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.
 430  *
 431  * @param obj The object
 432  * @param func The callback function to be executed when the event is
 433  * emitted.
 434  * @param data Data to pass in to the callback function.
 435  * @return The data pointer
 436  * @ingroup General
 437  */
 438 EAPI void        *elm_object_event_callback_del(Evas_Object *obj, Elm_Event_Cb func, const void *data);
 439
 440 /**
 441  * Disable the orientation mode of a given widget.
 442  *
 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.
 449  *
 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.
 453  *
 454  * @since 1.8
 455  *
 456  * @ingroup General
 457  */
 458 EAPI void        elm_object_orientation_mode_disabled_set(Evas_Object *obj, Eina_Bool disabled);
 459
 460 /**
 461  * Get the orientation mode of a given widget.
 462  *
 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()
 467  *
 468  * @since 1.8
 469  *
 470  * @ingroup General
 471  */
 472 EAPI Eina_Bool   elm_object_orientation_mode_disabled_get(const Evas_Object *obj);
 473