1 /* ATK - Accessibility Toolkit
2 * Copyright 2001 Sun Microsystems Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
20 #ifndef __ATK_OBJECT_H__
21 #define __ATK_OBJECT_H__
25 #endif /* __cplusplus */
27 #include <glib-object.h>
30 * AtkObject represents the minimum information all accessible objects
31 * return. This information includes accessible name, accessible
32 * description, role and state of the object, as well information about
33 * its parent and children. It is also possible to obtain more specific
34 * accessibility information about a component if it supports one or more
35 * of the following interfaces:
41 /* A label which represents an accelerator */
43 /* An object is used to alert the user about something */
45 /* An object which is an animated image */
47 /* An arrow in one of the four cardinal directoions */
49 /* An object that displays a calendar and allows the user to select a date */
51 /* An object that can be drawn into and is used to trap events */
54 * A choice that can be checked or unchecked and provides a separate
55 * indicator for the current state.
58 /* A menu item with a check box */
59 ATK_ROLE_CHECK_MENU_ITEM,
60 /* A specialized dialog that lets the user choose a color. */
61 ATK_ROLE_COLOR_CHOOSER,
62 /* The header for a column of data */
63 ATK_ROLE_COLUMN_HEADER,
64 /* A list of choices the user can select from */
66 /* An object whose purpose is to allow a user to edit a date */
68 /* An inconifed internal frame within a DESKTOP_PANE */
69 ATK_ROLE_DESKTOP_ICON,
71 * A pane that supports internal frames and iconified versions of those
74 ATK_ROLE_DESKTOP_FRAME,
75 /* An object whose purpose is to allow a user to set a value */
77 /* A top level window with title bar and a border */
80 * A pane that allows the user to navigate through and select the contents
83 ATK_ROLE_DIRECTORY_PANE,
85 * A specialized dialog that displays the files in the directory and lets
86 * the user select a file, browse a different directory, or specify a
89 /* An object used for drawing custom user interface elements */
90 ATK_ROLE_DRAWING_AREA,
91 /* A specialized dialog that lets the user choose a file. */
92 ATK_ROLE_FILE_CHOOSER,
93 /* A object that fills up space in a user interface */
95 /* A specialized dialog that lets the user choose a font. */
96 ATK_ROLE_FONT_CHOOSER,
97 /* A top level window with a title bar, border, menubar, etc. */
99 /* A pane that is guaranteed to be painted on top of all panes beneath it */
102 * A document container for HTML, whose children
103 * represent the document content.
105 ATK_ROLE_HTML_CONTAINER,
106 /* A small fixed size picture, typically used to decorate components */
108 /* An object whose primary purpose is to display an image */
110 /* A frame-like object that is clipped by a desktop pane. */
111 ATK_ROLE_INTERNAL_FRAME,
112 /* An object used to present an icon or short string in an interface */
115 * A specialized pane that allows its children to be drawn in layers,
116 * providing a form of stacking order.
118 ATK_ROLE_LAYERED_PANE,
120 * An object that presents a list of objects to the user and allows the
121 * user to select one or more of them.
124 /* An object that represents an element of a list. */
127 * An object usually found inside a menu bar that contains a list of
128 * actions the user can choose from.
132 * An object usually drawn at the top of the primary dialog box of an
133 * application that contains a list of menus the user can choose from.
137 * An object usually contained in a menu that presents an action the
141 /* A specialized pane whose primary use is inside a DIALOG */
142 ATK_ROLE_OPTION_PANE,
143 /* An object that is a child of a page tab list */
146 * An object that presents a series of panels (or page tabs), one at a time,
147 * through some mechanism provided by the object.
149 ATK_ROLE_PAGE_TAB_LIST,
150 /* A generic container that is often used to group objects. */
153 * A text object uses for passwords, or other places where the text
154 * content is not shown visibly to the user.
156 ATK_ROLE_PASSWORD_TEXT,
158 * A temporary window that is usually used to offer the user a list of
159 * choices, and then hides when the user selects one of those choices.
162 /* An object used to indicate how much of a task has been completed. */
163 ATK_ROLE_PROGRESS_BAR,
165 * An object the user can manipulate to tell the application to do
168 ATK_ROLE_PUSH_BUTTON,
170 * A specialized check box that will cause other radio buttons in the
171 * same group to become uncghecked when this one is checked.
173 ATK_ROLE_RADIO_BUTTON,
175 * A check menu item which belongs to a group. At each instant exactly
176 * one of the radio menu items from a group is selected
178 ATK_ROLE_RADIO_MENU_ITEM,
180 * A specialized pane that has a glass pane and a layered pane as its
184 /* The header for a row of data */
187 * An object usually used to allow a user to incrementally view a large
192 * An object that allows a user to incrementally view a large amount
195 ATK_ROLE_SCROLL_PANE,
197 * An object usually contained in a menu to provide a visible and
198 * logical separation of the contents in a menu.
201 /* An object that allows the user to select from a bounded range */
203 /* A specialized panel that presents two other panels at the same time. */
205 /* An object used to get an integer or floating point number from the user */
206 ATK_ROLE_SPIN_BUTTON,
207 /* An object which reports messages of minor importance to the user */
209 /* An object used to rpesent information in terms of rows and columns. */
212 ATK_ROLE_TABLE_COLUMN_HEADER,
213 ATK_ROLE_TABLE_ROW_HEADER,
214 /* A menu item used to tear off and reattach its menu */
215 ATK_ROLE_TEAR_OFF_MENU_ITEM,
216 /* An object that presents text to the user */
219 * A specialized push button that can be checked or unchecked, but does
220 * not procide a separate indicator for the current state.
222 ATK_ROLE_TOGGLE_BUTTON,
224 * A bar or palette usually composed of push buttons or toggle buttons
228 * An object that provides information about another object
231 /* An object used to repsent hierarchical information to the user. */
234 * The object contains some Accessible information, but its role is
238 /* An object usually used in a scroll pane. */
240 /* A top level window with no title or border */
242 /* not a valid role, used for finding end of enumeration. */
243 ATK_ROLE_LAST_DEFINED
246 AtkRole atk_role_register (const gchar *name);
249 #define ATK_TYPE_OBJECT (atk_object_get_type ())
250 #define ATK_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_OBJECT, AtkObject))
251 #define ATK_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), ATK_TYPE_OBJECT, AtkObjectClass))
252 #define ATK_IS_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_OBJECT))
253 #define ATK_IS_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), ATK_TYPE_OBJECT))
254 #define ATK_OBJECT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), ATK_TYPE_OBJECT, AtkObjectClass))
256 #define ATK_TYPE_IMPLEMENTOR (atk_implementor_get_type ())
257 #define ATK_IS_IMPLEMENTOR(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_IMPLEMENTOR)
258 #define ATK_IMPLEMENTOR(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_IMPLEMENTOR, AtkImplementor)
259 #define ATK_IMPLEMENTOR_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), ATK_TYPE_IMPLEMENTOR, AtkImplementorIface))
262 typedef struct _AtkImplementor AtkImplementor; /* dummy typedef */
263 typedef struct _AtkImplementorIface AtkImplementorIface;
266 typedef struct _AtkObject AtkObject;
267 typedef struct _AtkObjectClass AtkObjectClass;
268 typedef struct _AtkRelationSet AtkRelationSet;
269 typedef struct _AtkStateSet AtkStateSet;
271 struct _AtkPropertyValues
273 gchar *property_name;
278 typedef struct _AtkPropertyValues AtkPropertyValues;
281 * For most properties the old_value field of AtkPropertyValues will
282 * not contain a valid value.
284 * Currently, the only property for which old_value is used is
285 * accessible-state; for instance if there is a focus state the
286 * property change handler will be called for the object which lost the focus
287 * with the old_value containing an AtkState value corresponding to focused
288 * and the property change handler will be called for the object which
289 * received the focus with the new_value containing an AtkState value
290 * corresponding to focused.
292 typedef void (*AtkPropertyChangeHandler) (AtkObject*, AtkPropertyValues*);
301 AtkObject *accessible_parent;
303 AtkRelationSet *relation_set;
306 struct _AtkObjectClass
311 * Gets the accessible name of the object
313 G_CONST_RETURN gchar* (* get_name) (AtkObject *accessible);
315 * Gets the accessible description of the object
317 G_CONST_RETURN gchar* (* get_description) (AtkObject *accessible);
319 * Gets the accessible parent of the object
321 AtkObject* (*get_parent) (AtkObject *accessible);
324 * Gets the number of accessible children of the object
326 gint (* get_n_children) (AtkObject *accessible);
328 * Returns a reference to the specified accessible child of the object.
329 * The accessible children are 0-based so the first accessible child is
330 * at index 0, the second at index 1 and so on.
332 AtkObject* (* ref_child) (AtkObject *accessible,
335 * Gets the 0-based index of this object in its parent; returns -1 if the
336 * object does not have an accessible parent.
338 gint (* get_index_in_parent) (AtkObject *accessible);
340 * Gets the RelationSet associated with the object
342 AtkRelationSet* (* ref_relation_set) (AtkObject *accessible);
344 * Gets the role of the object
346 AtkRole (* get_role) (AtkObject *accessible);
348 * Gets the state set of the object
350 AtkStateSet* (* ref_state_set) (AtkObject *accessible);
352 * Sets the accessible name of the object
354 void (* set_name) (AtkObject *accessible,
357 * Sets the accessible description of the object
359 void (* set_description) (AtkObject *accessible,
360 const gchar *description);
362 * Sets the accessible parent of the object
364 void (* set_parent) (AtkObject *accessible,
367 * Sets the accessible role of the object
369 void (* set_role) (AtkObject *accessible,
372 * Specifies a function to be called when a property changes value
374 guint (* connect_property_change_handler) (AtkObject
376 AtkPropertyChangeHandler *handler);
378 * Removes a property change handler which was specified using
379 * connect_property_change_handler
381 void (* remove_property_change_handler) (AtkObject
386 * The signal handler which is executed when there is a change in the
387 * children of the object
389 void (* children_changed) (AtkObject *accessible,
391 AtkObject *changed_child);
393 * The signal handler which is executed when there is a focus event
396 void (*focus_event) (AtkObject *accessible,
400 GType atk_object_get_type (void);
402 struct _AtkImplementorIface
404 GTypeInterface parent;
406 AtkObject* (*ref_accessible) (AtkImplementor *implementor);
408 GType atk_implementor_get_type (void);
411 * This method uses the ref_accessible method in AtkImplementorIface,
412 * if the object's class implements AtkImplementorIface.
413 * Otherwise it returns %NULL.
416 * Note also that because this method may return flyweight objects,
417 * it increments the returned AtkObject's reference count.
418 * Therefore it is the responsibility of the calling
419 * program to unreference the object when no longer needed.
420 * (c.f. gtk_widget_get_accessible() where this is not the case).
422 AtkObject* atk_implementor_ref_accessible (AtkImplementor *implementor);
425 * Properties directly supported by AtkObject
428 G_CONST_RETURN gchar* atk_object_get_name (AtkObject *accessible);
429 G_CONST_RETURN gchar* atk_object_get_description (AtkObject *accessible);
430 AtkObject* atk_object_get_parent (AtkObject *accessible);
431 gint atk_object_get_n_accessible_children (AtkObject *accessible);
432 AtkObject* atk_object_ref_accessible_child (AtkObject *accessible,
434 AtkRelationSet* atk_object_ref_relation_set (AtkObject *accessible);
435 AtkRole atk_object_get_role (AtkObject *accessible);
436 AtkStateSet* atk_object_ref_state_set (AtkObject *accessible);
437 gint atk_object_get_index_in_parent (AtkObject *accessible);
438 void atk_object_set_name (AtkObject *accessible,
440 void atk_object_set_description (AtkObject *accessible,
441 const gchar *description);
442 void atk_object_set_parent (AtkObject *accessible,
444 void atk_object_set_role (AtkObject *accessible,
449 * to install property change listener, one must
450 * install signal handler for gobject "properties_changed" signal.
451 * (for single notifications of multiple changes).
452 * We could use the "notify" signal instead.
455 guint atk_object_connect_property_change_handler (AtkObject *accessible,
456 AtkPropertyChangeHandler *handler);
457 void atk_object_remove_property_change_handler (AtkObject *accessible,
461 * Note: the properties which are registered with the GType
462 * property registry, for type ATK_TYPE_OBJECT, are as follows:
465 * "accessible-description"
466 * "accessible-parent"
471 * accessibility property change listeners should use the
472 * normal GObject property interfaces and "properties_changed"
473 * signal handler semantics to interpret the property change
474 * information relayed from AtkObject.
475 * (AtkObject instances will connect to the "properties_changed"
476 * signal in their host objects, and relay the signals when appropriate).
479 /* For other signals, see related interfaces
490 * The usage model for obtaining these interface instances is:
491 * ATK_<interfacename>_GET_IFACE(GObject *accessible),
492 * where accessible, though specified as a GObject, is
493 * the AtkObject instance being queried.
494 * More usually, the interface will be used via a cast to the
495 * interface's corresponding "type":
497 * AtkText textImpl = ATK_TEXT(accessible);
500 * cpos = atk_text_get_caret_position(textImpl);
503 * If it's known in advance that accessible implements AtkTextIface,
504 * this is shortened to:
506 * cpos = atk_text_get_caret_position (ATK_TEXT (accessible));
511 #endif /* __cplusplus */
514 #endif /* __ATK_OBJECT_H__ */