2167049aa3020508fb14d57ece4cafde43113a06
[platform/upstream/atk.git] / atk / atkobject.h
1 /* ATK -  Accessibility Toolkit
2  * Copyright 2001 Sun Microsystems Inc.
3  *
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.
8  *
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.
13  *
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.
18  */
19
20 #ifndef __ATK_OBJECT_H__
21 #define __ATK_OBJECT_H__
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif /* __cplusplus */
26
27 #include <glib-object.h>
28
29 /*
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:
36  */
37 typedef enum
38 {
39   ATK_CHILD_ADDED,
40   ATK_CHILD_REMOVED,
41   ATK_CHILD_CHANGED
42 } AtkChildChangeType;
43
44 typedef enum
45 {
46   ATK_ROLE_INVALID,
47   /* Object is used to alert the user about something */
48   ATK_ROLE_ALERT,
49   /* Object that can be drawn into and is sued to trap events */
50   ATK_ROLE_CANVAS,
51   /*
52    * A choice that can be checked or unchecked and provides a separate
53    * indicator for the current state.
54    */
55   ATK_ROLE_CHECK_BOX,
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 */
61   ATK_ROLE_COMBO_BOX,
62   /* An inconifed internal frame within a DESKTOP_PANE */
63   ATK_ROLE_DESKTOP_ICON,
64   /*
65    * A pane that supports internal frames and iconified versions of those
66    * internal frames.
67    */
68   ATK_ROLE_DESKTOP_FRAME,
69   /* A top level window with title bar and a border */
70   ATK_ROLE_DIALOG,
71   /*
72    * A pane that allows the user to navigate through and select the contents
73    * of a directory
74    */
75   ATK_ROLE_DIRECTORY_PANE,
76   /*
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
79    * filename.
80    */
81   ATK_ROLE_FILE_CHOOSER,
82   /*
83    * A object that fills up space in a user interface
84    */
85   ATK_ROLE_FILLER,
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. */
89   ATK_ROLE_FRAME,
90   /* A pane that is guaranteed to be painted on top of all panes beneath it */
91   ATK_ROLE_GLASS_PANE,
92   /*
93    * A document container for HTML, whose children
94    * represent the document content.
95    */
96   ATK_ROLE_HTML_CONTAINER,
97   /* A small fixed size picture, typically used to decorate components */
98   ATK_ROLE_ICON,
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 */
102   ATK_ROLE_LABEL,
103   /*
104    * A specialized pane that allows its children to be drawn in layers,
105    * providing a form of stacking order.
106    */
107   ATK_ROLE_LAYERED_PANE,
108   /*
109    * An object that presents a list of objects to the user and allows the
110    * user to select one or more of them.
111    */
112   ATK_ROLE_LIST,
113    /* An object that represents an element of a list. */
114   ATK_ROLE_LIST_ITEM,
115   /*
116    * An object usually found inside a menu bar that contains a list of
117    * actions the user can choose from.
118    */
119   ATK_ROLE_MENU,
120   /*
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.
123    */
124   ATK_ROLE_MENU_BAR,
125   /*
126    * An object usually contained in a menu that presents an action the
127    * user can choose.
128    */
129   ATK_ROLE_MENU_ITEM,
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 */
133   ATK_ROLE_PAGE_TAB,
134   /*
135    * An object that presents a series of panels (or page tabs), one at a time,
136    * through some mechanism provided by the object.
137    */
138   ATK_ROLE_PAGE_TAB_LIST,
139   /* A generic container that is often used to group objects. */
140   ATK_ROLE_PANEL,
141   /*
142    * A text object uses for passwords, or other places where the text
143    * content is not shown visibly to the user.
144    */
145   ATK_ROLE_PASSWORD_TEXT,
146   /*
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.
149    */
150   ATK_ROLE_POPUP_MENU,
151   /* An object used to indicate how much of a task has been completed. */
152   ATK_ROLE_PROGRESS_BAR,
153   /*
154    * An object the user can manipulate to tell the application to do
155    * something.
156    */
157   ATK_ROLE_PUSH_BUTTON,
158   /*
159    * A specialized check box that will cause other radio buttons in the
160    * same group to become uncghecked when this one is checked.
161    */
162   ATK_ROLE_RADIO_BUTTON,
163   /*
164    * A specialized pane that has a glass pane and a layered pane as its
165    * children.
166    */
167   ATK_ROLE_ROOT_PANE,
168   /* The header for a row of data */
169   ATK_ROLE_ROW_HEADER,
170   /*
171    * An object usually used to allow a user to incrementally view a large
172    * amount of data.
173    */
174   ATK_ROLE_SCROLL_BAR,
175   /*
176    * An object that allows a user to incrementally view a large amount
177    * of information.
178    */
179   ATK_ROLE_SCROLL_PANE,
180   /*
181    * An object usually contained in a menu to provide a visible and
182    * logical separation of the contents in a menu.
183    */
184   ATK_ROLE_SEPARATOR,
185   /* An object that allows the user to select from a bounded range */
186   ATK_ROLE_SLIDER,
187   /* A specialized panel that presents two other panels at the same time. */
188   ATK_ROLE_SPLIT_PANE,
189   /* An object used to rpesent information in terms of rows and columns. */
190   ATK_ROLE_TABLE,
191   ATK_ROLE_TABLE_CELL,
192   ATK_ROLE_TABLE_COLUMN_HEADER,
193   ATK_ROLE_TABLE_ROW_HEADER,
194   /* An object that presents text to the user */
195   ATK_ROLE_TEXT,
196   /*
197    * A specialized push button that can be checked or unchecked, but does
198    * not procide a separate indicator for the current state.
199    */
200   ATK_ROLE_TOGGLE_BUTTON,
201   /*
202    * A bar or palette usually composed of push buttons or toggle buttons
203    */
204   ATK_ROLE_TOOL_BAR,
205   /*
206    * An object that provides information about another object
207    */
208   ATK_ROLE_TOOL_TIP,
209   /* An object used to repsent hierarchical information to the user. */
210   ATK_ROLE_TREE,
211   /*
212    * The object contains some Accessible information, but its role is
213    * not known.
214    */
215   ATK_ROLE_UNKNOWN,
216   /* An object usually used in a scroll pane. */
217   ATK_ROLE_VIEWPORT,
218   /* A top level window with no title or border */
219   ATK_ROLE_WINDOW,
220   /* not a valid role, used for finding end of enumeration. */
221   ATK_ROLE_LAST_DEFINED
222 } AtkRole;
223
224 AtkRole                  atk_role_register        (const gchar *name);
225
226 typedef enum
227 {
228   ATK_STATE_INVALID,
229   /* Indicates a window is currently the active window */
230   ATK_STATE_ACTIVE,
231   /* Indicates that the object is armed */
232   ATK_STATE_ARMED,
233   /* Indicates the current object is busy */
234   ATK_STATE_BUSY,
235   /* Indicates this object is currently checked */
236   ATK_STATE_CHECKED,
237   /* Indicates this object is collapsed */
238   ATK_STATE_COLLAPSED,
239   /* Indicates the user can change the contents of this object */
240   ATK_STATE_EDITABLE,
241   /* Indicates this object allows progressive disclosure of its children */
242   ATK_STATE_EXPANDABLE,
243   /* Indicates this object its expanded */
244   ATK_STATE_EXPANDED,
245   /*
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
249    */
250   ATK_STATE_FOCUSABLE,
251   /* Indicates this object currently has the keyboard focus */
252   ATK_STATE_FOCUSED,
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 */
256   ATK_STATE_ICONIFIED,
257   /*
258    * Indicates something must be done with this object before the user can
259    * interact with an object in a different window.
260    */
261   ATK_STATE_MODAL,
262   /* Indicates this (text) object can contain multiple lines of text */
263   ATK_STATE_MULTI_LINE,
264   /*
265    * Indicates this object allows more than one of its children to be
266    * selected at the same time
267    */
268   ATK_STATE_MULTISELECTABLE,
269   /* Indicates this object paints every pixel within its rectangular region. */
270   ATK_STATE_OPAQUE,
271   /* Indicates this object is currently pressed */
272   ATK_STATE_PRESSED,
273   /* Indicates the size of this object is not fixed */
274   ATK_STATE_RESIZABLE,
275   /*
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.
279    */
280   ATK_STATE_SELECTABLE,
281   /*
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.
285    */
286   ATK_STATE_SELECTED,
287   /* Indicates this object is sensitive */
288   ATK_STATE_SENSITIVE,
289   /*
290    * Indicates this object, the object's parent, the object's parent's
291    * parent, and so on, are all visible
292    */
293   ATK_STATE_SHOWING,
294   /* Indicates this (text) object can contain only a single line of text */
295   ATK_STATE_SINGLE_LINE,
296   /* Indicates this object is transient */
297   ATK_STATE_TRANSIENT,
298   /* Indicates the orientation of this object is vertical */
299   ATK_STATE_VERTICAL,
300   /* Indicates this object is visible */
301   ATK_STATE_VISIBLE,
302   ATK_STATE_LAST_DEFINED
303 } AtkStateType;
304
305 AtkStateType               atk_state_type_register      (const gchar *name);
306
307
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))
314
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))
319
320
321 typedef struct _AtkImplementor            AtkImplementor; /* dummy typedef */
322 typedef struct _AtkImplementorIface       AtkImplementorIface;
323
324
325 typedef struct _AtkObject                 AtkObject;
326 typedef struct _AtkObjectClass            AtkObjectClass;
327 typedef struct _AtkRelation               AtkRelation;
328 typedef struct _AtkRelationSet            AtkRelationSet;
329
330 typedef guint64                           AtkStateMask;
331 typedef guint64                           AtkState;
332
333 #define ATK_STATE(state_enum)             ((AtkStateMask)(1 << ((guint64)(state_enum)%64)))
334
335 struct _AtkPropertyValues
336 {
337   gchar  *property_name;
338   GValue old_value;
339   GValue new_value;
340 };
341
342 typedef struct _AtkPropertyValues        AtkPropertyValues;
343
344 /*
345  * For most properties the old_value field of AtkPropertyValues will
346  * not contain a valid value.
347  *
348  * Currently, the only property for which old_value is used is
349  * accessible-state; for instance if there is a focus state the
350  * property change handler will be called for the object which lost the focus
351  * with the old_value containing an AtkState value corresponding to focused
352  * and the property change handler will be called for the object which
353  * received the focus with the new_value containing an AtkState value
354  * corresponding to focused.
355  */
356 typedef void (*AtkPropertyChangeHandler) (AtkObject*, AtkPropertyValues*);
357
358
359 struct _AtkObject
360 {
361   GObject parent;
362
363   gchar *description;
364   gchar *name;
365   AtkObject *accessible_parent;
366   AtkRole role;
367   AtkRelationSet *relation_set;
368 };
369
370 struct _AtkObjectClass
371 {
372   GObjectClass parent;
373
374   /*
375    * Gets the accessible name of the object
376    */
377   G_CONST_RETURN gchar*    (* get_name)            (AtkObject                *accessible);
378   /*
379    * Gets the accessible description of the object
380    */
381   G_CONST_RETURN gchar*    (* get_description)     (AtkObject                *accessible);
382   /*
383    * Gets the accessible parent of the object
384    */
385   AtkObject*               (*get_parent)           (AtkObject                *accessible);
386
387   /*
388    * Gets the number of accessible children of the object
389    */
390   gint                    (* get_n_children)       (AtkObject                *accessible);
391   /*
392    * Returns a reference to the specified accessible child of the object.
393    * The accessible children are 0-based so the first accessible child is
394    * at index 0, the second at index 1 and so on.
395    */
396   AtkObject*              (* ref_child)            (AtkObject                *accessible,
397                                                     gint                      i);
398   /*
399    * Gets the 0-based index of this object in its parent; returns -1 if the
400    * object does not have an accessible parent.
401    */
402   gint                    (* get_index_in_parent) (AtkObject                 *accessible);
403   /*
404    * Gets the RelationSet associated with the object
405    */
406   AtkRelationSet*         (* get_relation_set)    (AtkObject                 *accessible);
407   /*
408    * Gets the role of the object
409    */
410   AtkRole                 (* get_role)            (AtkObject                 *accessible);
411   /*
412    * Gets the state set of the object
413    */
414   AtkState                (* get_state)           (AtkObject                 *accessible);
415   /*
416    * Sets the accessible name of the object
417    */
418   void                    (* set_name)            (AtkObject                 *accessible,
419                                                    const gchar               *name);
420   /*
421    * Sets the accessible description of the object
422    */
423   void                    (* set_description)     (AtkObject                 *accessible,
424                                                    const gchar               *description);
425   /*
426    * Sets the accessible parent of the object
427    */
428   void                    (* set_parent)          (AtkObject                 *accessible,
429                                                    AtkObject                 *parent);
430   /*
431    * Sets the accessible role of the object
432    */
433   void                    (* set_role)            (AtkObject                 *accessible,
434                                                    AtkRole                   role);
435   /*
436    * Specifies a function to be called when a property changes value
437    */
438 guint                     (* connect_property_change_handler)    (AtkObject
439                  *accessible,
440                                                                   AtkPropertyChangeHandler       *handler);
441   /*
442    * Removes a property change handler which was specified using
443    * connect_property_change_handler
444    */
445 void                      (* remove_property_change_handler)     (AtkObject
446                 *accessible,
447                                                                   guint
448                 handler_id);
449   /*
450    * The signal handler which is executed when there is a change in the
451    * children of the object
452    */
453   void                    (* children_changed)    (AtkObject                  *accessible,
454                                                    AtkChildChangeType         change_type,
455                                                    AtkObject                  *changed_child);
456 };
457 GType            atk_object_get_type   (void);
458
459 struct _AtkImplementorIface
460 {
461   GTypeInterface parent;
462
463   AtkObject*   (*ref_accessible) (AtkImplementor *implementor);
464 };
465 GType atk_implementor_get_type (void);
466
467 /*
468  * This method uses the ref_accessible method in AtkImplementorIface,
469  * if the object's class implements AtkImplementorIface.
470  * Otherwise it returns %NULL.
471  *
472  * IMPORTANT:
473  * Note also that because this method may return flyweight objects,
474  * it increments the returned AtkObject's reference count.
475  * Therefore it is the responsibility of the calling
476  * program to unreference the object when no longer needed.
477  * (c.f. gtk_widget_get_accessible() where this is not the case).
478  */
479 AtkObject*              atk_implementor_ref_accessible            (AtkImplementor *implementor);
480
481 /*
482  * Properties directly supported by AtkObject
483  */
484
485 G_CONST_RETURN gchar*   atk_object_get_name                       (AtkObject *accessible);
486 G_CONST_RETURN gchar*   atk_object_get_description                (AtkObject *accessible);
487 AtkObject*              atk_object_get_parent                     (AtkObject *accessible);
488 gint                    atk_object_get_n_accessible_children      (AtkObject *accessible);
489 AtkObject*              atk_object_ref_accessible_child           (AtkObject *accessible,
490                                                                    gint        i);
491 AtkRelationSet*         atk_object_get_relation_set               (AtkObject *accessible);
492 AtkRole                 atk_object_get_role                       (AtkObject *accessible);
493 AtkState                atk_object_get_state                      (AtkObject *accessible);
494 gint                    atk_object_get_index_in_parent            (AtkObject *accessible);
495 void                    atk_object_set_name                       (AtkObject *accessible,
496                                                                    const gchar *name);
497 void                    atk_object_set_description                (AtkObject *accessible,
498                                                                    const gchar *description);
499 void                    atk_object_set_parent                     (AtkObject *accessible,
500                                                                    AtkObject *parent);
501 void                    atk_object_set_role                       (AtkObject *accessible,
502                                                                    AtkRole   role);
503
504
505 /*
506  * to install property change listener, one must
507  * install signal handler for gobject "properties_changed" signal.
508  * (for single notifications of multiple changes).
509  * We could use the "notify" signal instead.
510  *
511  */
512 guint                atk_object_connect_property_change_handler  (AtkObject                      *accessible,
513                                                                   AtkPropertyChangeHandler       *handler);
514 void                 atk_object_remove_property_change_handler  (AtkObject                      *accessible,
515                                                                   guint                         handler_id);
516
517 /*
518  * Note: the properties which are registered with the GType
519  *   property registry, for type ATK_TYPE_OBJECT, are as follows:
520  *
521  *   "accessible-name"
522  *   "accessible-description"
523  *   "accessible-parent"
524  *   "accessible-child"
525  *   "accessible-role"
526  *   "accessible-state"
527  *
528  * accessibility property change listeners should use the
529  *   normal GObject property interfaces and "properties_changed"
530  *   signal handler semantics to interpret the property change
531  *   information relayed from AtkObject.
532  *   (AtkObject instances will connect to the "properties_changed"
533  *   signal in their host objects, and relay the signals when appropriate).
534  */
535
536 /* For other signals, see related interfaces
537  *
538  *    AtkActionIface,
539  *    AtkComponentIface,
540  *    AtkHypertextIface,
541  *    AtkImageIface,
542  *    AtkSelectionIface,
543  *    AtkTableIface,
544  *    AtkTextIface,
545  *    AtkValueIface.
546  *
547  *  The usage model for obtaining these interface instances is:
548  *    ATK_<interfacename>_GET_IFACE(GObject *accessible),
549  *    where accessible, though specified as a GObject, is
550  *    the AtkObject instance being queried.
551  *  More usually, the interface will be used via a cast to the
552  *    interface's corresponding "type":
553  *
554  *    AtkText textImpl = ATK_TEXT(accessible);
555  *    if (textImpl)
556  *      {
557  *        cpos = atk_text_get_caret_position(textImpl);
558  *      }
559  *
560  *  If it's known in advance that accessible implements AtkTextIface,
561  *    this is shortened to:
562  *
563  *    cpos = atk_text_get_caret_position (ATK_TEXT (accessible));
564  */
565
566 typedef enum
567 {
568   ATK_RELATION_NULL = 0,
569
570   ATK_RELATION_CONTROLLED_BY,
571   ATK_RELATION_CONTROLLER_FOR,
572   ATK_RELATION_LABEL_FOR,
573   ATK_RELATION_LABELLED_BY,
574   ATK_RELATION_MEMBER_OF,
575   ATK_RELATION_LAST_DEFINED
576 } AtkRelationType;
577
578 AtkRelationType atk_relation_type_register            (const gchar *name);
579
580 /*
581  * Create a new relation for the specified key and the specified list
582  * of targets.
583  */
584 AtkRelation*    atk_relation_new                      (GArray          *target,
585                                                        AtkRelationType relationship);
586 /*
587  * Returns whether the relation set contains a relation that matches the
588  * specified type.
589  */
590 gboolean        atk_relation_set_contains             (AtkRelationSet  *set,
591                                                        AtkRelationType relationship);
592 /*
593  * Remove a relation from the from the relation set.
594  */
595 void            atk_relation_set_remove               (AtkRelationSet  *set,
596                                                        AtkRelation     *relation);
597 /*
598  * Add a new relation to the current relation set if it is not already
599  * present.
600  */
601 void            atk_relation_set_add                  (AtkRelationSet  *set,
602                                                        AtkRelation     *relation);
603 /*
604  * Returns the number of relations in a relation set.
605  */
606 gint            atk_relation_set_get_n_relations      (AtkRelationSet  *set);
607 /*
608  * Returns the relation at the specified position in the relation set.
609  */
610 AtkRelation*    atk_relation_set_get_relation         (AtkRelationSet  *set,
611                                                        gint            i);
612 /*
613  * Returns a relation that matches the specified type.
614  */
615 AtkRelation*    atk_relation_set_get_relation_by_type (AtkRelationSet  *set,
616                                                        AtkRelationType relationship);
617
618 /*
619  * Returns the type of a relation.
620  */
621 AtkRelationType atk_relation_get_type                 (AtkRelation     *relation);
622 /*
623  * Returns the target list of a relation.
624  */
625 GArray*         atk_relation_get_target               (AtkRelation     *relation);
626
627 G_CONST_RETURN gchar* atk_state_mask_get_name         (AtkStateMask    state);
628 AtkStateMask          atk_state_mask_for_name         (const gchar     *name);
629
630 #ifdef __cplusplus
631 }
632 #endif /* __cplusplus */
633
634
635 #endif /* __ATK_OBJECT_H__ */