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 wxWindows applications, and
   9 wxWindows 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 wxWindows 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 wxWindows 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 Directions of navigation are represented by
  64 the following:
  65
  66 {\small%
  67 \begin{verbatim}
  68 typedef enum
  69 {
  70     wxNAVDIR\_DOWN,
  71     wxNAVDIR\_FIRSTCHILD,
  72     wxNAVDIR\_LASTCHILD,
  73     wxNAVDIR\_LEFT,
  74     wxNAVDIR\_NEXT,
  75     wxNAVDIR\_PREVIOUS,
  76     wxNAVDIR\_RIGHT,
  77     wxNAVDIR\_UP
  78 } wxNavDir
  79 \end{verbatim}}
  80
  81 The role of a user interface element is represented
  82 by the following type:
  83
  84 {\small%
  85 \begin{verbatim}
  86 typedef enum {
  87     wxROLE\_NONE,
  88     wxROLE\_SYSTEM\_ALERT,
  89     wxROLE\_SYSTEM\_ANIMATION,
  90     wxROLE\_SYSTEM\_APPLICATION,
  91     wxROLE\_SYSTEM\_BORDER,
  92     wxROLE\_SYSTEM\_BUTTONDROPDOWN,
  93     wxROLE\_SYSTEM\_BUTTONDROPDOWNGRID,
  94     wxROLE\_SYSTEM\_BUTTONMENU,
  95     wxROLE\_SYSTEM\_CARET,
  96     wxROLE\_SYSTEM\_CELL,
  97     wxROLE\_SYSTEM\_CHARACTER,
  98     wxROLE\_SYSTEM\_CHART,
  99     wxROLE\_SYSTEM\_CHECKBUTTON,
 100     wxROLE\_SYSTEM\_CLIENT,
 101     wxROLE\_SYSTEM\_CLOCK,
 102     wxROLE\_SYSTEM\_COLUMN,
 103     wxROLE\_SYSTEM\_COLUMNHEADER,
 104     wxROLE\_SYSTEM\_COMBOBOX,
 105     wxROLE\_SYSTEM\_CURSOR,
 106     wxROLE\_SYSTEM\_DIAGRAM,
 107     wxROLE\_SYSTEM\_DIAL,
 108     wxROLE\_SYSTEM\_DIALOG,
 109     wxROLE\_SYSTEM\_DOCUMENT,
 110     wxROLE\_SYSTEM\_DROPLIST,
 111     wxROLE\_SYSTEM\_EQUATION,
 112     wxROLE\_SYSTEM\_GRAPHIC,
 113     wxROLE\_SYSTEM\_GRIP,
 114     wxROLE\_SYSTEM\_GROUPING,
 115     wxROLE\_SYSTEM\_HELPBALLOON,
 116     wxROLE\_SYSTEM\_HOTKEYFIELD,
 117     wxROLE\_SYSTEM\_INDICATOR,
 118     wxROLE\_SYSTEM\_LINK,
 119     wxROLE\_SYSTEM\_LIST,
 120     wxROLE\_SYSTEM\_LISTITEM,
 121     wxROLE\_SYSTEM\_MENUBAR,
 122     wxROLE\_SYSTEM\_MENUITEM,
 123     wxROLE\_SYSTEM\_MENUPOPUP,
 124     wxROLE\_SYSTEM\_OUTLINE,
 125     wxROLE\_SYSTEM\_OUTLINEITEM,
 126     wxROLE\_SYSTEM\_PAGETAB,
 127     wxROLE\_SYSTEM\_PAGETABLIST,
 128     wxROLE\_SYSTEM\_PANE,
 129     wxROLE\_SYSTEM\_PROGRESSBAR,
 130     wxROLE\_SYSTEM\_PROPERTYPAGE,
 131     wxROLE\_SYSTEM\_PUSHBUTTON,
 132     wxROLE\_SYSTEM\_RADIOBUTTON,
 133     wxROLE\_SYSTEM\_ROW,
 134     wxROLE\_SYSTEM\_ROWHEADER,
 135     wxROLE\_SYSTEM\_SCROLLBAR,
 136     wxROLE\_SYSTEM\_SEPARATOR,
 137     wxROLE\_SYSTEM\_SLIDER,
 138     wxROLE\_SYSTEM\_SOUND,
 139     wxROLE\_SYSTEM\_SPINBUTTON,
 140     wxROLE\_SYSTEM\_STATICTEXT,
 141     wxROLE\_SYSTEM\_STATUSBAR,
 142     wxROLE\_SYSTEM\_TABLE,
 143     wxROLE\_SYSTEM\_TEXT,
 144     wxROLE\_SYSTEM\_TITLEBAR,
 145     wxROLE\_SYSTEM\_TOOLBAR,
 146     wxROLE\_SYSTEM\_TOOLTIP,
 147     wxROLE\_SYSTEM\_WHITESPACE,
 148     wxROLE\_SYSTEM\_WINDOW
 149 } wxAccRole
 150 \end{verbatim}}
 151
 152 Objects are represented by the following type:
 153
 154 {\small%
 155 \begin{verbatim}
 156 typedef enum {
 157     wxOBJID\_WINDOW =    0x00000000,
 158     wxOBJID\_SYSMENU =   0xFFFFFFFF,
 159     wxOBJID\_TITLEBAR =  0xFFFFFFFE,
 160     wxOBJID\_MENU =      0xFFFFFFFD,
 161     wxOBJID\_CLIENT =    0xFFFFFFFC,
 162     wxOBJID\_VSCROLL =   0xFFFFFFFB,
 163     wxOBJID\_HSCROLL =   0xFFFFFFFA,
 164     wxOBJID\_SIZEGRIP =  0xFFFFFFF9,
 165     wxOBJID\_CARET =     0xFFFFFFF8,
 166     wxOBJID\_CURSOR =    0xFFFFFFF7,
 167     wxOBJID\_ALERT =     0xFFFFFFF6,
 168     wxOBJID\_SOUND =     0xFFFFFFF5
 169 } wxAccObject
 170 \end{verbatim}}
 171
 172 Selection actions are identified by
 173 this type:
 174
 175 {\small%
 176 \begin{verbatim}
 177 typedef enum
 178 {
 179     wxACC\_SEL\_NONE            = 0,
 180     wxACC\_SEL\_TAKEFOCUS       = 1,
 181     wxACC\_SEL\_TAKESELECTION   = 2,
 182     wxACC\_SEL\_EXTENDSELECTION = 4,
 183     wxACC\_SEL\_ADDSELECTION    = 8,
 184     wxACC\_SEL\_REMOVESELECTION = 16
 185 } wxAccSelectionFlags
 186 \end{verbatim}}
 187
 188 States are represented by the following:
 189
 190 {\small%
 191 \begin{verbatim}
 192 #define wxACC\_STATE\_SYSTEM\_ALERT\_HIGH       0x00000001
 193 #define wxACC\_STATE\_SYSTEM\_ALERT\_MEDIUM     0x00000002
 194 #define wxACC\_STATE\_SYSTEM\_ALERT\_LOW        0x00000004
 195 #define wxACC\_STATE\_SYSTEM\_ANIMATED         0x00000008
 196 #define wxACC\_STATE\_SYSTEM\_BUSY             0x00000010
 197 #define wxACC\_STATE\_SYSTEM\_CHECKED          0x00000020
 198 #define wxACC\_STATE\_SYSTEM\_COLLAPSED        0x00000040
 199 #define wxACC\_STATE\_SYSTEM\_DEFAULT          0x00000080
 200 #define wxACC\_STATE\_SYSTEM\_EXPANDED         0x00000100
 201 #define wxACC\_STATE\_SYSTEM\_EXTSELECTABLE    0x00000200
 202 #define wxACC\_STATE\_SYSTEM\_FLOATING         0x00000400
 203 #define wxACC\_STATE\_SYSTEM\_FOCUSABLE        0x00000800
 204 #define wxACC\_STATE\_SYSTEM\_FOCUSED          0x00001000
 205 #define wxACC\_STATE\_SYSTEM\_HOTTRACKED       0x00002000
 206 #define wxACC\_STATE\_SYSTEM\_INVISIBLE        0x00004000
 207 #define wxACC\_STATE\_SYSTEM\_MARQUEED         0x00008000
 208 #define wxACC\_STATE\_SYSTEM\_MIXED            0x00010000
 209 #define wxACC\_STATE\_SYSTEM\_MULTISELECTABLE  0x00020000
 210 #define wxACC\_STATE\_SYSTEM\_OFFSCREEN        0x00040000
 211 #define wxACC\_STATE\_SYSTEM\_PRESSED          0x00080000
 212 #define wxACC\_STATE\_SYSTEM\_PROTECTED        0x00100000
 213 #define wxACC\_STATE\_SYSTEM\_READONLY         0x00200000
 214 #define wxACC\_STATE\_SYSTEM\_SELECTABLE       0x00400000
 215 #define wxACC\_STATE\_SYSTEM\_SELECTED         0x00800000
 216 #define wxACC\_STATE\_SYSTEM\_SELFVOICING      0x01000000
 217 #define wxACC\_STATE\_SYSTEM\_UNAVAILABLE      0x02000000
 218 \end{verbatim}}
 219
 220 Event identifiers that can be sent via \helpref{wxAccessible::NotifyEvent}{wxaccessiblenotifyevent} are
 221 as follows:
 222
 223 {\small%
 224 \begin{verbatim}
 225 #define wxACC\_EVENT\_SYSTEM\_SOUND              0x0001
 226 #define wxACC\_EVENT\_SYSTEM\_ALERT              0x0002
 227 #define wxACC\_EVENT\_SYSTEM\_FOREGROUND         0x0003
 228 #define wxACC\_EVENT\_SYSTEM\_MENUSTART          0x0004
 229 #define wxACC\_EVENT\_SYSTEM\_MENUEND            0x0005
 230 #define wxACC\_EVENT\_SYSTEM\_MENUPOPUPSTART     0x0006
 231 #define wxACC\_EVENT\_SYSTEM\_MENUPOPUPEND       0x0007
 232 #define wxACC\_EVENT\_SYSTEM\_CAPTURESTART       0x0008
 233 #define wxACC\_EVENT\_SYSTEM\_CAPTUREEND         0x0009
 234 #define wxACC\_EVENT\_SYSTEM\_MOVESIZESTART      0x000A
 235 #define wxACC\_EVENT\_SYSTEM\_MOVESIZEEND        0x000B
 236 #define wxACC\_EVENT\_SYSTEM\_CONTEXTHELPSTART   0x000C
 237 #define wxACC\_EVENT\_SYSTEM\_CONTEXTHELPEND     0x000D
 238 #define wxACC\_EVENT\_SYSTEM\_DRAGDROPSTART      0x000E
 239 #define wxACC\_EVENT\_SYSTEM\_DRAGDROPEND        0x000F
 240 #define wxACC\_EVENT\_SYSTEM\_DIALOGSTART        0x0010
 241 #define wxACC\_EVENT\_SYSTEM\_DIALOGEND          0x0011
 242 #define wxACC\_EVENT\_SYSTEM\_SCROLLINGSTART     0x0012
 243 #define wxACC\_EVENT\_SYSTEM\_SCROLLINGEND       0x0013
 244 #define wxACC\_EVENT\_SYSTEM\_SWITCHSTART        0x0014
 245 #define wxACC\_EVENT\_SYSTEM\_SWITCHEND          0x0015
 246 #define wxACC\_EVENT\_SYSTEM\_MINIMIZESTART      0x0016
 247 #define wxACC\_EVENT\_SYSTEM\_MINIMIZEEND        0x0017
 248 #define wxACC\_EVENT\_OBJECT\_CREATE                 0x8000
 249 #define wxACC\_EVENT\_OBJECT\_DESTROY                0x8001
 250 #define wxACC\_EVENT\_OBJECT\_SHOW                   0x8002
 251 #define wxACC\_EVENT\_OBJECT\_HIDE                   0x8003
 252 #define wxACC\_EVENT\_OBJECT\_REORDER                0x8004
 253 #define wxACC\_EVENT\_OBJECT\_FOCUS                  0x8005
 254 #define wxACC\_EVENT\_OBJECT\_SELECTION              0x8006
 255 #define wxACC\_EVENT\_OBJECT\_SELECTIONADD           0x8007
 256 #define wxACC\_EVENT\_OBJECT\_SELECTIONREMOVE        0x8008
 257 #define wxACC\_EVENT\_OBJECT\_SELECTIONWITHIN        0x8009
 258 #define wxACC\_EVENT\_OBJECT\_STATECHANGE            0x800A
 259 #define wxACC\_EVENT\_OBJECT\_LOCATIONCHANGE         0x800B
 260 #define wxACC\_EVENT\_OBJECT\_NAMECHANGE             0x800C
 261 #define wxACC\_EVENT\_OBJECT\_DESCRIPTIONCHANGE      0x800D
 262 #define wxACC\_EVENT\_OBJECT\_VALUECHANGE            0x800E
 263 #define wxACC\_EVENT\_OBJECT\_PARENTCHANGE           0x800F
 264 #define wxACC\_EVENT\_OBJECT\_HELPCHANGE             0x8010
 265 #define wxACC\_EVENT\_OBJECT\_DEFACTIONCHANGE        0x8011
 266 #define wxACC\_EVENT\_OBJECT\_ACCELERATORCHANGE      0x8012
 267 \end{verbatim}}
 268
 269 \latexignore{\rtfignore{\wxheading{Members}}}
 270
 271 \membersection{wxAccessible::wxAccessible}\label{wxaccessiblewxaccessible}
 272
 273 \func{}{wxAccessible}{\param{wxWindow* }{win = NULL}}
 274
 275 Constructor, taking an optional window. The object can be associated with
 276 a window later.
 277
 278 \membersection{wxAccessible::\destruct{wxAccessible}}\label{wxaccessibledtor}
 279
 280 \func{}{\destruct{wxAccessible}}{\void}
 281
 282 Destructor.
 283
 284 \membersection{wxAccessible::DoDefaultAction}\label{wxaccessibledodefaultaction}
 285
 286 \func{virtual wxAccStatus}{DoDefaultAction}{\param{int }{childId}}
 287
 288 Performs the default action for the object. {\it childId} is 0 (the action for this object)
 289 or greater than 0 (the action for a child). Return wxACC\_NOT\_SUPPORTED if there
 290 is no default action for this window (e.g. an edit control).
 291
 292 \membersection{wxAccessible::GetChild}\label{wxaccessiblegetchild}
 293
 294 \func{virtual wxAccStatus}{GetChild}{\param{int }{childId}, \param{wxAccessible** }{child}}
 295
 296 Gets the specified child (starting from 1). If {\it child} is NULL and the return value is wxACC\_OK,
 297 this means that the child is a simple element and not an accessible object.
 298
 299 \membersection{wxAccessible::GetChildCount}\label{wxaccessiblegetchildcount}
 300
 301 \func{virtual wxAccStatus}{GetChildCount}{\param{int* }{childCount}}
 302
 303 Returns the number of children in {\it childCount}.
 304
 305 \membersection{wxAccessible::GetDefaultAction}\label{wxaccessiblegetdefaultaction}
 306
 307 \func{virtual wxAccStatus}{GetDefaultAction}{\param{int }{childId}, \param{wxString* }{actionName}}
 308
 309 Gets the default action for this object (0) or a child (greater than 0).
 310 Return wxACC\_OK even if there is no action. {\it actionName} is the action, or the empty
 311 string if there is no action. The retrieved string describes the action that is performed on an object,
 312 not what the object does as a result. For example, a toolbar button that prints
 313 a document has a default action of "Press" rather than "Prints the current document."
 314
 315 \membersection{wxAccessible::GetDescription}\label{wxaccessiblegetdescription}
 316
 317 \func{virtual wxAccStatus}{GetDescription}{\param{int }{childId}, \param{wxString* }{description}}
 318
 319 Returns the description for this object or a child.
 320
 321 \membersection{wxAccessible::GetFocus}\label{wxaccessiblegetfocus}
 322
 323 \func{virtual wxAccStatus}{GetFocus}{\param{int* }{childId}, \param{wxAccessible** }{child}}
 324
 325 Gets the window with the keyboard focus. If childId is 0 and child is NULL, no object in
 326 this subhierarchy has the focus. If this object has the focus, child should be 'this'.
 327
 328 \membersection{wxAccessible::GetHelpText}\label{wxaccessiblegethelptext}
 329
 330 \func{virtual wxAccStatus}{GetHelpText}{\param{int }{childId}, \param{wxString* }{helpText}}
 331
 332 Returns help text for this object or a child, similar to tooltip text.
 333
 334 \membersection{wxAccessible::GetKeyboardShortcut}\label{wxaccessiblegetkeyboardshortcut}
 335
 336 \func{virtual wxAccStatus}{GetKeyboardShortcut}{\param{int }{childId}, \param{wxString* }{shortcut}}
 337
 338 Returns the keyboard shortcut for this object or child.
 339 Return e.g. ALT+K.
 340
 341 \membersection{wxAccessible::GetLocation}\label{wxaccessiblegetlocation}
 342
 343 \func{virtual wxAccStatus}{GetLocation}{\param{wxRect\& }{rect}, \param{int }{elementId}}
 344
 345 Returns the rectangle for this object (id is 0) or a child element (id is greater than 0).
 346 {\it rect} is in screen coordinates.
 347
 348 \membersection{wxAccessible::GetName}\label{wxaccessiblegetname}
 349
 350 \func{virtual wxAccStatus}{GetName}{\param{int }{childId}, \param{wxString* }{name}}
 351
 352 Gets the name of the specified object.
 353
 354 \membersection{wxAccessible::GetParent}\label{wxaccessiblegetparent}
 355
 356 \func{virtual wxAccStatus}{GetParent}{\param{wxAccessible** }{parent}}
 357
 358 Returns the parent of this object, or NULL.
 359
 360 \membersection{wxAccessible::GetRole}\label{wxaccessiblegetrole}
 361
 362 \func{virtual wxAccStatus}{GetRole}{\param{int }{childId}, \param{wxAccRole* }{role}}
 363
 364 Returns a role constant describing this object. See \helpref{wxAccessible}{wxaccessible} for a list
 365 of these roles.
 366
 367 \membersection{wxAccessible::GetSelections}\label{wxaccessiblegetselections}
 368
 369 \func{virtual wxAccStatus}{GetSelections}{\param{wxVariant* }{selections}}
 370
 371 Gets a variant representing the selected children
 372 of this object.
 373
 374 Acceptable values are:
 375
 376 \begin{itemize}
 377 \item  a null variant (IsNull() returns TRUE)
 378 \item  a list variant (GetType() == wxT("list"))
 379 \item  an integer representing the selected child element,
 380 or 0 if this object is selected (GetType() == wxT("long"))
 381 \item a "void*" pointer to a wxAccessible child object
 382 \end{itemize}
 383
 384 \membersection{wxAccessible::GetState}\label{wxaccessiblegetstate}
 385
 386 \func{virtual wxAccStatus}{GetState}{\param{int }{childId}, \param{long* }{state}}
 387
 388 Returns a state constant. See \helpref{wxAccessible}{wxaccessible} for a list
 389 of these states.
 390
 391 \membersection{wxAccessible::GetValue}\label{wxaccessiblegetvalue}
 392
 393 \func{virtual wxAccStatus}{GetValue}{\param{int }{childId}, \param{wxString* }{strValue}}
 394
 395 Returns a localized string representing the value for the object
 396 or child.
 397
 398 \membersection{wxAccessible::GetWindow}\label{wxaccessiblegetwindow}
 399
 400 \func{wxWindow*}{GetWindow}{\void}
 401
 402 Returns the window associated with this object.
 403
 404 \membersection{wxAccessible::HitTest}\label{wxaccessiblehittest}
 405
 406 \func{virtual wxAccStatus}{HitTest}{\param{const wxPoint\& }{pt}, \param{int* }{childId}, \param{wxAccessible** }{childObject}}
 407
 408 Returns a status value and object id to indicate whether the given point was on this or
 409 a child object. Can return either a child object, or an integer
 410 representing the child element, starting from 1.
 411
 412 {\it pt} is in screen coordinates.
 413
 414 \membersection{wxAccessible::Navigate}\label{wxaccessiblenavigate}
 415
 416 \func{virtual wxAccStatus}{Navigate}{\param{wxNavDir }{navDir}, \param{int }{fromId}, \param{int* }{toId}, \param{wxAccessible** }{toObject}}
 417
 418 Navigates from {\it fromId} to {\it toId}/{\it toObject}.
 419
 420 \membersection{wxAccessible::NotifyEvent}\label{wxaccessiblenotifyevent}
 421
 422 \func{virtual static void}{NotifyEvent}{\param{int}{ eventType}, \param{wxWindow* }{window}, \param{wxAccObjectt }{objectType}, \param{int }{objectType}}
 423
 424 Allows the application to send an event when something changes in an accessible object.
 425
 426 \membersection{wxAccessible::Select}\label{wxaccessibleselect}
 427
 428 \func{virtual wxAccStatus}{Select}{\param{int }{childId}, \param{wxAccSelectionFlags }{selectFlags}}
 429
 430 Selects the object or child. See \helpref{wxAccessible}{wxaccessible} for a list
 431 of the selection actions.
 432
 433 \membersection{wxAccessible::SetWindow}\label{wxaccessiblesetwindow}
 434
 435 \func{void}{SetWindow}{\param{wxWindow* }{window}}
 436
 437 Sets the window associated with this object.
 438