]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/access.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[wxWidgets.git] / 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