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:
47 /* Object is used to alert the user about something */
49 /* Object that can be drawn into and is sued to trap events */
52 * A choice that can be checked or unchecked and provides a separate
53 * indicator for the current state.
56 /* A specialized dialog that lets the user choose a color. */
57 ATK_ROLE_COLOR_CHOOSER,
58 /* The header for a column of data */
59 ATK_ROLE_COLUMN_HEADER,
60 /* A list of choices the user can select from */
62 /* An inconifed internal frame within a DESKTOP_PANE */
63 ATK_ROLE_DESKTOP_ICON,
65 * A pane that supports internal frames and iconified versions of those
68 ATK_ROLE_DESKTOP_FRAME,
69 /* A top level window with title bar and a border */
72 * A pane that allows the user to navigate through and select the contents
75 ATK_ROLE_DIRECTORY_PANE,
77 * A specialized dialog that displays the files in the directory and lets
78 * the user select a file, browse a different directory, or specify a
81 ATK_ROLE_FILE_CHOOSER,
83 * A object that fills up space in a user interface
86 /* XXX Don't know sure about this. */
87 ATK_ROLE_FOCUS_TRAVERSABLE,
88 /* A top level window with a title bar, border, menubar, etc. */
90 /* A pane that is guaranteed to be painted on top of all panes beneath it */
93 * A document container for HTML, whose children
94 * represent the document content.
96 ATK_ROLE_HTML_CONTAINER,
97 /* A small fixed size picture, typically used to decorate components */
99 /* A frame-like object that is clipped by a desktop pane. */
100 ATK_ROLE_INTERNAL_FRAME,
101 /* An object used to present an icon or short string in an interface */
104 * A specialized pane that allows its children to be drawn in layers,
105 * providing a form of stacking order.
107 ATK_ROLE_LAYERED_PANE,
109 * An object that presents a list of objects to the user and allows the
110 * user to select one or more of them.
113 /* An object that represents an element of a list. */
116 * An object usually found inside a menu bar that contains a list of
117 * actions the user can choose from.
121 * An object usually drawn at the top of the primary dialog box of an
122 * application that contains a list of menus the user can choose from.
126 * An object usually contained in a menu that presents an action the
130 /* A specialized pane whose primary use is inside a DIALOG */
131 ATK_ROLE_OPTION_PANE,
132 /* An object that is a child of a page tab list */
135 * An object that presents a series of panels (or page tabs), one at a time,
136 * through some mechanism provided by the object.
138 ATK_ROLE_PAGE_TAB_LIST,
139 /* A generic container that is often used to group objects. */
142 * A text object uses for passwords, or other places where the text
143 * content is not shown visibly to the user.
145 ATK_ROLE_PASSWORD_TEXT,
147 * A temporary window that is usually used to offer the user a list of
148 * choices, and then hides when the user selects one of those choices.
151 /* An object used to indicate how much of a task has been completed. */
152 ATK_ROLE_PROGRESS_BAR,
154 * An object the user can manipulate to tell the application to do
157 ATK_ROLE_PUSH_BUTTON,
159 * A specialized check box that will cause other radio buttons in the
160 * same group to become uncghecked when this one is checked.
162 ATK_ROLE_RADIO_BUTTON,
164 * A specialized pane that has a glass pane and a layered pane as its
168 /* The header for a row of data */
171 * An object usually used to allow a user to incrementally view a large
176 * An object that allows a user to incrementally view a large amount
179 ATK_ROLE_SCROLL_PANE,
181 * An object usually contained in a menu to provide a visible and
182 * logical separation of the contents in a menu.
185 /* An object that allows the user to select from a bounded range */
187 /* A specialized panel that presents two other panels at the same time. */
189 /* An object used to rpesent information in terms of rows and columns. */
192 ATK_ROLE_TABLE_COLUMN_HEADER,
193 ATK_ROLE_TABLE_ROW_HEADER,
194 /* An object that presents text to the user */
197 * A specialized push button that can be checked or unchecked, but does
198 * not procide a separate indicator for the current state.
200 ATK_ROLE_TOGGLE_BUTTON,
202 * A bar or palette usually composed of push buttons or toggle buttons
206 * An object that provides information about another object
209 /* An object used to repsent hierarchical information to the user. */
212 * The object contains some Accessible information, but its role is
216 /* An object usually used in a scroll pane. */
218 /* A top level window with no title or border */
220 /* not a valid role, used for finding end of enumeration. */
221 ATK_ROLE_LAST_DEFINED
224 AtkRole atk_role_register (const gchar *name);
227 #define ATK_TYPE_OBJECT (atk_object_get_type ())
228 #define ATK_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_OBJECT, AtkObject))
229 #define ATK_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), ATK_TYPE_OBJECT, AtkObjectClass))
230 #define ATK_IS_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_OBJECT))
231 #define ATK_IS_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), ATK_TYPE_OBJECT))
232 #define ATK_OBJECT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), ATK_TYPE_OBJECT, AtkObjectClass))
234 #define ATK_TYPE_IMPLEMENTOR (atk_implementor_get_type ())
235 #define ATK_IS_IMPLEMENTOR(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_IMPLEMENTOR)
236 #define ATK_IMPLEMENTOR(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_IMPLEMENTOR, AtkImplementor)
237 #define ATK_IMPLEMENTOR_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), ATK_TYPE_IMPLEMENTOR, AtkImplementorIface))
240 typedef struct _AtkImplementor AtkImplementor; /* dummy typedef */
241 typedef struct _AtkImplementorIface AtkImplementorIface;
244 typedef struct _AtkObject AtkObject;
245 typedef struct _AtkObjectClass AtkObjectClass;
246 typedef struct _AtkRelationSet AtkRelationSet;
247 typedef struct _AtkStateSet AtkStateSet;
249 struct _AtkPropertyValues
251 gchar *property_name;
256 typedef struct _AtkPropertyValues AtkPropertyValues;
259 * For most properties the old_value field of AtkPropertyValues will
260 * not contain a valid value.
262 * Currently, the only property for which old_value is used is
263 * accessible-state; for instance if there is a focus state the
264 * property change handler will be called for the object which lost the focus
265 * with the old_value containing an AtkState value corresponding to focused
266 * and the property change handler will be called for the object which
267 * received the focus with the new_value containing an AtkState value
268 * corresponding to focused.
270 typedef void (*AtkPropertyChangeHandler) (AtkObject*, AtkPropertyValues*);
279 AtkObject *accessible_parent;
281 AtkRelationSet *relation_set;
284 struct _AtkObjectClass
289 * Gets the accessible name of the object
291 G_CONST_RETURN gchar* (* get_name) (AtkObject *accessible);
293 * Gets the accessible description of the object
295 G_CONST_RETURN gchar* (* get_description) (AtkObject *accessible);
297 * Gets the accessible parent of the object
299 AtkObject* (*get_parent) (AtkObject *accessible);
302 * Gets the number of accessible children of the object
304 gint (* get_n_children) (AtkObject *accessible);
306 * Returns a reference to the specified accessible child of the object.
307 * The accessible children are 0-based so the first accessible child is
308 * at index 0, the second at index 1 and so on.
310 AtkObject* (* ref_child) (AtkObject *accessible,
313 * Gets the 0-based index of this object in its parent; returns -1 if the
314 * object does not have an accessible parent.
316 gint (* get_index_in_parent) (AtkObject *accessible);
318 * Gets the RelationSet associated with the object
320 AtkRelationSet* (* ref_relation_set) (AtkObject *accessible);
322 * Gets the role of the object
324 AtkRole (* get_role) (AtkObject *accessible);
326 * Gets the state set of the object
328 AtkStateSet* (* ref_state_set) (AtkObject *accessible);
330 * Sets the accessible name of the object
332 void (* set_name) (AtkObject *accessible,
335 * Sets the accessible description of the object
337 void (* set_description) (AtkObject *accessible,
338 const gchar *description);
340 * Sets the accessible parent of the object
342 void (* set_parent) (AtkObject *accessible,
345 * Sets the accessible role of the object
347 void (* set_role) (AtkObject *accessible,
350 * Specifies a function to be called when a property changes value
352 guint (* connect_property_change_handler) (AtkObject
354 AtkPropertyChangeHandler *handler);
356 * Removes a property change handler which was specified using
357 * connect_property_change_handler
359 void (* remove_property_change_handler) (AtkObject
364 * The signal handler which is executed when there is a change in the
365 * children of the object
367 void (* children_changed) (AtkObject *accessible,
368 AtkChildChangeType change_type,
369 AtkObject *changed_child);
371 GType atk_object_get_type (void);
373 struct _AtkImplementorIface
375 GTypeInterface parent;
377 AtkObject* (*ref_accessible) (AtkImplementor *implementor);
379 GType atk_implementor_get_type (void);
382 * This method uses the ref_accessible method in AtkImplementorIface,
383 * if the object's class implements AtkImplementorIface.
384 * Otherwise it returns %NULL.
387 * Note also that because this method may return flyweight objects,
388 * it increments the returned AtkObject's reference count.
389 * Therefore it is the responsibility of the calling
390 * program to unreference the object when no longer needed.
391 * (c.f. gtk_widget_get_accessible() where this is not the case).
393 AtkObject* atk_implementor_ref_accessible (AtkImplementor *implementor);
396 * Properties directly supported by AtkObject
399 G_CONST_RETURN gchar* atk_object_get_name (AtkObject *accessible);
400 G_CONST_RETURN gchar* atk_object_get_description (AtkObject *accessible);
401 AtkObject* atk_object_get_parent (AtkObject *accessible);
402 gint atk_object_get_n_accessible_children (AtkObject *accessible);
403 AtkObject* atk_object_ref_accessible_child (AtkObject *accessible,
405 AtkRelationSet* atk_object_ref_relation_set (AtkObject *accessible);
406 AtkRole atk_object_get_role (AtkObject *accessible);
407 AtkStateSet* atk_object_ref_state_set (AtkObject *accessible);
408 gint atk_object_get_index_in_parent (AtkObject *accessible);
409 void atk_object_set_name (AtkObject *accessible,
411 void atk_object_set_description (AtkObject *accessible,
412 const gchar *description);
413 void atk_object_set_parent (AtkObject *accessible,
415 void atk_object_set_role (AtkObject *accessible,
420 * to install property change listener, one must
421 * install signal handler for gobject "properties_changed" signal.
422 * (for single notifications of multiple changes).
423 * We could use the "notify" signal instead.
426 guint atk_object_connect_property_change_handler (AtkObject *accessible,
427 AtkPropertyChangeHandler *handler);
428 void atk_object_remove_property_change_handler (AtkObject *accessible,
432 * Note: the properties which are registered with the GType
433 * property registry, for type ATK_TYPE_OBJECT, are as follows:
436 * "accessible-description"
437 * "accessible-parent"
442 * accessibility property change listeners should use the
443 * normal GObject property interfaces and "properties_changed"
444 * signal handler semantics to interpret the property change
445 * information relayed from AtkObject.
446 * (AtkObject instances will connect to the "properties_changed"
447 * signal in their host objects, and relay the signals when appropriate).
450 /* For other signals, see related interfaces
461 * The usage model for obtaining these interface instances is:
462 * ATK_<interfacename>_GET_IFACE(GObject *accessible),
463 * where accessible, though specified as a GObject, is
464 * the AtkObject instance being queried.
465 * More usually, the interface will be used via a cast to the
466 * interface's corresponding "type":
468 * AtkText textImpl = ATK_TEXT(accessible);
471 * cpos = atk_text_get_caret_position(textImpl);
474 * If it's known in advance that accessible implements AtkTextIface,
475 * this is shortened to:
477 * cpos = atk_text_get_caret_position (ATK_TEXT (accessible));
482 #endif /* __cplusplus */
485 #endif /* __ATK_OBJECT_H__ */