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 (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 (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_OBJECT_IFACE (atk_object_iface_get_type ())
316 #define ATK_OBJECT_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), ATK_TYPE_OBJECT_IFACE, AtkObjectIface))
319 /* Forward declarations of interface structures */
321 typedef struct _AtkIfaceImplementor AtkIfaceImplementor;
323 typedef struct _AtkObjectIface AtkObjectIface;
325 typedef struct _AtkActionIface AtkActionIface;
326 typedef struct _AtkComponentIface AtkComponentIface;
327 typedef struct _AtkEditableTextIface AtkEditableTextIface;
328 typedef struct _AtkHypertextIface AtkHypertextIface;
329 typedef struct _AtkImageIface AtkImageIface;
330 typedef struct _AtkSelectionIface AtkSelectionIface;
331 typedef struct _AtkTableIface AtkTableIface;
332 typedef struct _AtkTextIface AtkTextIface;
333 typedef struct _AtkValueIface AtkValueIface;
336 typedef struct _AtkObject AtkObject;
337 typedef struct _AtkObjectClass AtkObjectClass;
338 typedef struct _AtkRelation AtkRelation;
339 typedef struct _AtkRelationSet AtkRelationSet;
341 typedef guint64 AtkStateMask;
342 typedef guint64 AtkState;
344 #define ATK_STATE(state_enum) ((AtkStateMask)(1 << ((guint64)(state_enum)%64)))
346 struct _AtkPropertyValues
348 gchar *property_name;
353 typedef struct _AtkPropertyValues AtkPropertyValues;
356 * For most properties the old_value field of AtkPropertyValues will
357 * not contain a valid value.
359 * Currently, the only property for which old_value is used is
360 * accessible-state; for instance if there is a focus state the
361 * property change handler will be called for the object which lost the focus
362 * with the old_value containing an AtkState value corresponding to focused
363 * and the property change handler will be called for the object which
364 * received the focus with the new_value containing an AtkState value
365 * corresponding to focused.
367 typedef void (*AtkPropertyChangeHandler) (AtkObject*, AtkPropertyValues*);
376 AtkObject *accessible_parent;
378 AtkRelationSet *relation_set;
381 struct _AtkObjectClass
386 * Gets the accessible name of the object
388 G_CONST_RETURN gchar* (* get_name) (AtkObject *accessible);
390 * Gets the accessible description of the object
392 G_CONST_RETURN gchar* (* get_description) (AtkObject *accessible);
394 * Gets the accessible parent of the object
396 AtkObject* (*get_parent) (AtkObject *accessible);
399 * Gets the number of accessible children of the object
401 gint (* get_n_children) (AtkObject *accessible);
403 * Returns a reference to the specified accessible child of the object.
404 * The accessible children are 0-based so the first accessible child is
405 * at index 0, the second at index 1 and so on.
407 AtkObject* (* ref_child) (AtkObject *accessible,
410 * Gets the 0-based index of this object in its parent; returns -1 if the
411 * object does not have an accessible parent.
413 gint (* get_index_in_parent) (AtkObject *accessible);
415 * Gets the RelationSet associated with the object
417 AtkRelationSet* (* get_relation_set) (AtkObject *accessible);
419 * Gets the role of the object
421 AtkRole (* get_role) (AtkObject *accessible);
423 * Gets the state set of the object
425 AtkState (* get_state) (AtkObject *accessible);
427 * Sets the accessible name of the object
429 void (* set_name) (AtkObject *accessible,
432 * Sets the accessible description of the object
434 void (* set_description) (AtkObject *accessible,
435 const gchar *description);
437 * Sets the accessible parent of the object
439 void (* set_parent) (AtkObject *accessible,
442 * Sets the accessible role of the object
444 void (* set_role) (AtkObject *accessible,
447 * Specifies a function to be called when a property changes value
449 guint (* connect_property_change_handler) (AtkObject
451 AtkPropertyChangeHandler *handler);
453 * Removes a property change handler which was specified using
454 * connect_property_change_handler
456 void (* remove_property_change_handler) (AtkObject
461 * The signal handler which is executed when there is a change in the
462 * children of the object
464 void (* children_changed) (AtkObject *accessible,
465 AtkChildChangeType change_type,
466 AtkObject *changed_child);
468 GType atk_object_get_type (void);
470 struct _AtkObjectIface
472 GTypeInterface parent;
474 AtkObject* (*ref_accessible) (AtkIfaceImplementor *accessible);
476 GType atk_object_iface_get_type (void);
479 * This method uses the ref_accessible method in AtkObjectIface,
480 * if the object's class implements AtkObjectIface.
481 * Otherwise it returns %NULL.
484 * Note also that because this method may return flyweight objects,
485 * it increments the returned AtkObject's reference count.
486 * Therefore it is the responsibility of the calling
487 * program to unreference the object when no longer needed.
488 * (c.f. gtk_widget_get_accessible() where this is not the case).
490 AtkObject* atk_object_ref_accessible (AtkIfaceImplementor *accessible);
493 * Properties directly supported by AtkObject
496 G_CONST_RETURN gchar* atk_object_get_name (AtkObject *accessible);
497 G_CONST_RETURN gchar* atk_object_get_description (AtkObject *accessible);
498 AtkObject* atk_object_get_parent (AtkObject *accessible);
499 gint atk_object_get_n_accessible_children (AtkObject *accessible);
500 AtkObject* atk_object_ref_accessible_child (AtkObject *accessible,
502 AtkRelationSet* atk_object_get_relation_set (AtkObject *accessible);
503 AtkRole atk_object_get_role (AtkObject *accessible);
504 AtkState atk_object_get_state (AtkObject *accessible);
505 gint atk_object_get_index_in_parent (AtkObject *accessible);
506 void atk_object_set_name (AtkObject *accessible,
508 void atk_object_set_description (AtkObject *accessible,
509 const gchar *description);
510 void atk_object_set_parent (AtkObject *accessible,
512 void atk_object_set_role (AtkObject *accessible,
517 * to install property change listener, one must
518 * install signal handler for gobject "properties_changed" signal.
519 * (for single notifications of multiple changes).
520 * We could use the "notify" signal instead.
523 guint atk_object_connect_property_change_handler (AtkObject *accessible,
524 AtkPropertyChangeHandler *handler);
525 void atk_object_remove_property_change_handler (AtkObject *accessible,
529 * Note: the properties which are registered with the GType
530 * property registry, for type ATK_TYPE_OBJECT, are as follows:
533 * "accessible-description"
534 * "accessible-parent"
539 * accessibility property change listeners should use the
540 * normal GObject property interfaces and "properties_changed"
541 * signal handler semantics to interpret the property change
542 * information relayed from AtkObject.
543 * (AtkObject instances will connect to the "properties_changed"
544 * signal in their host objects, and relay the signals when appropriate).
547 /* For other signals, see related interfaces
558 * The usage model for obtaining these interface instances is:
559 * ATK_<interfacename>_GET_IFACE(GObject *accessible),
560 * where accessible, though specified as a GObject, is
561 * the AtkObject instance being queried.
562 * More usually, the interface will be used via a cast to the
563 * interface's corresponding "type":
565 * AtkText textImpl = ATK_TEXT(accessible);
568 * cpos = atk_text_get_caret_position(textImpl);
571 * If it's known in advance that accessible implements AtkTextIface,
572 * this is shortened to:
574 * cpos = atk_text_get_caret_position (ATK_TEXT (accessible));
579 ATK_RELATION_NULL = 0,
581 ATK_RELATION_CONTROLLED_BY,
582 ATK_RELATION_CONTROLLER_FOR,
583 ATK_RELATION_LABEL_FOR,
584 ATK_RELATION_LABELLED_BY,
585 ATK_RELATION_MEMBER_OF,
586 ATK_RELATION_LAST_DEFINED
589 AtkRelationType atk_relation_type_register (gchar *name);
592 * Create a new relation for the specified key and the specified list
595 AtkRelation* atk_relation_new (GArray *target,
596 AtkRelationType relationship);
598 * Returns whether the relation set contains a relation that matches the
601 gboolean atk_relation_set_contains (AtkRelationSet *set,
602 AtkRelationType relationship);
604 * Remove a relation from the from the relation set.
606 void atk_relation_set_remove (AtkRelationSet *set,
607 AtkRelation *relation);
609 * Add a new relation to the current relation set if it is not already
612 void atk_relation_set_add (AtkRelationSet *set,
613 AtkRelation *relation);
615 * Returns the number of relations in a relation set.
617 gint atk_relation_set_get_n_relations (AtkRelationSet *set);
619 * Returns the relation at the specified position in the relation set.
621 AtkRelation* atk_relation_set_get_relation (AtkRelationSet *set,
624 * Returns a relation that matches the specified type.
626 AtkRelation* atk_relation_set_get_relation_by_type (AtkRelationSet *set,
627 AtkRelationType relationship);
630 * Returns the type of a relation.
632 AtkRelationType atk_relation_get_type (AtkRelation *relation);
634 * Returns the target list of a relation.
636 GArray* atk_relation_get_target (AtkRelation *relation);
638 gchar* atk_state_mask_get_name (AtkStateMask state);
639 AtkStateMask atk_state_mask_for_name (gchar *name);
643 #endif /* __cplusplus */
646 #endif /* __ATK_OBJECT_H__ */