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