include/wx/access.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/access.h
   3 // Purpose:     Accessibility classes
   4 // Author:      Julian Smart
   5 // Modified by:
   6 // Created:     2003-02-12
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Julian Smart
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_ACCESSBASE_H_
  13 #define _WX_ACCESSBASE_H_
  14
  15 // ----------------------------------------------------------------------------
  16 // headers we have to include here
  17 // ----------------------------------------------------------------------------
  18
  19 #include "wx/defs.h"
  20
  21 #if wxUSE_ACCESSIBILITY
  22
  23 #include "wx/variant.h"
  24
  25 typedef enum
  26 {
  27     wxACC_FAIL,
  28     wxACC_FALSE,
  29     wxACC_OK,
  30     wxACC_NOT_IMPLEMENTED,
  31     wxACC_NOT_SUPPORTED
  32 } wxAccStatus;
  33
  34 // Child ids are integer identifiers from 1 up.
  35 // So zero represents 'this' object.
  36 #define wxACC_SELF 0
  37
  38 // Navigation constants
  39
  40 typedef enum
  41 {
  42     wxNAVDIR_DOWN,
  43     wxNAVDIR_FIRSTCHILD,
  44     wxNAVDIR_LASTCHILD,
  45     wxNAVDIR_LEFT,
  46     wxNAVDIR_NEXT,
  47     wxNAVDIR_PREVIOUS,
  48     wxNAVDIR_RIGHT,
  49     wxNAVDIR_UP
  50 } wxNavDir;
  51
  52 // Role constants
  53
  54 typedef enum {
  55     wxROLE_NONE,
  56     wxROLE_SYSTEM_ALERT,
  57     wxROLE_SYSTEM_ANIMATION,
  58     wxROLE_SYSTEM_APPLICATION,
  59     wxROLE_SYSTEM_BORDER,
  60     wxROLE_SYSTEM_BUTTONDROPDOWN,
  61     wxROLE_SYSTEM_BUTTONDROPDOWNGRID,
  62     wxROLE_SYSTEM_BUTTONMENU,
  63     wxROLE_SYSTEM_CARET,
  64     wxROLE_SYSTEM_CELL,
  65     wxROLE_SYSTEM_CHARACTER,
  66     wxROLE_SYSTEM_CHART,
  67     wxROLE_SYSTEM_CHECKBUTTON,
  68     wxROLE_SYSTEM_CLIENT,
  69     wxROLE_SYSTEM_CLOCK,
  70     wxROLE_SYSTEM_COLUMN,
  71     wxROLE_SYSTEM_COLUMNHEADER,
  72     wxROLE_SYSTEM_COMBOBOX,
  73     wxROLE_SYSTEM_CURSOR,
  74     wxROLE_SYSTEM_DIAGRAM,
  75     wxROLE_SYSTEM_DIAL,
  76     wxROLE_SYSTEM_DIALOG,
  77     wxROLE_SYSTEM_DOCUMENT,
  78     wxROLE_SYSTEM_DROPLIST,
  79     wxROLE_SYSTEM_EQUATION,
  80     wxROLE_SYSTEM_GRAPHIC,
  81     wxROLE_SYSTEM_GRIP,
  82     wxROLE_SYSTEM_GROUPING,
  83     wxROLE_SYSTEM_HELPBALLOON,
  84     wxROLE_SYSTEM_HOTKEYFIELD,
  85     wxROLE_SYSTEM_INDICATOR,
  86     wxROLE_SYSTEM_LINK,
  87     wxROLE_SYSTEM_LIST,
  88     wxROLE_SYSTEM_LISTITEM,
  89     wxROLE_SYSTEM_MENUBAR,
  90     wxROLE_SYSTEM_MENUITEM,
  91     wxROLE_SYSTEM_MENUPOPUP,
  92     wxROLE_SYSTEM_OUTLINE,
  93     wxROLE_SYSTEM_OUTLINEITEM,
  94     wxROLE_SYSTEM_PAGETAB,
  95     wxROLE_SYSTEM_PAGETABLIST,
  96     wxROLE_SYSTEM_PANE,
  97     wxROLE_SYSTEM_PROGRESSBAR,
  98     wxROLE_SYSTEM_PROPERTYPAGE,
  99     wxROLE_SYSTEM_PUSHBUTTON,
 100     wxROLE_SYSTEM_RADIOBUTTON,
 101     wxROLE_SYSTEM_ROW,
 102     wxROLE_SYSTEM_ROWHEADER,
 103     wxROLE_SYSTEM_SCROLLBAR,
 104     wxROLE_SYSTEM_SEPARATOR,
 105     wxROLE_SYSTEM_SLIDER,
 106     wxROLE_SYSTEM_SOUND,
 107     wxROLE_SYSTEM_SPINBUTTON,
 108     wxROLE_SYSTEM_STATICTEXT,
 109     wxROLE_SYSTEM_STATUSBAR,
 110     wxROLE_SYSTEM_TABLE,
 111     wxROLE_SYSTEM_TEXT,
 112     wxROLE_SYSTEM_TITLEBAR,
 113     wxROLE_SYSTEM_TOOLBAR,
 114     wxROLE_SYSTEM_TOOLTIP,
 115     wxROLE_SYSTEM_WHITESPACE,
 116     wxROLE_SYSTEM_WINDOW
 117 } wxAccRole;
 118
 119 // Object types
 120
 121 typedef enum {
 122     wxOBJID_WINDOW =    0x00000000,
 123     wxOBJID_SYSMENU =   0xFFFFFFFF,
 124     wxOBJID_TITLEBAR =  0xFFFFFFFE,
 125     wxOBJID_MENU =      0xFFFFFFFD,
 126     wxOBJID_CLIENT =    0xFFFFFFFC,
 127     wxOBJID_VSCROLL =   0xFFFFFFFB,
 128     wxOBJID_HSCROLL =   0xFFFFFFFA,
 129     wxOBJID_SIZEGRIP =  0xFFFFFFF9,
 130     wxOBJID_CARET =     0xFFFFFFF8,
 131     wxOBJID_CURSOR =    0xFFFFFFF7,
 132     wxOBJID_ALERT =     0xFFFFFFF6,
 133     wxOBJID_SOUND =     0xFFFFFFF5
 134 } wxAccObject;
 135
 136 // Accessible states
 137
 138 #define wxACC_STATE_SYSTEM_ALERT_HIGH       0x00000001
 139 #define wxACC_STATE_SYSTEM_ALERT_MEDIUM     0x00000002
 140 #define wxACC_STATE_SYSTEM_ALERT_LOW        0x00000004
 141 #define wxACC_STATE_SYSTEM_ANIMATED         0x00000008
 142 #define wxACC_STATE_SYSTEM_BUSY             0x00000010
 143 #define wxACC_STATE_SYSTEM_CHECKED          0x00000020
 144 #define wxACC_STATE_SYSTEM_COLLAPSED        0x00000040
 145 #define wxACC_STATE_SYSTEM_DEFAULT          0x00000080
 146 #define wxACC_STATE_SYSTEM_EXPANDED         0x00000100
 147 #define wxACC_STATE_SYSTEM_EXTSELECTABLE    0x00000200
 148 #define wxACC_STATE_SYSTEM_FLOATING         0x00000400
 149 #define wxACC_STATE_SYSTEM_FOCUSABLE        0x00000800
 150 #define wxACC_STATE_SYSTEM_FOCUSED          0x00001000
 151 #define wxACC_STATE_SYSTEM_HOTTRACKED       0x00002000
 152 #define wxACC_STATE_SYSTEM_INVISIBLE        0x00004000
 153 #define wxACC_STATE_SYSTEM_MARQUEED         0x00008000
 154 #define wxACC_STATE_SYSTEM_MIXED            0x00010000
 155 #define wxACC_STATE_SYSTEM_MULTISELECTABLE  0x00020000
 156 #define wxACC_STATE_SYSTEM_OFFSCREEN        0x00040000
 157 #define wxACC_STATE_SYSTEM_PRESSED          0x00080000
 158 #define wxACC_STATE_SYSTEM_PROTECTED        0x00100000
 159 #define wxACC_STATE_SYSTEM_READONLY         0x00200000
 160 #define wxACC_STATE_SYSTEM_SELECTABLE       0x00400000
 161 #define wxACC_STATE_SYSTEM_SELECTED         0x00800000
 162 #define wxACC_STATE_SYSTEM_SELFVOICING      0x01000000
 163 #define wxACC_STATE_SYSTEM_UNAVAILABLE      0x02000000
 164
 165 // Selection flag
 166
 167 typedef enum
 168 {
 169     wxACC_SEL_NONE            = 0,
 170     wxACC_SEL_TAKEFOCUS       = 1,
 171     wxACC_SEL_TAKESELECTION   = 2,
 172     wxACC_SEL_EXTENDSELECTION = 4,
 173     wxACC_SEL_ADDSELECTION    = 8,
 174     wxACC_SEL_REMOVESELECTION = 16
 175 } wxAccSelectionFlags;
 176
 177 // Accessibility event identifiers
 178
 179 #define wxACC_EVENT_SYSTEM_SOUND              0x0001
 180 #define wxACC_EVENT_SYSTEM_ALERT              0x0002
 181 #define wxACC_EVENT_SYSTEM_FOREGROUND         0x0003
 182 #define wxACC_EVENT_SYSTEM_MENUSTART          0x0004
 183 #define wxACC_EVENT_SYSTEM_MENUEND            0x0005
 184 #define wxACC_EVENT_SYSTEM_MENUPOPUPSTART     0x0006
 185 #define wxACC_EVENT_SYSTEM_MENUPOPUPEND       0x0007
 186 #define wxACC_EVENT_SYSTEM_CAPTURESTART       0x0008
 187 #define wxACC_EVENT_SYSTEM_CAPTUREEND         0x0009
 188 #define wxACC_EVENT_SYSTEM_MOVESIZESTART      0x000A
 189 #define wxACC_EVENT_SYSTEM_MOVESIZEEND        0x000B
 190 #define wxACC_EVENT_SYSTEM_CONTEXTHELPSTART   0x000C
 191 #define wxACC_EVENT_SYSTEM_CONTEXTHELPEND     0x000D
 192 #define wxACC_EVENT_SYSTEM_DRAGDROPSTART      0x000E
 193 #define wxACC_EVENT_SYSTEM_DRAGDROPEND        0x000F
 194 #define wxACC_EVENT_SYSTEM_DIALOGSTART        0x0010
 195 #define wxACC_EVENT_SYSTEM_DIALOGEND          0x0011
 196 #define wxACC_EVENT_SYSTEM_SCROLLINGSTART     0x0012
 197 #define wxACC_EVENT_SYSTEM_SCROLLINGEND       0x0013
 198 #define wxACC_EVENT_SYSTEM_SWITCHSTART        0x0014
 199 #define wxACC_EVENT_SYSTEM_SWITCHEND          0x0015
 200 #define wxACC_EVENT_SYSTEM_MINIMIZESTART      0x0016
 201 #define wxACC_EVENT_SYSTEM_MINIMIZEEND        0x0017
 202 #define wxACC_EVENT_OBJECT_CREATE                 0x8000
 203 #define wxACC_EVENT_OBJECT_DESTROY                0x8001
 204 #define wxACC_EVENT_OBJECT_SHOW                   0x8002
 205 #define wxACC_EVENT_OBJECT_HIDE                   0x8003
 206 #define wxACC_EVENT_OBJECT_REORDER                0x8004
 207 #define wxACC_EVENT_OBJECT_FOCUS                  0x8005
 208 #define wxACC_EVENT_OBJECT_SELECTION              0x8006
 209 #define wxACC_EVENT_OBJECT_SELECTIONADD           0x8007
 210 #define wxACC_EVENT_OBJECT_SELECTIONREMOVE        0x8008
 211 #define wxACC_EVENT_OBJECT_SELECTIONWITHIN        0x8009
 212 #define wxACC_EVENT_OBJECT_STATECHANGE            0x800A
 213 #define wxACC_EVENT_OBJECT_LOCATIONCHANGE         0x800B
 214 #define wxACC_EVENT_OBJECT_NAMECHANGE             0x800C
 215 #define wxACC_EVENT_OBJECT_DESCRIPTIONCHANGE      0x800D
 216 #define wxACC_EVENT_OBJECT_VALUECHANGE            0x800E
 217 #define wxACC_EVENT_OBJECT_PARENTCHANGE           0x800F
 218 #define wxACC_EVENT_OBJECT_HELPCHANGE             0x8010
 219 #define wxACC_EVENT_OBJECT_DEFACTIONCHANGE        0x8011
 220 #define wxACC_EVENT_OBJECT_ACCELERATORCHANGE      0x8012
 221
 222 // ----------------------------------------------------------------------------
 223 // wxAccessible
 224 // All functions return an indication of success, failure, or not implemented.
 225 // ----------------------------------------------------------------------------
 226
 227 class WXDLLIMPEXP_FWD_CORE wxAccessible;
 228 class WXDLLIMPEXP_FWD_CORE wxWindow;
 229 class WXDLLIMPEXP_FWD_CORE wxPoint;
 230 class WXDLLIMPEXP_FWD_CORE wxRect;
 231 class WXDLLIMPEXP_CORE wxAccessibleBase : public wxObject
 232 {
 233     wxDECLARE_NO_COPY_CLASS(wxAccessibleBase);
 234
 235 public:
 236     wxAccessibleBase(wxWindow* win): m_window(win) {}
 237     virtual ~wxAccessibleBase() {}
 238
 239 // Overridables
 240
 241         // Can return either a child object, or an integer
 242         // representing the child element, starting from 1.
 243         // pt is in screen coordinates.
 244     virtual wxAccStatus HitTest(const wxPoint& WXUNUSED(pt), int* WXUNUSED(childId), wxAccessible** WXUNUSED(childObject))
 245          { return wxACC_NOT_IMPLEMENTED; }
 246
 247         // Returns the rectangle for this object (id = 0) or a child element (id > 0).
 248         // rect is in screen coordinates.
 249     virtual wxAccStatus GetLocation(wxRect& WXUNUSED(rect), int WXUNUSED(elementId))
 250          { return wxACC_NOT_IMPLEMENTED; }
 251
 252         // Navigates from fromId to toId/toObject.
 253     virtual wxAccStatus Navigate(wxNavDir WXUNUSED(navDir), int WXUNUSED(fromId),
 254                 int* WXUNUSED(toId), wxAccessible** WXUNUSED(toObject))
 255          { return wxACC_NOT_IMPLEMENTED; }
 256
 257         // Gets the name of the specified object.
 258     virtual wxAccStatus GetName(int WXUNUSED(childId), wxString* WXUNUSED(name))
 259          { return wxACC_NOT_IMPLEMENTED; }
 260
 261         // Gets the number of children.
 262     virtual wxAccStatus GetChildCount(int* WXUNUSED(childCount))
 263          { return wxACC_NOT_IMPLEMENTED; }
 264
 265         // Gets the specified child (starting from 1).
 266         // If *child is NULL and return value is wxACC_OK,
 267         // this means that the child is a simple element and
 268         // not an accessible object.
 269     virtual wxAccStatus GetChild(int WXUNUSED(childId), wxAccessible** WXUNUSED(child))
 270          { return wxACC_NOT_IMPLEMENTED; }
 271
 272         // Gets the parent, or NULL.
 273     virtual wxAccStatus GetParent(wxAccessible** WXUNUSED(parent))
 274          { return wxACC_NOT_IMPLEMENTED; }
 275
 276         // Performs the default action. childId is 0 (the action for this object)
 277         // or > 0 (the action for a child).
 278         // Return wxACC_NOT_SUPPORTED if there is no default action for this
 279         // window (e.g. an edit control).
 280     virtual wxAccStatus DoDefaultAction(int WXUNUSED(childId))
 281          { return wxACC_NOT_IMPLEMENTED; }
 282
 283         // Gets the default action for this object (0) or > 0 (the action for a child).
 284         // Return wxACC_OK even if there is no action. actionName is the action, or the empty
 285         // string if there is no action.
 286         // The retrieved string describes the action that is performed on an object,
 287         // not what the object does as a result. For example, a toolbar button that prints
 288         // a document has a default action of "Press" rather than "Prints the current document."
 289     virtual wxAccStatus GetDefaultAction(int WXUNUSED(childId), wxString* WXUNUSED(actionName))
 290          { return wxACC_NOT_IMPLEMENTED; }
 291
 292         // Returns the description for this object or a child.
 293     virtual wxAccStatus GetDescription(int WXUNUSED(childId), wxString* WXUNUSED(description))
 294          { return wxACC_NOT_IMPLEMENTED; }
 295
 296         // Returns help text for this object or a child, similar to tooltip text.
 297     virtual wxAccStatus GetHelpText(int WXUNUSED(childId), wxString* WXUNUSED(helpText))
 298          { return wxACC_NOT_IMPLEMENTED; }
 299
 300         // Returns the keyboard shortcut for this object or child.
 301         // Return e.g. ALT+K
 302     virtual wxAccStatus GetKeyboardShortcut(int WXUNUSED(childId), wxString* WXUNUSED(shortcut))
 303          { return wxACC_NOT_IMPLEMENTED; }
 304
 305         // Returns a role constant.
 306     virtual wxAccStatus GetRole(int WXUNUSED(childId), wxAccRole* WXUNUSED(role))
 307          { return wxACC_NOT_IMPLEMENTED; }
 308
 309         // Returns a state constant.
 310     virtual wxAccStatus GetState(int WXUNUSED(childId), long* WXUNUSED(state))
 311          { return wxACC_NOT_IMPLEMENTED; }
 312
 313         // Returns a localized string representing the value for the object
 314         // or child.
 315     virtual wxAccStatus GetValue(int WXUNUSED(childId), wxString* WXUNUSED(strValue))
 316          { return wxACC_NOT_IMPLEMENTED; }
 317
 318         // Selects the object or child.
 319     virtual wxAccStatus Select(int WXUNUSED(childId), wxAccSelectionFlags WXUNUSED(selectFlags))
 320          { return wxACC_NOT_IMPLEMENTED; }
 321
 322         // Gets the window with the keyboard focus.
 323         // If childId is 0 and child is NULL, no object in
 324         // this subhierarchy has the focus.
 325         // If this object has the focus, child should be 'this'.
 326     virtual wxAccStatus GetFocus(int* WXUNUSED(childId), wxAccessible** WXUNUSED(child))
 327          { return wxACC_NOT_IMPLEMENTED; }
 328
 329 #if wxUSE_VARIANT
 330         // Gets a variant representing the selected children
 331         // of this object.
 332         // Acceptable values:
 333         // - a null variant (IsNull() returns TRUE)
 334         // - a list variant (GetType() == wxT("list"))
 335         // - an integer representing the selected child element,
 336         //   or 0 if this object is selected (GetType() == wxT("long"))
 337         // - a "void*" pointer to a wxAccessible child object
 338     virtual wxAccStatus GetSelections(wxVariant* WXUNUSED(selections))
 339          { return wxACC_NOT_IMPLEMENTED; }
 340 #endif // wxUSE_VARIANT
 341
 342 // Accessors
 343
 344         // Returns the window associated with this object.
 345
 346     wxWindow* GetWindow() { return m_window; }
 347
 348         // Sets the window associated with this object.
 349
 350     void SetWindow(wxWindow* window) { m_window = window; }
 351
 352 // Operations
 353
 354         // Each platform's implementation must define this
 355     // static void NotifyEvent(int eventType, wxWindow* window, wxAccObject objectType,
 356     //                         int objectId);
 357
 358 private:
 359
 360 // Data members
 361
 362     wxWindow*   m_window;
 363 };
 364
 365
 366 // ----------------------------------------------------------------------------
 367 // now include the declaration of the real class
 368 // ----------------------------------------------------------------------------
 369
 370 #if defined(__WXMSW__)
 371     #include "wx/msw/ole/access.h"
 372 #endif
 373
 374 #endif // wxUSE_ACCESSIBILITY
 375
 376 #endif // _WX_ACCESSBASE_H_
 377