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 functioon, 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{Data structures}
  47
  48 Functions return a wxAccStatus error code, which
  49 may be one of the following:
  50
  51 {\small
  52 \begin{verbatim}
  53 typedef 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
  64 Directions of navigation are represented by
  65 the following:
  66
  67 {\small
  68 \begin{verbatim}
  69 typedef 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
  83 The role of a user interface element is represented
  84 by the following type:
  85
  86 {\small
  87 \begin{verbatim}
  88 typedef 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
 155 Objects are represented by the following type:
 156
 157 {\small
 158 \begin{verbatim}
 159 typedef 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
 176 Selection actions are identified by
 177 this type:
 178
 179 {\small
 180 \begin{verbatim}
 181 typedef 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
 193 States 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
 226 Event identifiers that can be sent via \helpref{wxAccessible::NotifyEvent}{wxaccessiblenotifyevent} are
 227 as 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
 282 Constructor, taking an optional window. The object can be associated with
 283 a window later.
 284
 285 \membersection{wxAccessible::\destruct{wxAccessible}}\label{wxaccessibledtor}
 286
 287 \func{}{\destruct{wxAccessible}}{\void}
 288
 289 Destructor.
 290
 291 \membersection{wxAccessible::DoDefaultAction}\label{wxaccessibledodefaultaction}
 292
 293 \func{virtual wxAccStatus}{DoDefaultAction}{\param{int }{childId}}
 294
 295 Performs the default action for the object. {\it childId} is 0 (the action for this object)
 296 or greater than 0 (the action for a child). Return wxACC\_NOT\_SUPPORTED if there
 297 is 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
 303 Gets the specified child (starting from 1). If {\it child} is NULL and the return value is wxACC\_OK,
 304 this 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
 310 Returns 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
 316 Gets the default action for this object (0) or a child (greater than 0).
 317 Return wxACC\_OK even if there is no action. {\it actionName} is the action, or the empty
 318 string if there is no action. The retrieved string describes the action that is performed on an object,
 319 not what the object does as a result. For example, a toolbar button that prints
 320 a 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
 326 Returns 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
 332 Gets the window with the keyboard focus. If childId is 0 and child is NULL, no object in
 333 this 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
 339 Returns 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
 345 Returns the keyboard shortcut for this object or child.
 346 Return e.g. ALT+K.
 347
 348 \membersection{wxAccessible::GetLocation}\label{wxaccessiblegetlocation}
 349
 350 \func{virtual wxAccStatus}{GetLocation}{\param{wxRect\& }{rect}, \param{int }{elementId}}
 351
 352 Returns 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
 359 Gets the name of the specified object.
 360
 361 \membersection{wxAccessible::GetParent}\label{wxaccessiblegetparent}
 362
 363 \func{virtual wxAccStatus}{GetParent}{\param{wxAccessible** }{parent}}
 364
 365 Returns 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
 371 Returns a role constant describing this object. See \helpref{wxAccessible}{wxaccessible} for a list
 372 of these roles.
 373
 374 \membersection{wxAccessible::GetSelections}\label{wxaccessiblegetselections}
 375
 376 \func{virtual wxAccStatus}{GetSelections}{\param{wxVariant* }{selections}}
 377
 378 Gets a variant representing the selected children
 379 of this object.
 380
 381 Acceptable 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,
 387 or 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
 395 Returns a state constant. See \helpref{wxAccessible}{wxaccessible} for a list
 396 of these states.
 397
 398 \membersection{wxAccessible::GetValue}\label{wxaccessiblegetvalue}
 399
 400 \func{virtual wxAccStatus}{GetValue}{\param{int }{childId}, \param{wxString* }{strValue}}
 401
 402 Returns a localized string representing the value for the object
 403 or child.
 404
 405 \membersection{wxAccessible::GetWindow}\label{wxaccessiblegetwindow}
 406
 407 \func{wxWindow*}{GetWindow}{\void}
 408
 409 Returns 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
 415 Returns a status value and object id to indicate whether the given point was on this or
 416 a child object. Can return either a child object, or an integer
 417 representing 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
 425 Navigates 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{wxAccObjectt }{objectType}, \param{int }{objectType}}
 430
 431 Allows 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
 437 Selects the object or child. See \helpref{wxAccessible}{wxaccessible} for a list
 438 of the selection actions.
 439
 440 \membersection{wxAccessible::SetWindow}\label{wxaccessiblesetwindow}
 441
 442 \func{void}{SetWindow}{\param{wxWindow* }{window}}
 443
 444 Sets the window associated with this object.
 445