src/lib/elm_object.h

   1 /**
   2  * Set a label of an object
   3  *
   4  * @param obj The Elementary object
   5  * @param part The text part name to set (NULL for the default label)
   6  * @param label The new text of the label
   7  *
   8  * @note Elementary objects may have many labels (e.g. Action Slider)
   9  * @deprecated Use elm_object_part_text_set() instead.
  10  * @ingroup General
  11  */
  12 EINA_DEPRECATED EAPI void         elm_object_text_part_set(Evas_Object *obj, const char *part, const char *label);
  13
  14 /**
  15  * Set a label of an object
  16  *
  17  * @param obj The Elementary object
  18  * @param part The text part name to set (NULL for the default label)
  19  * @param label The new text of the label
  20  *
  21  * @note Elementary objects may have many labels (e.g. Action Slider)
  22  *
  23  * @ingroup General
  24  */
  25 EAPI void                         elm_object_part_text_set(Evas_Object *obj, const char *part, const char *label);
  26
  27 #define elm_object_text_set(obj, label) elm_object_part_text_set((obj), NULL, (label))
  28
  29 /**
  30  * Get a label of an object
  31  *
  32  * @param obj The Elementary object
  33  * @param part The text part name to get (NULL for the default label)
  34  * @return text of the label or NULL for any error
  35  *
  36  * @note Elementary objects may have many labels (e.g. Action Slider)
  37  * @deprecated Use elm_object_part_text_get() instead.
  38  * @ingroup General
  39  */
  40 EINA_DEPRECATED EAPI const char  *elm_object_text_part_get(const Evas_Object *obj, const char *part);
  41
  42 /**
  43  * Get a label of an object
  44  *
  45  * @param obj The Elementary object
  46  * @param part The text part name to get (NULL for the default label)
  47  * @return text of the label or NULL for any error
  48  *
  49  * @note Elementary objects may have many labels (e.g. Action Slider)
  50  *
  51  * @ingroup General
  52  */
  53 EAPI const char                  *elm_object_part_text_get(const Evas_Object *obj, const char *part);
  54
  55 #define elm_object_text_get(obj) elm_object_part_text_get((obj), NULL)
  56
  57 /**
  58  * Set a content of an object
  59  *
  60  * @param obj The Elementary object
  61  * @param part The content part name to set (NULL for the default content)
  62  * @param content The new content of the object
  63  *
  64  * @note Elementary objects may have many contents
  65  * @deprecated Use elm_object_part_content_set instead.
  66  * @ingroup General
  67  */
  68 EINA_DEPRECATED EAPI void         elm_object_content_part_set(Evas_Object *obj, const char *part, Evas_Object *content);
  69
  70 /**
  71  * Set a content of an object
  72  *
  73  * @param obj The Elementary object
  74  * @param part The content part name to set (NULL for the default content)
  75  * @param content The new content of the object
  76  *
  77  * @note Elementary objects may have many contents
  78  *
  79  * @ingroup General
  80  */
  81 EAPI void                         elm_object_part_content_set(Evas_Object *obj, const char *part, Evas_Object *content);
  82
  83 #define elm_object_content_set(obj, content) elm_object_part_content_set((obj), NULL, (content))
  84
  85 /**
  86  * Get a content of an object
  87  *
  88  * @param obj The Elementary object
  89  * @param item The content part name to get (NULL for the default content)
  90  * @return content of the object or NULL for any error
  91  *
  92  * @note Elementary objects may have many contents
  93  * @deprecated Use elm_object_part_content_get instead.
  94  * @ingroup General
  95  */
  96 EINA_DEPRECATED EAPI Evas_Object *elm_object_content_part_get(const Evas_Object *obj, const char *part);
  97
  98 /**
  99  * Get a content of an object
 100  *
 101  * @param obj The Elementary object
 102  * @param item The content part name to get (NULL for the default content)
 103  * @return content of the object or NULL for any error
 104  *
 105  * @note Elementary objects may have many contents
 106  *
 107  * @ingroup General
 108  */
 109 EAPI Evas_Object                 *elm_object_part_content_get(const Evas_Object *obj, const char *part);
 110
 111 #define elm_object_content_get(obj) elm_object_part_content_get((obj), NULL)
 112
 113 /**
 114  * Unset a content of an object
 115  *
 116  * @param obj The Elementary object
 117  * @param item The content part name to unset (NULL for the default content)
 118  *
 119  * @note Elementary objects may have many contents
 120  * @deprecated Use elm_object_part_content_unset instead.
 121  * @ingroup General
 122  */
 123 EINA_DEPRECATED EAPI Evas_Object *elm_object_content_part_unset(Evas_Object *obj, const char *part);
 124
 125 /**
 126  * Unset a content of an object
 127  *
 128  * @param obj The Elementary object
 129  * @param item The content part name to unset (NULL for the default content)
 130  *
 131  * @note Elementary objects may have many contents
 132  *
 133  * @ingroup General
 134  */
 135 EAPI Evas_Object                 *elm_object_part_content_unset(Evas_Object *obj, const char *part);
 136
 137 #define elm_object_content_unset(obj) elm_object_part_content_unset((obj), NULL)
 138
 139 /**
 140  * Set the text to read out when in accessibility mode
 141  *
 142  * @param obj The object which is to be described
 143  * @param txt The text that describes the widget to people with poor or no vision
 144  *
 145  * @ingroup General
 146  */
 147 EAPI void                         elm_object_access_info_set(Evas_Object *obj, const char *txt);
 148
 149 /**
 150  * Get a named object from the children
 151  *
 152  * @param obj The parent object whose children to look at
 153  * @param name The name of the child to find
 154  * @param recurse Set to thge maximum number of levels to recurse (0 == none, 1 is only look at 1 level of children etc.)
 155  * @return The found object of that name, or NULL if none is found
 156  *
 157  * This function searches the children (or recursively children of
 158  * children and so on) of the given @p obj object looking for a child with
 159  * the name of @p name. If the child is found the object is returned, or
 160  * NULL is returned. You can set the name of an object with
 161  * evas_object_name_set(). If the name is not unique within the child
 162  * objects (or the tree is @p recurse is greater than 0) then it is
 163  * undefined as to which child of that name is returned, so ensure the name
 164  * is unique amongst children. If recurse is set to -1 it will recurse
 165  * without limit.
 166  *
 167  * @ingroup General
 168  */
 169 EAPI Evas_Object                 *elm_object_name_find(const Evas_Object *obj, const char *name, int recurse);
 170
 171 /**
 172  * @defgroup Styles Styles
 173  *
 174  * Widgets can have different styles of look. These generic API's
 175  * set styles of widgets, if they support them (and if the theme(s)
 176  * do).
 177  *
 178  * @ref general_functions_example_page "This" example contemplates
 179  * some of these functions.
 180  */
 181
 182 /**
 183  * Set the style to use by a widget
 184  *
 185  * Sets the style name that will define the appearance of a widget. Styles
 186  * vary from widget to widget and may also be defined by other themes
 187  * by means of extensions and overlays.
 188  *
 189  * @param obj The Elementary widget to style
 190  * @param style The style name to use
 191  *
 192  * @see elm_theme_extension_add()
 193  * @see elm_theme_extension_del()
 194  * @see elm_theme_overlay_add()
 195  * @see elm_theme_overlay_del()
 196  *
 197  * @ingroup Styles
 198  */
 199 EAPI void
 200                   elm_object_style_set(Evas_Object *obj, const char *style)
 201 EINA_ARG_NONNULL(1);
 202
 203 /**
 204  * Get the style used by the widget
 205  *
 206  * This gets the style being used for that widget. Note that the string
 207  * pointer is only valid as longas the object is valid and the style doesn't
 208  * change.
 209  *
 210  * @param obj The Elementary widget to query for its style
 211  * @return The style name used
 212  *
 213  * @see elm_object_style_set()
 214  *
 215  * @ingroup Styles
 216  */
 217 EAPI const char  *elm_object_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 218
 219 /**
 220  * Set the disabled state of an Elementary object.
 221  *
 222  * @param obj The Elementary object to operate on
 223  * @param disabled The state to put in in: @c EINA_TRUE for
 224  *        disabled, @c EINA_FALSE for enabled
 225  *
 226  * Elementary objects can be @b disabled, in which state they won't
 227  * receive input and, in general, will be themed differently from
 228  * their normal state, usually greyed out. Useful for contexts
 229  * where you don't want your users to interact with some of the
 230  * parts of you interface.
 231  *
 232  * This sets the state for the widget, either disabling it or
 233  * enabling it back.
 234  *
 235  * @ingroup Styles
 236  */
 237 EAPI void         elm_object_disabled_set(Evas_Object *obj, Eina_Bool disabled) EINA_ARG_NONNULL(1);
 238
 239 /**
 240  * Get the disabled state of an Elementary object.
 241  *
 242  * @param obj The Elementary object to operate on
 243  * @return @c EINA_TRUE, if the widget is disabled, @c EINA_FALSE
 244  *            if it's enabled (or on errors)
 245  *
 246  * This gets the state of the widget, which might be enabled or disabled.
 247  *
 248  * @ingroup Styles
 249  */
 250 EAPI Eina_Bool    elm_object_disabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 251
 252 /**
 253  * @defgroup WidgetNavigation Widget Tree Navigation.
 254  *
 255  * How to check if an Evas Object is an Elementary widget? How to
 256  * get the first elementary widget that is parent of the given
 257  * object?  These are all covered in widget tree navigation.
 258  *
 259  * @ref general_functions_example_page "This" example contemplates
 260  * some of these functions.
 261  */
 262
 263 /**
 264  * Check if the given Evas Object is an Elementary widget.
 265  *
 266  * @param obj the object to query.
 267  * @return @c EINA_TRUE if it is an elementary widget variant,
 268  *         @c EINA_FALSE otherwise
 269  * @ingroup WidgetNavigation
 270  */
 271 EAPI Eina_Bool    elm_object_widget_check(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 272
 273 /**
 274  * Get the first parent of the given object that is an Elementary
 275  * widget.
 276  *
 277  * @param obj the Elementary object to query parent from.
 278  * @return the parent object that is an Elementary widget, or @c
 279  *         NULL, if it was not found.
 280  *
 281  * Use this to query for an object's parent widget.
 282  *
 283  * @note Most of Elementary users wouldn't be mixing non-Elementary
 284  * smart objects in the objects tree of an application, as this is
 285  * an advanced usage of Elementary with Evas. So, except for the
 286  * application's window, which is the root of that tree, all other
 287  * objects would have valid Elementary widget parents.
 288  *
 289  * @ingroup WidgetNavigation
 290  */
 291 EAPI Evas_Object *elm_object_parent_widget_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 292
 293 /**
 294  * Get the top level parent of an Elementary widget.
 295  *
 296  * @param obj The object to query.
 297  * @return The top level Elementary widget, or @c NULL if parent cannot be
 298  * found.
 299  * @ingroup WidgetNavigation
 300  */
 301 EAPI Evas_Object *elm_object_top_widget_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 302
 303 /**
 304  * Get the string that represents this Elementary widget.
 305  *
 306  * @note Elementary is weird and exposes itself as a single
 307  *       Evas_Object_Smart_Class of type "elm_widget", so
 308  *       evas_object_type_get() always return that, making debug and
 309  *       language bindings hard. This function tries to mitigate this
 310  *       problem, but the solution is to change Elementary to use
 311  *       proper inheritance.
 312  *
 313  * @param obj the object to query.
 314  * @return Elementary widget name, or @c NULL if not a valid widget.
 315  * @ingroup WidgetNavigation
 316  */
 317 EAPI const char  *elm_object_widget_type_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 318
 319 /**
 320  * Send a signal to the widget edje object.
 321  *
 322  * This function sends a signal to the edje object of the obj. An
 323  * edje program can respond to a signal by specifying matching
 324  * 'signal' and 'source' fields.
 325  *
 326  * @param obj The object
 327  * @param emission The signal's name.
 328  * @param source The signal's source.
 329  * @ingroup General
 330  */
 331 EAPI void         elm_object_signal_emit(Evas_Object *obj, const char *emission, const char *source) EINA_ARG_NONNULL(1);
 332
 333 /**
 334  * Add a callback for a signal emitted by widget edje object.
 335  *
 336  * This function connects a callback function to a signal emitted by the
 337  * edje object of the obj.
 338  * Globs can occur in either the emission or source name.
 339  *
 340  * @param obj The object
 341  * @param emission The signal's name.
 342  * @param source The signal's source.
 343  * @param func The callback function to be executed when the signal is
 344  * emitted.
 345  * @param data A pointer to data to pass in to the callback function.
 346  * @ingroup General
 347  */
 348 EAPI void         elm_object_signal_callback_add(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func, void *data) EINA_ARG_NONNULL(1, 4);
 349
 350 /**
 351  * Remove a signal-triggered callback from a widget edje object.
 352  *
 353  * This function removes a callback, previoulsy attached to a
 354  * signal emitted by the edje object of the obj.  The parameters
 355  * emission, source and func must match exactly those passed to a
 356  * previous call to elm_object_signal_callback_add(). The data
 357  * pointer that was passed to this call will be returned.
 358  *
 359  * @param obj The object
 360  * @param emission The signal's name.
 361  * @param source The signal's source.
 362  * @param func The callback function to be executed when the signal is
 363  * emitted.
 364  * @return The data pointer
 365  * @ingroup General
 366  */
 367 EAPI void        *elm_object_signal_callback_del(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func) EINA_ARG_NONNULL(1, 4);
 368
 369 /**
 370  * Add a callback for input events (key up, key down, mouse wheel)
 371  * on a given Elementary widget
 372  *
 373  * @param obj The widget to add an event callback on
 374  * @param func The callback function to be executed when the event
 375  * happens
 376  * @param data Data to pass in to @p func
 377  *
 378  * Every widget in an Elementary interface set to receive focus,
 379  * with elm_object_focus_allow_set(), will propagate @b all of its
 380  * key up, key down and mouse wheel input events up to its parent
 381  * object, and so on. All of the focusable ones in this chain which
 382  * had an event callback set, with this call, will be able to treat
 383  * those events. There are two ways of making the propagation of
 384  * these event upwards in the tree of widgets to @b cease:
 385  * - Just return @c EINA_TRUE on @p func. @c EINA_FALSE will mean
 386  *   the event was @b not processed, so the propagation will go on.
 387  * - The @c event_info pointer passed to @p func will contain the
 388  *   event's structure and, if you OR its @c event_flags inner
 389  *   value to @c EVAS_EVENT_FLAG_ON_HOLD, you're telling Elementary
 390  *   one has already handled it, thus killing the event's
 391  *   propagation, too.
 392  *
 393  * @note Your event callback will be issued on those events taking
 394  * place only if no other child widget of @obj has consumed the
 395  * event already.
 396  *
 397  * @note Not to be confused with @c
 398  * evas_object_event_callback_add(), which will add event callbacks
 399  * per type on general Evas objects (no event propagation
 400  * infrastructure taken in account).
 401  *
 402  * @note Not to be confused with @c
 403  * elm_object_signal_callback_add(), which will add callbacks to @b
 404  * signals coming from a widget's theme, not input events.
 405  *
 406  * @note Not to be confused with @c
 407  * edje_object_signal_callback_add(), which does the same as
 408  * elm_object_signal_callback_add(), but directly on an Edje
 409  * object.
 410  *
 411  * @note Not to be confused with @c
 412  * evas_object_smart_callback_add(), which adds callbacks to smart
 413  * objects' <b>smart events</b>, and not input events.
 414  *
 415  * @see elm_object_event_callback_del()
 416  *
 417  * @ingroup General
 418  */
 419 EAPI void         elm_object_event_callback_add(Evas_Object *obj, Elm_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
 420
 421 /**
 422  * Remove an event callback from a widget.
 423  *
 424  * This function removes a callback, previoulsy attached to event emission
 425  * by the @p obj.
 426  * The parameters func and data must match exactly those passed to
 427  * a previous call to elm_object_event_callback_add(). The data pointer that
 428  * was passed to this call will be returned.
 429  *
 430  * @param obj The object
 431  * @param func The callback function to be executed when the event is
 432  * emitted.
 433  * @param data Data to pass in to the callback function.
 434  * @return The data pointer
 435  * @ingroup General
 436  */
 437 EAPI void        *elm_object_event_callback_del(Evas_Object *obj, Elm_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);