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