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