src/lib/elm_access.h

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