src/lib/elm_cursor.h

   1 /**
   2  * @defgroup Cursors Cursors
   3  * @ingroup Elementary
   4  *
   5  * The Elementary cursor is an internal smart object used to
   6  * customize the mouse cursor displayed over objects (or
   7  * widgets). In the most common scenario, the cursor decoration
   8  * comes from the graphical @b engine Elementary is running
   9  * on. Those engines may provide different decorations for cursors,
  10  * and Elementary provides functions to choose them (think of X11
  11  * cursors, as an example).
  12  *
  13  * By default, Elementary searches cursors only from engine.
  14  * There's also the possibility of, besides using engine provided
  15  * cursors, also use the ones coming from Edje theme files. Both
  16  * globally and per widget, Elementary makes it possible for one to
  17  * make the cursors lookup to be held on engines only or on
  18  * Elementary's theme file, too. To set cursor's hot spot,
  19  * two data items should be added to cursor's theme: "hot_x" and
  20  * "hot_y", that are the offset from upper-left corner of the cursor
  21  * (coordinates 0,0).
  22  *
  23  * @{
  24  */
  25
  26 /**
  27  * Set the cursor to be shown when mouse is over the object
  28  *
  29  * Set the cursor that will be displayed when mouse is over the
  30  * object. The object can have only one cursor set to it, so if
  31  * this function is called twice for an object, the previous set
  32  * will be unset.
  33  * If using X cursors, a definition of all the valid cursor names
  34  * is listed on Elementary_Cursors.h. If an invalid name is set
  35  * the default cursor will be used.
  36  *
  37  * @param obj the object being set a cursor.
  38  * @param cursor the cursor name to be used.
  39  *
  40  * @ingroup Cursors
  41  */
  42 EAPI void        elm_object_cursor_set(Evas_Object *obj, const char *cursor);
  43
  44 /**
  45  * Get the cursor to be shown when mouse is over the object
  46  *
  47  * @param obj an object with cursor already set.
  48  * @return the cursor name.
  49  *
  50  * @ingroup Cursors
  51  */
  52 EAPI const char *elm_object_cursor_get(const Evas_Object *obj);
  53
  54 /**
  55  * Unset cursor for object
  56  *
  57  * Unset cursor for object, and set the cursor to default if the mouse
  58  * was over this object.
  59  *
  60  * @param obj Target object
  61  * @see elm_object_cursor_set()
  62  *
  63  * @ingroup Cursors
  64  */
  65 EAPI void        elm_object_cursor_unset(Evas_Object *obj);
  66
  67 /**
  68  * Sets a different style for this object cursor.
  69  *
  70  * @note before you set a style you should define a cursor with
  71  *       elm_object_cursor_set()
  72  *
  73  * @param obj an object with cursor already set.
  74  * @param style the theme style to use (default, transparent, ...)
  75  *
  76  * @ingroup Cursors
  77  */
  78 EAPI void        elm_object_cursor_style_set(Evas_Object *obj, const char *style);
  79
  80 /**
  81  * Get the style for this object cursor.
  82  *
  83  * @param obj an object with cursor already set.
  84  * @return style the theme style in use, defaults to "default". If the
  85  *         object does not have a cursor set, then NULL is returned.
  86  *
  87  * @ingroup Cursors
  88  */
  89 EAPI const char *elm_object_cursor_style_get(const Evas_Object *obj);
  90
  91 /**
  92  * Set if the cursor set should be searched on the theme or should use
  93  * the provided by the engine, only.
  94  *
  95  * @note before you set engine_only you should define a cursor with
  96  * elm_object_cursor_set(). By default it will only look for cursors
  97  * provided by the engine.
  98  *
  99  * @param obj an object with cursor already set.
 100  * @param theme_search boolean to define if cursors should be looked only
 101  * between the provided by the engine or searched on widget's theme as well.
 102  *
 103  * @ingroup Cursors
 104  */
 105 EAPI void elm_object_cursor_theme_search_enabled_set(Evas_Object *obj, Eina_Bool theme_search);
 106
 107 /**
 108  * Get the cursor engine only usage for this object cursor.
 109  *
 110  * @param obj an object with cursor already set.
 111  * @return engine_only boolean to define it cursors should be
 112  * looked only between the provided by the engine or searched on
 113  * widget's theme as well. If the object does not have a cursor
 114  * set, then EINA_FALSE is returned.
 115  *
 116  * @ingroup Cursors
 117  */
 118 EAPI Eina_Bool elm_object_cursor_theme_search_enabled_get(const Evas_Object *obj);
 119
 120 /**
 121  * @}
 122  */