interface/access.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        access.h
   3 // Purpose:     interface of wxAccessible
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     wxAccessible functions return a wxAccStatus error code,
  12     which may be one of this enum's values.
  13 */
  14 typedef enum
  15 {
  16     wxACC_FAIL,            //!< The function failed.
  17     wxACC_FALSE,           //!< The function returned false.
  18     wxACC_OK,              //!< The function completed successfully.
  19     wxACC_NOT_IMPLEMENTED, //!< The function is not implemented.
  20     wxACC_NOT_SUPPORTED    //!< The function is not supported.
  21 } wxAccStatus;
  22
  23
  24 /**
  25     Directions of navigation are represented by this enum.
  26 */
  27 typedef enum
  28 {
  29     wxNAVDIR_DOWN,
  30     wxNAVDIR_FIRSTCHILD,
  31     wxNAVDIR_LASTCHILD,
  32     wxNAVDIR_LEFT,
  33     wxNAVDIR_NEXT,
  34     wxNAVDIR_PREVIOUS,
  35     wxNAVDIR_RIGHT,
  36     wxNAVDIR_UP
  37 } wxNavDir;
  38
  39
  40 /**
  41     The role of a user interface element is represented by the values of this enum.
  42 */
  43 typedef enum {
  44     wxROLE_NONE,
  45     wxROLE_SYSTEM_ALERT,
  46     wxROLE_SYSTEM_ANIMATION,
  47     wxROLE_SYSTEM_APPLICATION,
  48     wxROLE_SYSTEM_BORDER,
  49     wxROLE_SYSTEM_BUTTONDROPDOWN,
  50     wxROLE_SYSTEM_BUTTONDROPDOWNGRID,
  51     wxROLE_SYSTEM_BUTTONMENU,
  52     wxROLE_SYSTEM_CARET,
  53     wxROLE_SYSTEM_CELL,
  54     wxROLE_SYSTEM_CHARACTER,
  55     wxROLE_SYSTEM_CHART,
  56     wxROLE_SYSTEM_CHECKBUTTON,
  57     wxROLE_SYSTEM_CLIENT,
  58     wxROLE_SYSTEM_CLOCK,
  59     wxROLE_SYSTEM_COLUMN,
  60     wxROLE_SYSTEM_COLUMNHEADER,
  61     wxROLE_SYSTEM_COMBOBOX,
  62     wxROLE_SYSTEM_CURSOR,
  63     wxROLE_SYSTEM_DIAGRAM,
  64     wxROLE_SYSTEM_DIAL,
  65     wxROLE_SYSTEM_DIALOG,
  66     wxROLE_SYSTEM_DOCUMENT,
  67     wxROLE_SYSTEM_DROPLIST,
  68     wxROLE_SYSTEM_EQUATION,
  69     wxROLE_SYSTEM_GRAPHIC,
  70     wxROLE_SYSTEM_GRIP,
  71     wxROLE_SYSTEM_GROUPING,
  72     wxROLE_SYSTEM_HELPBALLOON,
  73     wxROLE_SYSTEM_HOTKEYFIELD,
  74     wxROLE_SYSTEM_INDICATOR,
  75     wxROLE_SYSTEM_LINK,
  76     wxROLE_SYSTEM_LIST,
  77     wxROLE_SYSTEM_LISTITEM,
  78     wxROLE_SYSTEM_MENUBAR,
  79     wxROLE_SYSTEM_MENUITEM,
  80     wxROLE_SYSTEM_MENUPOPUP,
  81     wxROLE_SYSTEM_OUTLINE,
  82     wxROLE_SYSTEM_OUTLINEITEM,
  83     wxROLE_SYSTEM_PAGETAB,
  84     wxROLE_SYSTEM_PAGETABLIST,
  85     wxROLE_SYSTEM_PANE,
  86     wxROLE_SYSTEM_PROGRESSBAR,
  87     wxROLE_SYSTEM_PROPERTYPAGE,
  88     wxROLE_SYSTEM_PUSHBUTTON,
  89     wxROLE_SYSTEM_RADIOBUTTON,
  90     wxROLE_SYSTEM_ROW,
  91     wxROLE_SYSTEM_ROWHEADER,
  92     wxROLE_SYSTEM_SCROLLBAR,
  93     wxROLE_SYSTEM_SEPARATOR,
  94     wxROLE_SYSTEM_SLIDER,
  95     wxROLE_SYSTEM_SOUND,
  96     wxROLE_SYSTEM_SPINBUTTON,
  97     wxROLE_SYSTEM_STATICTEXT,
  98     wxROLE_SYSTEM_STATUSBAR,
  99     wxROLE_SYSTEM_TABLE,
 100     wxROLE_SYSTEM_TEXT,
 101     wxROLE_SYSTEM_TITLEBAR,
 102     wxROLE_SYSTEM_TOOLBAR,
 103     wxROLE_SYSTEM_TOOLTIP,
 104     wxROLE_SYSTEM_WHITESPACE,
 105     wxROLE_SYSTEM_WINDOW
 106 } wxAccRole;
 107
 108 /**
 109     Objects are represented by a wxAccObject enum value.
 110 */
 111 typedef enum {
 112     wxOBJID_WINDOW =    0x00000000,
 113     wxOBJID_SYSMENU =   0xFFFFFFFF,
 114     wxOBJID_TITLEBAR =  0xFFFFFFFE,
 115     wxOBJID_MENU =      0xFFFFFFFD,
 116     wxOBJID_CLIENT =    0xFFFFFFFC,
 117     wxOBJID_VSCROLL =   0xFFFFFFFB,
 118     wxOBJID_HSCROLL =   0xFFFFFFFA,
 119     wxOBJID_SIZEGRIP =  0xFFFFFFF9,
 120     wxOBJID_CARET =     0xFFFFFFF8,
 121     wxOBJID_CURSOR =    0xFFFFFFF7,
 122     wxOBJID_ALERT =     0xFFFFFFF6,
 123     wxOBJID_SOUND =     0xFFFFFFF5
 124 } wxAccObject;
 125
 126
 127 /**
 128     Selection actions are identified by the wxAccSelectionFlags values.
 129 */
 130 typedef enum
 131 {
 132     wxACC_SEL_NONE            = 0,
 133     wxACC_SEL_TAKEFOCUS       = 1,
 134     wxACC_SEL_TAKESELECTION   = 2,
 135     wxACC_SEL_EXTENDSELECTION = 4,
 136     wxACC_SEL_ADDSELECTION    = 8,
 137     wxACC_SEL_REMOVESELECTION = 16
 138 } wxAccSelectionFlags;
 139
 140 //@{
 141 /**
 142     Represents a status of the system.
 143 */
 144 #define wxACC_STATE_SYSTEM_ALERT_HIGH       0x00000001
 145 #define wxACC_STATE_SYSTEM_ALERT_MEDIUM     0x00000002
 146 #define wxACC_STATE_SYSTEM_ALERT_LOW        0x00000004
 147 #define wxACC_STATE_SYSTEM_ANIMATED         0x00000008
 148 #define wxACC_STATE_SYSTEM_BUSY             0x00000010
 149 #define wxACC_STATE_SYSTEM_CHECKED          0x00000020
 150 #define wxACC_STATE_SYSTEM_COLLAPSED        0x00000040
 151 #define wxACC_STATE_SYSTEM_DEFAULT          0x00000080
 152 #define wxACC_STATE_SYSTEM_EXPANDED         0x00000100
 153 #define wxACC_STATE_SYSTEM_EXTSELECTABLE    0x00000200
 154 #define wxACC_STATE_SYSTEM_FLOATING         0x00000400
 155 #define wxACC_STATE_SYSTEM_FOCUSABLE        0x00000800
 156 #define wxACC_STATE_SYSTEM_FOCUSED          0x00001000
 157 #define wxACC_STATE_SYSTEM_HOTTRACKED       0x00002000
 158 #define wxACC_STATE_SYSTEM_INVISIBLE        0x00004000
 159 #define wxACC_STATE_SYSTEM_MARQUEED         0x00008000
 160 #define wxACC_STATE_SYSTEM_MIXED            0x00010000
 161 #define wxACC_STATE_SYSTEM_MULTISELECTABLE  0x00020000
 162 #define wxACC_STATE_SYSTEM_OFFSCREEN        0x00040000
 163 #define wxACC_STATE_SYSTEM_PRESSED          0x00080000
 164 #define wxACC_STATE_SYSTEM_PROTECTED        0x00100000
 165 #define wxACC_STATE_SYSTEM_READONLY         0x00200000
 166 #define wxACC_STATE_SYSTEM_SELECTABLE       0x00400000
 167 #define wxACC_STATE_SYSTEM_SELECTED         0x00800000
 168 #define wxACC_STATE_SYSTEM_SELFVOICING      0x01000000
 169 #define wxACC_STATE_SYSTEM_UNAVAILABLE      0x02000000
 170 //@}
 171
 172 //@{
 173 /**
 174     An event identifier that can be sent via wxAccessible::NotifyEvent.
 175 */
 176 #define wxACC_EVENT_SYSTEM_SOUND              0x0001
 177 #define wxACC_EVENT_SYSTEM_ALERT              0x0002
 178 #define wxACC_EVENT_SYSTEM_FOREGROUND         0x0003
 179 #define wxACC_EVENT_SYSTEM_MENUSTART          0x0004
 180 #define wxACC_EVENT_SYSTEM_MENUEND            0x0005
 181 #define wxACC_EVENT_SYSTEM_MENUPOPUPSTART     0x0006
 182 #define wxACC_EVENT_SYSTEM_MENUPOPUPEND       0x0007
 183 #define wxACC_EVENT_SYSTEM_CAPTURESTART       0x0008
 184 #define wxACC_EVENT_SYSTEM_CAPTUREEND         0x0009
 185 #define wxACC_EVENT_SYSTEM_MOVESIZESTART      0x000A
 186 #define wxACC_EVENT_SYSTEM_MOVESIZEEND        0x000B
 187 #define wxACC_EVENT_SYSTEM_CONTEXTHELPSTART   0x000C
 188 #define wxACC_EVENT_SYSTEM_CONTEXTHELPEND     0x000D
 189 #define wxACC_EVENT_SYSTEM_DRAGDROPSTART      0x000E
 190 #define wxACC_EVENT_SYSTEM_DRAGDROPEND        0x000F
 191 #define wxACC_EVENT_SYSTEM_DIALOGSTART        0x0010
 192 #define wxACC_EVENT_SYSTEM_DIALOGEND          0x0011
 193 #define wxACC_EVENT_SYSTEM_SCROLLINGSTART     0x0012
 194 #define wxACC_EVENT_SYSTEM_SCROLLINGEND       0x0013
 195 #define wxACC_EVENT_SYSTEM_SWITCHSTART        0x0014
 196 #define wxACC_EVENT_SYSTEM_SWITCHEND          0x0015
 197 #define wxACC_EVENT_SYSTEM_MINIMIZESTART      0x0016
 198 #define wxACC_EVENT_SYSTEM_MINIMIZEEND        0x0017
 199 #define wxACC_EVENT_OBJECT_CREATE                 0x8000
 200 #define wxACC_EVENT_OBJECT_DESTROY                0x8001
 201 #define wxACC_EVENT_OBJECT_SHOW                   0x8002
 202 #define wxACC_EVENT_OBJECT_HIDE                   0x8003
 203 #define wxACC_EVENT_OBJECT_REORDER                0x8004
 204 #define wxACC_EVENT_OBJECT_FOCUS                  0x8005
 205 #define wxACC_EVENT_OBJECT_SELECTION              0x8006
 206 #define wxACC_EVENT_OBJECT_SELECTIONADD           0x8007
 207 #define wxACC_EVENT_OBJECT_SELECTIONREMOVE        0x8008
 208 #define wxACC_EVENT_OBJECT_SELECTIONWITHIN        0x8009
 209 #define wxACC_EVENT_OBJECT_STATECHANGE            0x800A
 210 #define wxACC_EVENT_OBJECT_LOCATIONCHANGE         0x800B
 211 #define wxACC_EVENT_OBJECT_NAMECHANGE             0x800C
 212 #define wxACC_EVENT_OBJECT_DESCRIPTIONCHANGE      0x800D
 213 #define wxACC_EVENT_OBJECT_VALUECHANGE            0x800E
 214 #define wxACC_EVENT_OBJECT_PARENTCHANGE           0x800F
 215 #define wxACC_EVENT_OBJECT_HELPCHANGE             0x8010
 216 #define wxACC_EVENT_OBJECT_DEFACTIONCHANGE        0x8011
 217 #define wxACC_EVENT_OBJECT_ACCELERATORCHANGE      0x8012
 218 //@}
 219
 220 /**
 221     @class wxAccessible
 222     @wxheader{access.h}
 223
 224     The wxAccessible class allows wxWidgets applications, and wxWidgets itself,
 225     to return extended information about user interface elements to client
 226     applications such as screen readers. This is the main way in which wxWidgets
 227     implements accessibility features.
 228
 229     At present, only Microsoft Active Accessibility is supported by this class.
 230
 231     To use this class, derive from wxAccessible, implement appropriate
 232     functions, and associate an object of the class with a window using
 233     wxWindow::SetAccessible.
 234
 235     All functions return an indication of success, failure, or not implemented
 236     using values of the wxAccStatus enum type.
 237
 238     If you return @c wxACC_NOT_IMPLEMENTED from any function, the system will try
 239     to implement the appropriate functionality. However this will not work with
 240     all functions.
 241
 242     Most functions work with an object @e id, which can be zero to refer to
 243     'this' UI element, or greater than zero to refer to the nth child element.
 244     This allows you to specify elements that don't have a corresponding wxWindow or
 245     wxAccessible; for example, the sash of a splitter window.
 246
 247     For details on the semantics of functions and types, please refer to the
 248     Microsoft Active Accessibility 1.2 documentation.
 249
 250     This class is compiled into wxWidgets only if the wxUSE_ACCESSIBILITY setup
 251     symbol is set to 1.
 252
 253     @onlyfor{wxmsw}
 254
 255     @library{wxcore}
 256     @category{misc}
 257
 258     @see @sample{access}
 259 */
 260 class wxAccessible : public wxObject
 261 {
 262 public:
 263     /**
 264         Constructor, taking an optional window. The object can be associated with
 265         a window later.
 266     */
 267     wxAccessible(wxWindow* win = NULL);
 268
 269     /**
 270         Destructor.
 271     */
 272     ~wxAccessible();
 273
 274     /**
 275         Performs the default action for the object.
 276         @a childId is 0 (the action for this object) or greater than 0 (the action
 277         for a child).
 278
 279         @return wxACC_NOT_SUPPORTED if there is no default action for this
 280                 window (e.g. an edit control).
 281     */
 282     virtual wxAccStatus DoDefaultAction(int childId);
 283
 284     /**
 285         Gets the specified child (starting from 1). If @a child is @NULL and the return
 286         value is wxACC_OK, this means that the child is a simple element and not an
 287         accessible object.
 288     */
 289     virtual wxAccStatus GetChild(int childId, wxAccessible** child);
 290
 291     /**
 292         Returns the number of children in @a childCount.
 293     */
 294     virtual wxAccStatus GetChildCount(int* childCount);
 295
 296     /**
 297         Gets the default action for this object (0) or a child (greater than 0).
 298
 299         Return wxACC_OK even if there is no action. @a actionName is the action, or the
 300         empty string if there is no action. The retrieved string describes the action that is
 301         performed on an object, not what the object does as a result. For example, a toolbar
 302         button that prints a document has a default action of "Press" rather than "Prints
 303         the current document."
 304     */
 305     virtual wxAccStatus GetDefaultAction(int childId,
 306                                          wxString* actionName);
 307
 308     /**
 309         Returns the description for this object or a child.
 310     */
 311     virtual wxAccStatus GetDescription(int childId,
 312                                        wxString* description);
 313
 314     /**
 315         Gets the window with the keyboard focus. If childId is 0 and child is @NULL, no
 316         object in this subhierarchy has the focus. If this object has the focus, child
 317         should be 'this'.
 318     */
 319     virtual wxAccStatus GetFocus(int* childId, wxAccessible** child);
 320
 321     /**
 322         Returns help text for this object or a child, similar to tooltip text.
 323     */
 324     virtual wxAccStatus GetHelpText(int childId, wxString* helpText);
 325
 326     /**
 327         Returns the keyboard shortcut for this object or child.
 328         Returns e.g. ALT+K.
 329     */
 330     virtual wxAccStatus GetKeyboardShortcut(int childId,
 331                                             wxString* shortcut);
 332
 333     /**
 334         Returns the rectangle for this object (id is 0) or a child element (id is
 335         greater than 0).
 336         @a rect is in screen coordinates.
 337     */
 338     virtual wxAccStatus GetLocation(wxRect& rect, int elementId);
 339
 340     /**
 341         Gets the name of the specified object.
 342     */
 343     virtual wxAccStatus GetName(int childId, wxString* name);
 344
 345     /**
 346         Returns the parent of this object, or @NULL.
 347     */
 348     virtual wxAccStatus GetParent(wxAccessible** parent);
 349
 350     /**
 351         Returns a role constant describing this object. See wxAccRole for a list
 352         of these roles.
 353     */
 354     virtual wxAccStatus GetRole(int childId, wxAccRole* role);
 355
 356     /**
 357         Gets a variant representing the selected children of this object.
 358
 359         Acceptable values are:
 360         @li a null variant (IsNull() returns @true)
 361         @li a list variant (GetType() == wxT("list"))
 362         @li an integer representing the selected child element,
 363             or 0 if this object is selected (GetType() == wxT("long"))
 364         @li a "void*" pointer to a wxAccessible child object
 365     */
 366     virtual wxAccStatus GetSelections(wxVariant* selections);
 367
 368     /**
 369         Returns a state constant. See wxAccStatus for a list of these states.
 370     */
 371     virtual wxAccStatus GetState(int childId, long* state);
 372
 373     /**
 374         Returns a localized string representing the value for the object
 375         or child.
 376     */
 377     virtual wxAccStatus GetValue(int childId, wxString* strValue);
 378
 379     /**
 380         Returns the window associated with this object.
 381     */
 382     wxWindow* GetWindow();
 383
 384     /**
 385         Returns a status value and object id to indicate whether the given point
 386         was on this or a child object. Can return either a child object, or an
 387         integer representing the child element, starting from 1.
 388
 389         @a pt is in screen coordinates.
 390     */
 391     virtual wxAccStatus HitTest(const wxPoint& pt, int* childId,
 392                                 wxAccessible** childObject);
 393
 394     /**
 395         Navigates from @a fromId to @a toId or to @a toObject.
 396     */
 397     virtual wxAccStatus Navigate(wxNavDir navDir, int fromId,
 398                                  int* toId,
 399                                  wxAccessible** toObject);
 400
 401     /**
 402         Allows the application to send an event when something changes in
 403         an accessible object.
 404     */
 405     virtual static void NotifyEvent(int eventType, wxWindow* window,
 406                                     wxAccObject objectType,
 407                                     int objectType);
 408
 409     /**
 410         Selects the object or child. See wxAccSelectionFlags for a list
 411         of the selection actions.
 412     */
 413     virtual wxAccStatus Select(int childId,
 414                                wxAccSelectionFlags selectFlags);
 415
 416     /**
 417         Sets the window associated with this object.
 418     */
 419     void SetWindow(wxWindow* window);
 420 };
 421