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);
229 /* Indicates a window is currently the active window */
231 /* Indicates that the object is armed */
233 /* Indicates the current object is busy */
235 /* Indicates this object is currently checked */
237 /* Indicates this object is collapsed */
239 /* Indicates the user can change the contents of this object */
241 /* Indicates this object allows progressive disclosure of its children */
242 ATK_STATE_EXPANDABLE,
243 /* Indicates this object its expanded */
246 * Indicates this object can accept keyboard focus, which means all
247 * events resulting from typing on the keyboard will normally be passed
248 * to it when it has focus
251 /* Indicates this object currently has the keyboard focus */
253 /* Indicates the orientation of thsi object is horizontal */
254 ATK_STATE_HORIZONTAL,
255 /* Indicates this object is minimized and is represented only by an icon */
258 * Indicates something must be done with this object before the user can
259 * interact with an object in a different window.
262 /* Indicates this (text) object can contain multiple lines of text */
263 ATK_STATE_MULTI_LINE,
265 * Indicates this object allows more than one of its children to be
266 * selected at the same time
268 ATK_STATE_MULTISELECTABLE,
269 /* Indicates this object paints every pixel within its rectangular region. */
271 /* Indicates this object is currently pressed */
273 /* Indicates the size of this object is not fixed */
276 * Indicates this object is the child of an object that allows its
277 * children to be selected and that this child is one of those children
278 * that can be selected.
280 ATK_STATE_SELECTABLE,
282 * Indicates this object is the child of an object that allows its
283 * children to be selected and that this child is one of those children
284 * that has been selected.
287 /* Indicates this object is sensitive */
290 * Indicates this object, the object's parent, the object's parent's
291 * parent, and so on, are all visible
294 /* Indicates this (text) object can contain only a single line of text */
295 ATK_STATE_SINGLE_LINE,
296 /* Indicates this object is transient */
298 /* Indicates the orientation of this object is vertical */
300 /* Indicates this object is visible */
302 ATK_STATE_LAST_DEFINED
305 AtkStateType atk_state_type_register (const gchar *name);
308 #define ATK_TYPE_OBJECT (atk_object_get_type ())
309 #define ATK_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_OBJECT, AtkObject))
310 #define ATK_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), ATK_TYPE_OBJECT, AtkObjectClass))
311 #define ATK_IS_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_OBJECT))
312 #define ATK_IS_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), ATK_TYPE_OBJECT))
313 #define ATK_OBJECT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), ATK_TYPE_OBJECT, AtkObjectClass))
315 #define ATK_TYPE_IMPLEMENTOR (atk_implementor_get_type ())
316 #define ATK_IS_IMPLEMENTOR(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_IMPLEMENTOR)
317 #define ATK_IMPLEMENTOR(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_IMPLEMENTOR, AtkImplementor)
318 #define ATK_IMPLEMENTOR_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), ATK_TYPE_IMPLEMENTOR, AtkImplementorIface))
321 typedef struct _AtkImplementor AtkImplementor; /* dummy typedef */
322 typedef struct _AtkImplementorIface AtkImplementorIface;
325 typedef struct _AtkObject AtkObject;
326 typedef struct _AtkObjectClass AtkObjectClass;
327 typedef struct _AtkRelationSet AtkRelationSet;
329 typedef guint64 AtkStateMask;
330 typedef guint64 AtkState;
332 #define ATK_STATE(state_enum) ((AtkStateMask)(1 << ((guint64)(state_enum)%64)))
334 struct _AtkPropertyValues
336 gchar *property_name;
341 typedef struct _AtkPropertyValues AtkPropertyValues;
344 * For most properties the old_value field of AtkPropertyValues will
345 * not contain a valid value.
347 * Currently, the only property for which old_value is used is
348 * accessible-state; for instance if there is a focus state the
349 * property change handler will be called for the object which lost the focus
350 * with the old_value containing an AtkState value corresponding to focused
351 * and the property change handler will be called for the object which
352 * received the focus with the new_value containing an AtkState value
353 * corresponding to focused.
355 typedef void (*AtkPropertyChangeHandler) (AtkObject*, AtkPropertyValues*);
364 AtkObject *accessible_parent;
366 AtkRelationSet *relation_set;
369 struct _AtkObjectClass
374 * Gets the accessible name of the object
376 G_CONST_RETURN gchar* (* get_name) (AtkObject *accessible);
378 * Gets the accessible description of the object
380 G_CONST_RETURN gchar* (* get_description) (AtkObject *accessible);
382 * Gets the accessible parent of the object
384 AtkObject* (*get_parent) (AtkObject *accessible);
387 * Gets the number of accessible children of the object
389 gint (* get_n_children) (AtkObject *accessible);
391 * Returns a reference to the specified accessible child of the object.
392 * The accessible children are 0-based so the first accessible child is
393 * at index 0, the second at index 1 and so on.
395 AtkObject* (* ref_child) (AtkObject *accessible,
398 * Gets the 0-based index of this object in its parent; returns -1 if the
399 * object does not have an accessible parent.
401 gint (* get_index_in_parent) (AtkObject *accessible);
403 * Gets the RelationSet associated with the object
405 AtkRelationSet* (* ref_relation_set) (AtkObject *accessible);
407 * Gets the role of the object
409 AtkRole (* get_role) (AtkObject *accessible);
411 * Gets the state set of the object
413 AtkState (* get_state) (AtkObject *accessible);
415 * Sets the accessible name of the object
417 void (* set_name) (AtkObject *accessible,
420 * Sets the accessible description of the object
422 void (* set_description) (AtkObject *accessible,
423 const gchar *description);
425 * Sets the accessible parent of the object
427 void (* set_parent) (AtkObject *accessible,
430 * Sets the accessible role of the object
432 void (* set_role) (AtkObject *accessible,
435 * Specifies a function to be called when a property changes value
437 guint (* connect_property_change_handler) (AtkObject
439 AtkPropertyChangeHandler *handler);
441 * Removes a property change handler which was specified using
442 * connect_property_change_handler
444 void (* remove_property_change_handler) (AtkObject
449 * The signal handler which is executed when there is a change in the
450 * children of the object
452 void (* children_changed) (AtkObject *accessible,
453 AtkChildChangeType change_type,
454 AtkObject *changed_child);
456 GType atk_object_get_type (void);
458 struct _AtkImplementorIface
460 GTypeInterface parent;
462 AtkObject* (*ref_accessible) (AtkImplementor *implementor);
464 GType atk_implementor_get_type (void);
467 * This method uses the ref_accessible method in AtkImplementorIface,
468 * if the object's class implements AtkImplementorIface.
469 * Otherwise it returns %NULL.
472 * Note also that because this method may return flyweight objects,
473 * it increments the returned AtkObject's reference count.
474 * Therefore it is the responsibility of the calling
475 * program to unreference the object when no longer needed.
476 * (c.f. gtk_widget_get_accessible() where this is not the case).
478 AtkObject* atk_implementor_ref_accessible (AtkImplementor *implementor);
481 * Properties directly supported by AtkObject
484 G_CONST_RETURN gchar* atk_object_get_name (AtkObject *accessible);
485 G_CONST_RETURN gchar* atk_object_get_description (AtkObject *accessible);
486 AtkObject* atk_object_get_parent (AtkObject *accessible);
487 gint atk_object_get_n_accessible_children (AtkObject *accessible);
488 AtkObject* atk_object_ref_accessible_child (AtkObject *accessible,
490 AtkRelationSet* atk_object_ref_relation_set (AtkObject *accessible);
491 AtkRole atk_object_get_role (AtkObject *accessible);
492 AtkState atk_object_get_state (AtkObject *accessible);
493 gint atk_object_get_index_in_parent (AtkObject *accessible);
494 void atk_object_set_name (AtkObject *accessible,
496 void atk_object_set_description (AtkObject *accessible,
497 const gchar *description);
498 void atk_object_set_parent (AtkObject *accessible,
500 void atk_object_set_role (AtkObject *accessible,
505 * to install property change listener, one must
506 * install signal handler for gobject "properties_changed" signal.
507 * (for single notifications of multiple changes).
508 * We could use the "notify" signal instead.
511 guint atk_object_connect_property_change_handler (AtkObject *accessible,
512 AtkPropertyChangeHandler *handler);
513 void atk_object_remove_property_change_handler (AtkObject *accessible,
517 * Note: the properties which are registered with the GType
518 * property registry, for type ATK_TYPE_OBJECT, are as follows:
521 * "accessible-description"
522 * "accessible-parent"
527 * accessibility property change listeners should use the
528 * normal GObject property interfaces and "properties_changed"
529 * signal handler semantics to interpret the property change
530 * information relayed from AtkObject.
531 * (AtkObject instances will connect to the "properties_changed"
532 * signal in their host objects, and relay the signals when appropriate).
535 /* For other signals, see related interfaces
546 * The usage model for obtaining these interface instances is:
547 * ATK_<interfacename>_GET_IFACE(GObject *accessible),
548 * where accessible, though specified as a GObject, is
549 * the AtkObject instance being queried.
550 * More usually, the interface will be used via a cast to the
551 * interface's corresponding "type":
553 * AtkText textImpl = ATK_TEXT(accessible);
556 * cpos = atk_text_get_caret_position(textImpl);
559 * If it's known in advance that accessible implements AtkTextIface,
560 * this is shortened to:
562 * cpos = atk_text_get_caret_position (ATK_TEXT (accessible));
565 G_CONST_RETURN gchar* atk_state_mask_get_name (AtkStateMask state);
566 AtkStateMask atk_state_mask_for_name (const gchar *name);
570 #endif /* __cplusplus */
573 #endif /* __ATK_OBJECT_H__ */