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