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 may have been removed by the application */
243 /* Indicates this object allows progressive disclosure of its children */
244 ATK_STATE_EXPANDABLE,
245 /* Indicates this object is expandable */
248 * Indicates this object can accept keyboard focus, which means all
249 * events resulting from typing on the keyboard will normally be passed
250 * to it when it has focus
253 /* Indicates this object currently has the keyboard focus */
255 /* Indicates the orientation of thsi object is horizontal */
256 ATK_STATE_HORIZONTAL,
257 /* Indicates this object is minimized and is represented only by an icon */
260 * Indicates something must be done with this object before the user can
261 * interact with an object in a different window.
264 /* Indicates this (text) object can contain multiple lines of text */
265 ATK_STATE_MULTI_LINE,
267 * Indicates this object allows more than one of its children to be
268 * selected at the same time
270 ATK_STATE_MULTISELECTABLE,
271 /* Indicates this object paints every pixel within its rectangular region. */
273 /* Indicates this object is currently pressed */
275 /* Indicates the size of this object is not fixed */
278 * Indicates this object is the child of an object that allows its
279 * children to be selected and that this child is one of those children
280 * that can be selected.
282 ATK_STATE_SELECTABLE,
284 * Indicates this object is the child of an object that allows its
285 * children to be selected and that this child is one of those children
286 * that has been selected.
289 /* Indicates this object is sensitive */
292 * Indicates this object, the object's parent, the object's parent's
293 * parent, and so on, are all visible
296 /* Indicates this (text) object can contain only a single line of text */
297 ATK_STATE_SINGLE_LINE,
298 /* Indicates this object is transient */
300 /* Indicates the orientation of this object is vertical */
302 /* Indicates this object is visible */
304 ATK_STATE_LAST_DEFINED
307 AtkStateType atk_state_type_register (const gchar *name);
310 #define ATK_TYPE_OBJECT (atk_object_get_type ())
311 #define ATK_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_OBJECT, AtkObject))
312 #define ATK_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), ATK_TYPE_OBJECT, AtkObjectClass))
313 #define ATK_IS_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_OBJECT))
314 #define ATK_IS_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), ATK_TYPE_OBJECT))
315 #define ATK_OBJECT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), ATK_TYPE_OBJECT, AtkObjectClass))
317 #define ATK_TYPE_IMPLEMENTOR (atk_implementor_get_type ())
318 #define ATK_IS_IMPLEMENTOR(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_IMPLEMENTOR)
319 #define ATK_IMPLEMENTOR(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_IMPLEMENTOR, AtkImplementor)
320 #define ATK_IMPLEMENTOR_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), ATK_TYPE_IMPLEMENTOR, AtkImplementorIface))
323 typedef struct _AtkImplementor AtkImplementor; /* dummy typedef */
324 typedef struct _AtkImplementorIface AtkImplementorIface;
327 typedef struct _AtkObject AtkObject;
328 typedef struct _AtkObjectClass AtkObjectClass;
329 typedef struct _AtkRelationSet AtkRelationSet;
330 typedef struct _AtkStateSet AtkStateSet;
332 typedef guint64 AtkState;
333 typedef guint64 AtkStateMask;
336 struct _AtkPropertyValues
338 gchar *property_name;
343 typedef struct _AtkPropertyValues AtkPropertyValues;
346 * For most properties the old_value field of AtkPropertyValues will
347 * not contain a valid value.
349 * Currently, the only property for which old_value is used is
350 * accessible-state; for instance if there is a focus state the
351 * property change handler will be called for the object which lost the focus
352 * with the old_value containing an AtkState value corresponding to focused
353 * and the property change handler will be called for the object which
354 * received the focus with the new_value containing an AtkState value
355 * corresponding to focused.
357 typedef void (*AtkPropertyChangeHandler) (AtkObject*, AtkPropertyValues*);
366 AtkObject *accessible_parent;
368 AtkRelationSet *relation_set;
371 struct _AtkObjectClass
376 * Gets the accessible name of the object
378 G_CONST_RETURN gchar* (* get_name) (AtkObject *accessible);
380 * Gets the accessible description of the object
382 G_CONST_RETURN gchar* (* get_description) (AtkObject *accessible);
384 * Gets the accessible parent of the object
386 AtkObject* (*get_parent) (AtkObject *accessible);
389 * Gets the number of accessible children of the object
391 gint (* get_n_children) (AtkObject *accessible);
393 * Returns a reference to the specified accessible child of the object.
394 * The accessible children are 0-based so the first accessible child is
395 * at index 0, the second at index 1 and so on.
397 AtkObject* (* ref_child) (AtkObject *accessible,
400 * Gets the 0-based index of this object in its parent; returns -1 if the
401 * object does not have an accessible parent.
403 gint (* get_index_in_parent) (AtkObject *accessible);
405 * Gets the RelationSet associated with the object
407 AtkRelationSet* (* ref_relation_set) (AtkObject *accessible);
409 * Gets the role of the object
411 AtkRole (* get_role) (AtkObject *accessible);
413 * Gets the state set of the object
415 AtkStateSet* (* ref_state_set) (AtkObject *accessible);
417 * Sets the accessible name of the object
419 void (* set_name) (AtkObject *accessible,
422 * Sets the accessible description of the object
424 void (* set_description) (AtkObject *accessible,
425 const gchar *description);
427 * Sets the accessible parent of the object
429 void (* set_parent) (AtkObject *accessible,
432 * Sets the accessible role of the object
434 void (* set_role) (AtkObject *accessible,
437 * Specifies a function to be called when a property changes value
439 guint (* connect_property_change_handler) (AtkObject
441 AtkPropertyChangeHandler *handler);
443 * Removes a property change handler which was specified using
444 * connect_property_change_handler
446 void (* remove_property_change_handler) (AtkObject
451 * The signal handler which is executed when there is a change in the
452 * children of the object
454 void (* children_changed) (AtkObject *accessible,
455 AtkChildChangeType change_type,
456 AtkObject *changed_child);
458 GType atk_object_get_type (void);
460 struct _AtkImplementorIface
462 GTypeInterface parent;
464 AtkObject* (*ref_accessible) (AtkImplementor *implementor);
466 GType atk_implementor_get_type (void);
469 * This method uses the ref_accessible method in AtkImplementorIface,
470 * if the object's class implements AtkImplementorIface.
471 * Otherwise it returns %NULL.
474 * Note also that because this method may return flyweight objects,
475 * it increments the returned AtkObject's reference count.
476 * Therefore it is the responsibility of the calling
477 * program to unreference the object when no longer needed.
478 * (c.f. gtk_widget_get_accessible() where this is not the case).
480 AtkObject* atk_implementor_ref_accessible (AtkImplementor *implementor);
483 * Properties directly supported by AtkObject
486 G_CONST_RETURN gchar* atk_object_get_name (AtkObject *accessible);
487 G_CONST_RETURN gchar* atk_object_get_description (AtkObject *accessible);
488 AtkObject* atk_object_get_parent (AtkObject *accessible);
489 gint atk_object_get_n_accessible_children (AtkObject *accessible);
490 AtkObject* atk_object_ref_accessible_child (AtkObject *accessible,
492 AtkRelationSet* atk_object_ref_relation_set (AtkObject *accessible);
493 AtkRole atk_object_get_role (AtkObject *accessible);
494 AtkStateSet* atk_object_ref_state_set (AtkObject *accessible);
495 gint atk_object_get_index_in_parent (AtkObject *accessible);
496 void atk_object_set_name (AtkObject *accessible,
498 void atk_object_set_description (AtkObject *accessible,
499 const gchar *description);
500 void atk_object_set_parent (AtkObject *accessible,
502 void atk_object_set_role (AtkObject *accessible,
507 * to install property change listener, one must
508 * install signal handler for gobject "properties_changed" signal.
509 * (for single notifications of multiple changes).
510 * We could use the "notify" signal instead.
513 guint atk_object_connect_property_change_handler (AtkObject *accessible,
514 AtkPropertyChangeHandler *handler);
515 void atk_object_remove_property_change_handler (AtkObject *accessible,
519 * Note: the properties which are registered with the GType
520 * property registry, for type ATK_TYPE_OBJECT, are as follows:
523 * "accessible-description"
524 * "accessible-parent"
529 * accessibility property change listeners should use the
530 * normal GObject property interfaces and "properties_changed"
531 * signal handler semantics to interpret the property change
532 * information relayed from AtkObject.
533 * (AtkObject instances will connect to the "properties_changed"
534 * signal in their host objects, and relay the signals when appropriate).
537 /* For other signals, see related interfaces
548 * The usage model for obtaining these interface instances is:
549 * ATK_<interfacename>_GET_IFACE(GObject *accessible),
550 * where accessible, though specified as a GObject, is
551 * the AtkObject instance being queried.
552 * More usually, the interface will be used via a cast to the
553 * interface's corresponding "type":
555 * AtkText textImpl = ATK_TEXT(accessible);
558 * cpos = atk_text_get_caret_position(textImpl);
561 * If it's known in advance that accessible implements AtkTextIface,
562 * this is shortened to:
564 * cpos = atk_text_get_caret_position (ATK_TEXT (accessible));
567 G_CONST_RETURN gchar* atk_state_mask_get_name (AtkStateMask state);
568 AtkStateMask atk_state_mask_for_name (const gchar *name);
572 #endif /* __cplusplus */
575 #endif /* __ATK_OBJECT_H__ */