interface/wx/access.h

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