interface/access.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        access.h
   3 // Purpose:     documentation for wxAccessible class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxAccessible
  11     @wxheader{access.h}
  12
  13     The wxAccessible class allows wxWidgets applications, and
  14     wxWidgets itself, to return extended information about user interface elements
  15     to client applications such as screen readers. This is the
  16     main way in which wxWidgets implements accessibility features.
  17
  18     At present, only Microsoft Active Accessibility is supported
  19     by this class.
  20
  21     To use this class, derive from wxAccessible, implement appropriate
  22     functions, and associate an object of the class with a
  23     window using wxWindow::SetAccessible.
  24
  25     All functions return an indication of success, failure, or not implemented
  26     using values of the wxAccStatus enum type.
  27
  28     If you return wxACC_NOT_IMPLEMENTED from any function, the system will try to
  29     implement the appropriate functionality. However this will not work with
  30     all functions.
  31
  32     Most functions work with an @e object id, which can be zero to refer to
  33     'this' UI element, or greater than zero to refer to the nth child element.
  34     This allows you to specify elements that don't have a corresponding wxWindow or
  35     wxAccessible; for example, the sash of a splitter window.
  36
  37     For details on the semantics of functions and types, please refer to the
  38     Microsoft Active Accessibility 1.2 documentation.
  39
  40     This class is compiled into wxWidgets only if the wxUSE_ACCESSIBILITY setup
  41     symbol is set to 1.
  42
  43     @library{wxcore}
  44     @category{FIXME}
  45 */
  46 class wxAccessible : public wxObject
  47 {
  48 public:
  49     /**
  50         Constructor, taking an optional window. The object can be associated with
  51         a window later.
  52     */
  53     wxAccessible(wxWindow* win = @NULL);
  54
  55     /**
  56         Destructor.
  57     */
  58     ~wxAccessible();
  59
  60     /**
  61         Performs the default action for the object. @e childId is 0 (the action for
  62         this object)
  63         or greater than 0 (the action for a child). Return wxACC_NOT_SUPPORTED if there
  64         is no default action for this window (e.g. an edit control).
  65     */
  66     virtual wxAccStatus DoDefaultAction(int childId);
  67
  68     /**
  69         Gets the specified child (starting from 1). If @e child is @NULL and the return
  70         value is wxACC_OK,
  71         this means that the child is a simple element and not an accessible object.
  72     */
  73     virtual wxAccStatus GetChild(int childId, wxAccessible** child);
  74
  75     /**
  76         Returns the number of children in @e childCount.
  77     */
  78     virtual wxAccStatus GetChildCount(int* childCount);
  79
  80     /**
  81         Gets the default action for this object (0) or a child (greater than 0).
  82         Return wxACC_OK even if there is no action. @e actionName is the action, or the
  83         empty
  84         string if there is no action. The retrieved string describes the action that is
  85         performed on an object,
  86         not what the object does as a result. For example, a toolbar button that prints
  87         a document has a default action of "Press" rather than "Prints the current
  88         document."
  89     */
  90     virtual wxAccStatus GetDefaultAction(int childId,
  91                                          wxString* actionName);
  92
  93     /**
  94         Returns the description for this object or a child.
  95     */
  96     virtual wxAccStatus GetDescription(int childId,
  97                                        wxString* description);
  98
  99     /**
 100         Gets the window with the keyboard focus. If childId is 0 and child is @NULL, no
 101         object in
 102         this subhierarchy has the focus. If this object has the focus, child should be
 103         'this'.
 104     */
 105     virtual wxAccStatus GetFocus(int* childId, wxAccessible** child);
 106
 107     /**
 108         Returns help text for this object or a child, similar to tooltip text.
 109     */
 110     virtual wxAccStatus GetHelpText(int childId, wxString* helpText);
 111
 112     /**
 113         Returns the keyboard shortcut for this object or child.
 114         Return e.g. ALT+K.
 115     */
 116     virtual wxAccStatus GetKeyboardShortcut(int childId,
 117                                             wxString* shortcut);
 118
 119     /**
 120         Returns the rectangle for this object (id is 0) or a child element (id is
 121         greater than 0).
 122         @e rect is in screen coordinates.
 123     */
 124     virtual wxAccStatus GetLocation(wxRect& rect, int elementId);
 125
 126     /**
 127         Gets the name of the specified object.
 128     */
 129     virtual wxAccStatus GetName(int childId, wxString* name);
 130
 131     /**
 132         Returns the parent of this object, or @NULL.
 133     */
 134     virtual wxAccStatus GetParent(wxAccessible** parent);
 135
 136     /**
 137         Returns a role constant describing this object. See wxAccessible for a list
 138         of these roles.
 139     */
 140     virtual wxAccStatus GetRole(int childId, wxAccRole* role);
 141
 142     /**
 143         Gets a variant representing the selected children
 144         of this object.
 145
 146         Acceptable values are:
 147
 148           a null variant (IsNull() returns TRUE)
 149           a list variant (GetType() == wxT("list"))
 150           an integer representing the selected child element,
 151         or 0 if this object is selected (GetType() == wxT("long"))
 152          a "void*" pointer to a wxAccessible child object
 153     */
 154     virtual wxAccStatus GetSelections(wxVariant* selections);
 155
 156     /**
 157         Returns a state constant. See wxAccessible for a list
 158         of these states.
 159     */
 160     virtual wxAccStatus GetState(int childId, long* state);
 161
 162     /**
 163         Returns a localized string representing the value for the object
 164         or child.
 165     */
 166     virtual wxAccStatus GetValue(int childId, wxString* strValue);
 167
 168     /**
 169         Returns the window associated with this object.
 170     */
 171     wxWindow* GetWindow();
 172
 173     /**
 174         Returns a status value and object id to indicate whether the given point was on
 175         this or
 176         a child object. Can return either a child object, or an integer
 177         representing the child element, starting from 1.
 178
 179         @e pt is in screen coordinates.
 180     */
 181     virtual wxAccStatus HitTest(const wxPoint& pt, int* childId,
 182                                 wxAccessible** childObject);
 183
 184     /**
 185         Navigates from @e fromId to @e toId/@e toObject.
 186     */
 187     virtual wxAccStatus Navigate(wxNavDir navDir, int fromId,
 188                                  int* toId,
 189                                  wxAccessible** toObject);
 190
 191     /**
 192         Allows the application to send an event when something changes in an accessible
 193         object.
 194     */
 195     virtual static void NotifyEvent(int eventType, wxWindow* window,
 196                                     wxAccObject objectType,
 197                                     int objectType);
 198
 199     /**
 200         Selects the object or child. See wxAccessible for a list
 201         of the selection actions.
 202     */
 203     virtual wxAccStatus Select(int childId,
 204                                wxAccSelectionFlags selectFlags);
 205
 206     /**
 207         Sets the window associated with this object.
 208     */
 209     void SetWindow(wxWindow* window);
 210 };