src/lib/elm_access.h

   1 /**
   2  * @defgroup Access Access
   3  * @ingroup Elementary
   4  *
   5  * TODO: description
   6  *
   7  */
   8
   9 enum _Elm_Access_Info_Type
  10 {
  11    ELM_ACCESS_INFO_FIRST = -1,
  12    ELM_ACCESS_INFO,         /* next read is info - this is
  13                              * normally label */
  14    ELM_ACCESS_TYPE,         /* when reading out widget or item
  15                              * this is read first */
  16    ELM_ACCESS_STATE,        /* if there is a state (eg checkbox)
  17                              * then read state out */
  18    ELM_ACCESS_CONTEXT_INFO, /* to give contextual information */
  19    ELM_ACCESS_INFO_LAST
  20 };
  21
  22 /**
  23  * @typedef Elm_Access_Info_Type
  24  */
  25 typedef enum _Elm_Access_Info_Type Elm_Access_Info_Type;
  26
  27 typedef char *(*Elm_Access_Info_Cb)(void *data, Evas_Object *obj);
  28 typedef void (*Elm_Access_Activate_Cb)(void *data, Evas_Object *part_obj, Elm_Object_Item *item);
  29
  30 /**
  31  * @typedef Elm_Access_Action_Cb
  32  * User callback to make access object do specific action
  33  * @param data user data
  34  * @param action_info information to classify the action
  35  * Returns EINA_TRUE on success, EINA FALSE otherwise
  36  *
  37  */
  38 typedef Eina_Bool (*Elm_Access_Action_Cb)(void *data, Evas_Object *obj, void *action_info);
  39
  40 /**
  41  * @enum _Elm_Access_Action_Type
  42  * Enum of supported access action types.
  43  */
  44 enum _Elm_Access_Action_Type
  45 {
  46    ELM_ACCESS_ACTION_FIRST = -1,
  47
  48    ELM_ACCESS_ACTION_HIGHLIGHT, /* highlight an object */
  49    ELM_ACCESS_ACTION_UNHIGHLIGHT, /* unhighlight an object */
  50    ELM_ACCESS_ACTION_HIGHLIGHT_NEXT, /* set highlight to next object */
  51    ELM_ACCESS_ACTION_HIGHLIGHT_PREV, /* set highlight to previous object */
  52    ELM_ACCESS_ACTION_ACTIVATE, /* activate a highlight object */
  53    ELM_ACCESS_ACTION_VALUE_CHANGE, /* change value of highlight object */
  54    ELM_ACCESS_ACTION_SCROLL, /* scroll if one of highlight object parents
  55                               * is scrollable */
  56    ELM_ACCESS_ACTION_BACK, /* go back to a previous view
  57                               ex: pop naviframe item */
  58    ELM_ACCESS_ACTION_READ, /* highlight an object */
  59
  60    ELM_ACCESS_ACTION_LAST
  61 };
  62
  63 /**
  64  * @typedef Elm_Access_Action_Type
  65  */
  66 typedef enum _Elm_Access_Action_Type Elm_Access_Action_Type;
  67
  68 struct _Elm_Access_Action_Info
  69 {
  70    Evas_Coord   x;
  71    Evas_Coord   y;
  72    unsigned int mouse_type; /* 0: mouse down
  73                                1: mouse move
  74                                2: mouse up   */
  75
  76    Elm_Access_Action_Type action_type;
  77    Eina_Bool              highlight_cycle : 1;
  78 };
  79
  80 typedef struct _Elm_Access_Action_Info Elm_Access_Action_Info;
  81
  82 /**
  83  * @brief Register evas object as an accessible object.
  84  * @since 1.8
  85  *
  86  * @param obj The evas object to register as an accessible object.
  87  * @param parent The elementary object which is used for creating
  88  * accessible object.
  89  *
  90  * @ingroup Access
  91  */
  92 EAPI Evas_Object *elm_access_object_register(Evas_Object *obj, Evas_Object *parent);
  93
  94 /**
  95  * @brief Unregister accessible object.
  96  * @since 1.8
  97  *
  98  * @param obj The Evas object to unregister accessible object.
  99  *
 100  * @ingroup Access
 101  */
 102 EAPI void elm_access_object_unregister(Evas_Object *obj);
 103
 104 /**
 105  * @brief Get an accessible object of the evas object.
 106  * @since 1.8
 107  *
 108  * @param obj The evas object.
 109  * @return Accessible object of the evas object or NULL for any error
 110  *
 111  * @ingroup Access
 112  */
 113 EAPI Evas_Object *elm_access_object_get(const Evas_Object *obj);
 114
 115 /**
 116  * @brief Set text to give information for specific type.
 117  * @since 1.8
 118  *
 119  * @param obj Accessible object.
 120  * @param type The type of content that will be read
 121  * @param text The text information that will be read
 122  *
 123  * @see elm_access_info_cb_set
 124  * @ingroup Access
 125  */
 126 EAPI void elm_access_info_set(Evas_Object *obj, int type, const char *text);
 127
 128 /**
 129  * @brief Set text to give information for specific type.
 130  * @since 1.8
 131  *
 132  * @param obj Accessible object.
 133  * @param type The type of content that will be read
 134  *
 135  * @see elm_access_info_cb_set
 136  * @ingroup Access
 137  */
 138 EAPI char *elm_access_info_get(const Evas_Object *obj, int type);
 139
 140 /**
 141  * @brief Set content callback to give information for specific type.
 142  * @since 1.8
 143  *
 144  * @param obj Accessible object.
 145  * @param type The type of content that will be read
 146  * @param func The function to be called when the content is read
 147  * @param data The data pointer to be passed to @p func
 148  *
 149  * The type would be one of ELM_ACCESS_TYPE, ELM_ACCESS_INFO,
 150  * ELM_ACCESS_STATE, ELM_ACCESS_CONTEXT_INFO.
 151  *
 152  * In the case of button widget, the content of ELM_ACCESS_TYPE would be
 153  * "button". The label of button such as "ok", "cancel" is for ELM_ACCESS_INFO.
 154  * If the button is disabled, content of ELM_ACCESS_STATE would be "disabled".
 155  * And if there is contextual information, use ELM_ACCESS_CONTEXT_INFO.
 156  *
 157  * @ingroup Access
 158  */
 159 EAPI void elm_access_info_cb_set(Evas_Object *obj, int type, Elm_Access_Info_Cb func, const void *data);
 160
 161 /**
 162  * @brief Set activate callback to activate highlight object.
 163  * @since 1.8
 164  *
 165  * @param obj Accessible object.
 166  * @param func The function to be called when the activate gesture is detected
 167  * @param data The data pointer to be passed to @p func
 168  *
 169  * @ingroup Access
 170  */
 171 EAPI void elm_access_activate_cb_set(Evas_Object *obj, Elm_Access_Activate_Cb func, void *data);
 172
 173 /**
 174  * @brief Read out text information directly.
 175  * @since 1.8
 176  *
 177  * @param text The text information that will be read
 178  *
 179  * This function will not free the @p text internally.
 180  *
 181  * @ingroup Access
 182  */
 183 EAPI void elm_access_say(const char *text);
 184
 185 /**
 186  * @brief Give the highlight to the object directly.
 187  * @since 1.8
 188  *
 189  * @param obj The object that will have the highlight and its information be read.
 190  *
 191  * The object should be an elementary object or an access object.
 192  *
 193  * @see elm_access_object_get
 194  * @ingroup Access
 195  */
 196 EAPI void elm_access_highlight_set(Evas_Object* obj);
 197
 198 EAPI Eina_Bool elm_access_action(Evas_Object *obj, const Elm_Access_Action_Type type, void *action_info);
 199
 200 EAPI void elm_access_action_cb_set(Evas_Object *obj, const Elm_Access_Action_Type type, const Elm_Access_Action_Cb cb, const void *data);
 201 //TODO: remvoe below - use elm_access_text_set(); or elm_access_cb_set();
 202 EINA_DEPRECATED EAPI void elm_access_external_info_set(Evas_Object *obj, const char *text);
 203 EINA_DEPRECATED EAPI char *elm_access_external_info_get(const Evas_Object *obj);