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{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{wxAccObject }{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