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 class wxAccessible : public wxObject
 259 {
 260 public:
 261     /**
 262         Constructor, taking an optional window. The object can be associated with
 263         a window later.
 264     */
 265     wxAccessible(wxWindow* win = NULL);
 266
 267     /**
 268         Destructor.
 269     */
 270     ~wxAccessible();
 271
 272     /**
 273         Performs the default action for the object.
 274         @a childId is 0 (the action for this object) or greater than 0 (the action
 275         for a child).
 276
 277         @return wxACC_NOT_SUPPORTED if there is no default action for this
 278                 window (e.g. an edit control).
 279     */
 280     virtual wxAccStatus DoDefaultAction(int childId);
 281
 282     /**
 283         Gets the specified child (starting from 1). If @a child is @NULL and the return
 284         value is wxACC_OK, this means that the child is a simple element and not an
 285         accessible object.
 286     */
 287     virtual wxAccStatus GetChild(int childId, wxAccessible** child);
 288
 289     /**
 290         Returns the number of children in @a childCount.
 291     */
 292     virtual wxAccStatus GetChildCount(int* childCount);
 293
 294     /**
 295         Gets the default action for this object (0) or a child (greater than 0).
 296
 297         Return wxACC_OK even if there is no action. @a actionName is the action, or the
 298         empty string if there is no action. The retrieved string describes the action that is
 299         performed on an object, not what the object does as a result. For example, a toolbar
 300         button that prints a document has a default action of "Press" rather than "Prints
 301         the current document."
 302     */
 303     virtual wxAccStatus GetDefaultAction(int childId,
 304                                          wxString* actionName);
 305
 306     /**
 307         Returns the description for this object or a child.
 308     */
 309     virtual wxAccStatus GetDescription(int childId,
 310                                        wxString* description);
 311
 312     /**
 313         Gets the window with the keyboard focus. If childId is 0 and child is @NULL, no
 314         object in this subhierarchy has the focus. If this object has the focus, child
 315         should be 'this'.
 316     */
 317     virtual wxAccStatus GetFocus(int* childId, wxAccessible** child);
 318
 319     /**
 320         Returns help text for this object or a child, similar to tooltip text.
 321     */
 322     virtual wxAccStatus GetHelpText(int childId, wxString* helpText);
 323
 324     /**
 325         Returns the keyboard shortcut for this object or child.
 326         Returns e.g. ALT+K.
 327     */
 328     virtual wxAccStatus GetKeyboardShortcut(int childId,
 329                                             wxString* shortcut);
 330
 331     /**
 332         Returns the rectangle for this object (id is 0) or a child element (id is
 333         greater than 0).
 334         @a rect is in screen coordinates.
 335     */
 336     virtual wxAccStatus GetLocation(wxRect& rect, int elementId);
 337
 338     /**
 339         Gets the name of the specified object.
 340     */
 341     virtual wxAccStatus GetName(int childId, wxString* name);
 342
 343     /**
 344         Returns the parent of this object, or @NULL.
 345     */
 346     virtual wxAccStatus GetParent(wxAccessible** parent);
 347
 348     /**
 349         Returns a role constant describing this object. See wxAccRole for a list
 350         of these roles.
 351     */
 352     virtual wxAccStatus GetRole(int childId, wxAccRole* role);
 353
 354     /**
 355         Gets a variant representing the selected children of this object.
 356
 357         Acceptable values are:
 358         @li a null variant (IsNull() returns @true)
 359         @li a list variant (GetType() == wxT("list"))
 360         @li an integer representing the selected child element,
 361             or 0 if this object is selected (GetType() == wxT("long"))
 362         @li a "void*" pointer to a wxAccessible child object
 363     */
 364     virtual wxAccStatus GetSelections(wxVariant* selections);
 365
 366     /**
 367         Returns a state constant. See wxAccStatus for a list of these states.
 368     */
 369     virtual wxAccStatus GetState(int childId, long* state);
 370
 371     /**
 372         Returns a localized string representing the value for the object
 373         or child.
 374     */
 375     virtual wxAccStatus GetValue(int childId, wxString* strValue);
 376
 377     /**
 378         Returns the window associated with this object.
 379     */
 380     wxWindow* GetWindow();
 381
 382     /**
 383         Returns a status value and object id to indicate whether the given point
 384         was on this or a child object. Can return either a child object, or an
 385         integer representing the child element, starting from 1.
 386
 387         @a pt is in screen coordinates.
 388     */
 389     virtual wxAccStatus HitTest(const wxPoint& pt, int* childId,
 390                                 wxAccessible** childObject);
 391
 392     /**
 393         Navigates from @a fromId to @a toId or to @a toObject.
 394     */
 395     virtual wxAccStatus Navigate(wxNavDir navDir, int fromId,
 396                                  int* toId,
 397                                  wxAccessible** toObject);
 398
 399     /**
 400         Allows the application to send an event when something changes in
 401         an accessible object.
 402     */
 403     virtual static void NotifyEvent(int eventType, wxWindow* window,
 404                                     wxAccObject objectType,
 405                                     int objectType);
 406
 407     /**
 408         Selects the object or child. See wxAccSelectionFlags for a list
 409         of the selection actions.
 410     */
 411     virtual wxAccStatus Select(int childId,
 412                                wxAccSelectionFlags selectFlags);
 413
 414     /**
 415         Sets the window associated with this object.
 416     */
 417     void SetWindow(wxWindow* window);
 418 };
 419