src/lib/elm_cursor.h

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