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