docs/latex/wx/accessible.tex

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