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