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  * There's also the possibility of, besides using engine provided
  13  * cursors, also use ones coming from Edje theming files. Both
  14  * globally and per widget, Elementary makes it possible for one to
  15  * make the cursors lookup to be held on engines only or on
  16  * Elementary's theme file, too. To set cursor's hot spot,
  17  * two data items should be added to cursor's theme: "hot_x" and
  18  * "hot_y", that are the offset from upper-left corner of the cursor
  19  * (coordinates 0,0).
  20  *
  21  * @{
  22  */
  23
  24 /**
  25  * Set the cursor to be shown when mouse is over the object
  26  *
  27  * Set the cursor that will be displayed when mouse is over the
  28  * object. The object can have only one cursor set to it, so if
  29  * this function is called twice for an object, the previous set
  30  * will be unset.
  31  * If using X cursors, a definition of all the valid cursor names
  32  * is listed on Elementary_Cursors.h. If an invalid name is set
  33  * the default cursor will be used.
  34  *
  35  * @param obj the object being set a cursor.
  36  * @param cursor the cursor name to be used.
  37  *
  38  * @ingroup Cursors
  39  */
  40 EAPI void
  41                  elm_object_cursor_set(Evas_Object *obj, const char *cursor)
  42 EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
  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 if should look on theme you should define a cursor
  96  * with 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 engine_only boolean to define it 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_engine_only_set(Evas_Object *obj, Eina_Bool engine_only) EINA_ARG_NONNULL(1);
 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_engine_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 119
 120 /**
 121  * Get the configured cursor engine only usage
 122  *
 123  * This gets the globally configured exclusive usage of engine cursors.
 124  *
 125  * @return 1 if only engine cursors should be used
 126  * @ingroup Cursors
 127  */
 128 EAPI int         elm_cursor_engine_only_get(void);
 129
 130 /**
 131  * Set the configured cursor engine only usage
 132  *
 133  * This sets the globally configured exclusive usage of engine cursors.
 134  * It won't affect cursors set before changing this value.
 135  *
 136  * @param engine_only If 1 only engine cursors will be enabled, if 0 will
 137  * look for them on theme before.
 138  * @return EINA_TRUE if value is valid and setted (0 or 1)
 139  * @ingroup Cursors
 140  */
 141 EAPI Eina_Bool   elm_cursor_engine_only_set(int engine_only);
 142
 143 /**
 144  * @}
 145  */