interface/wx/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
 223     The wxAccessible class allows wxWidgets applications, and wxWidgets itself,
 224     to return extended information about user interface elements to client
 225     applications such as screen readers. This is the main way in which wxWidgets
 226     implements accessibility features.
 227
 228     At present, only Microsoft Active Accessibility is supported by this class.
 229
 230     To use this class, derive from wxAccessible, implement appropriate
 231     functions, and associate an object of the class with a window using
 232     wxWindow::SetAccessible.
 233
 234     All functions return an indication of success, failure, or not implemented
 235     using values of the wxAccStatus enum type.
 236
 237     If you return @c wxACC_NOT_IMPLEMENTED from any function, the system will try
 238     to implement the appropriate functionality. However this will not work with
 239     all functions.
 240
 241     Most functions work with an object @e id, which can be zero to refer to
 242     'this' UI element, or greater than zero to refer to the nth child element.
 243     This allows you to specify elements that don't have a corresponding wxWindow or
 244     wxAccessible; for example, the sash of a splitter window.
 245
 246     For details on the semantics of functions and types, please refer to the
 247     Microsoft Active Accessibility 1.2 documentation.
 248
 249     This class is compiled into wxWidgets only if the wxUSE_ACCESSIBILITY setup
 250     symbol is set to 1.
 251
 252     @onlyfor{wxmsw}
 253
 254     @library{wxcore}
 255     @category{misc}
 256
 257     @see @sample{access}
 258 */
 259 class wxAccessible : public wxObject
 260 {
 261 public:
 262     /**
 263         Constructor, taking an optional window. The object can be associated with
 264         a window later.
 265     */
 266     wxAccessible(wxWindow* win = NULL);
 267
 268     /**
 269         Destructor.
 270     */
 271     ~wxAccessible();
 272
 273     /**
 274         Performs the default action for the object.
 275         @a childId is 0 (the action for this object) or greater than 0 (the action
 276         for a child).
 277
 278         @return wxACC_NOT_SUPPORTED if there is no default action for this
 279                 window (e.g. an edit control).
 280     */
 281     virtual wxAccStatus DoDefaultAction(int childId);
 282
 283     /**
 284         Gets the specified child (starting from 1). If @a child is @NULL and the return
 285         value is wxACC_OK, this means that the child is a simple element and not an
 286         accessible object.
 287     */
 288     virtual wxAccStatus GetChild(int childId, wxAccessible** child);
 289
 290     /**
 291         Returns the number of children in @a childCount.
 292     */
 293     virtual wxAccStatus GetChildCount(int* childCount);
 294
 295     /**
 296         Gets the default action for this object (0) or a child (greater than 0).
 297
 298         Return wxACC_OK even if there is no action. @a actionName is the action, or the
 299         empty string if there is no action. The retrieved string describes the action that is
 300         performed on an object, not what the object does as a result. For example, a toolbar
 301         button that prints a document has a default action of "Press" rather than "Prints
 302         the current document."
 303     */
 304     virtual wxAccStatus GetDefaultAction(int childId,
 305                                          wxString* actionName);
 306
 307     /**
 308         Returns the description for this object or a child.
 309     */
 310     virtual wxAccStatus GetDescription(int childId,
 311                                        wxString* description);
 312
 313     /**
 314         Gets the window with the keyboard focus. If childId is 0 and child is @NULL, no
 315         object in this subhierarchy has the focus. If this object has the focus, child
 316         should be 'this'.
 317     */
 318     virtual wxAccStatus GetFocus(int* childId, wxAccessible** child);
 319
 320     /**
 321         Returns help text for this object or a child, similar to tooltip text.
 322     */
 323     virtual wxAccStatus GetHelpText(int childId, wxString* helpText);
 324
 325     /**
 326         Returns the keyboard shortcut for this object or child.
 327         Returns e.g. ALT+K.
 328     */
 329     virtual wxAccStatus GetKeyboardShortcut(int childId,
 330                                             wxString* shortcut);
 331
 332     /**
 333         Returns the rectangle for this object (id is 0) or a child element (id is
 334         greater than 0).
 335         @a rect is in screen coordinates.
 336     */
 337     virtual wxAccStatus GetLocation(wxRect& rect, int elementId);
 338
 339     /**
 340         Gets the name of the specified object.
 341     */
 342     virtual wxAccStatus GetName(int childId, wxString* name);
 343
 344     /**
 345         Returns the parent of this object, or @NULL.
 346     */
 347     virtual wxAccStatus GetParent(wxAccessible** parent);
 348
 349     /**
 350         Returns a role constant describing this object. See wxAccRole for a list
 351         of these roles.
 352     */
 353     virtual wxAccStatus GetRole(int childId, wxAccRole* role);
 354
 355     /**
 356         Gets a variant representing the selected children of this object.
 357
 358         Acceptable values are:
 359         @li a null variant (IsNull() returns @true)
 360         @li a list variant (GetType() == wxT("list"))
 361         @li an integer representing the selected child element,
 362             or 0 if this object is selected (GetType() == wxT("long"))
 363         @li a "void*" pointer to a wxAccessible child object
 364     */
 365     virtual wxAccStatus GetSelections(wxVariant* selections);
 366
 367     /**
 368         Returns a state constant. See wxAccStatus for a list of these states.
 369     */
 370     virtual wxAccStatus GetState(int childId, long* state);
 371
 372     /**
 373         Returns a localized string representing the value for the object
 374         or child.
 375     */
 376     virtual wxAccStatus GetValue(int childId, wxString* strValue);
 377
 378     /**
 379         Returns the window associated with this object.
 380     */
 381     wxWindow* GetWindow();
 382
 383     /**
 384         Returns a status value and object id to indicate whether the given point
 385         was on this or a child object. Can return either a child object, or an
 386         integer representing the child element, starting from 1.
 387
 388         @a pt is in screen coordinates.
 389     */
 390     virtual wxAccStatus HitTest(const wxPoint& pt, int* childId,
 391                                 wxAccessible** childObject);
 392
 393     /**
 394         Navigates from @a fromId to @a toId or to @a toObject.
 395     */
 396     virtual wxAccStatus Navigate(wxNavDir navDir, int fromId,
 397                                  int* toId,
 398                                  wxAccessible** toObject);
 399
 400     /**
 401         Allows the application to send an event when something changes in
 402         an accessible object.
 403     */
 404     static void NotifyEvent(int eventType, wxWindow* window,
 405                             wxAccObject objectType,
 406                             int objectType);
 407
 408     /**
 409         Selects the object or child. See wxAccSelectionFlags for a list
 410         of the selection actions.
 411     */
 412     virtual wxAccStatus Select(int childId,
 413                                wxAccSelectionFlags selectFlags);
 414
 415     /**
 416         Sets the window associated with this object.
 417     */
 418     void SetWindow(wxWindow* window);
 419 };
 420