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