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 Lesser 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 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser 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.
22 #include <glib-object.h>
26 /* New GObject properties registered by AtkObject */
29 PROP_0, /* gobject convention */
33 PROP_PARENT, /* ancestry has changed */
34 PROP_CHILD, /* a child has been added or removed */
35 PROP_STATE, /* AtkStateSet for the object has changed */
36 PROP_TEXT, /* Used only by AtkText implementors */
37 PROP_CARET, /* Used only by AtkText implementors */
43 PROP_TABLE_COLUMN_DESCRIPTION,
44 PROP_TABLE_COLUMN_HEADER,
45 PROP_TABLE_ROW_DESCRIPTION,
46 PROP_TABLE_ROW_HEADER,
49 PROP_LAST /* gobject convention */
58 static void atk_object_class_init (AtkObjectClass *klass);
59 static void atk_object_init (AtkObject *accessible,
60 AtkObjectClass *klass);
61 static AtkRelationSet* atk_object_real_ref_relation_set (AtkObject *accessible);
63 static void atk_object_real_set_property(GObject *object,
67 static void atk_object_real_get_property(GObject *object,
71 static void atk_object_finalize (GObject *object);
72 static void atk_object_real_set_role (AtkObject *object,
75 static guint atk_object_signals[LAST_SIGNAL] = { 0, };
77 static gpointer parent_class = NULL;
79 static const gchar* atk_object_name_property_name = "accessible-name";
80 static const gchar* atk_object_name_property_state = "accessible-state";
81 static const gchar* atk_object_name_property_description = "accessible-description";
82 static const gchar* atk_object_name_property_child = "accessible-child";
83 static const gchar* atk_object_name_property_parent = "accessible-parent";
84 static const gchar* atk_object_name_property_text = "accessible-text";
85 static const gchar* atk_object_name_property_caret = "accessible-caret";
86 static const gchar* atk_object_name_property_selection = "accessible-selection";
87 static const gchar* atk_object_name_property_value = "accessible-value";
88 static const gchar* atk_object_name_property_visible = "accessible-visible-data";
89 static const gchar* atk_object_name_property_role = "accessible-role";
90 static const gchar* atk_object_name_property_table_caption = "accessible-table-caption";
91 static const gchar* atk_object_name_property_table_column_description = "accessible-table-column-description";
92 static const gchar* atk_object_name_property_table_column_header = "accessible-table-column-header";
93 static const gchar* atk_object_name_property_table_row_description = "accessible-table-row-description";
94 static const gchar* atk_object_name_property_table_row_header = "accessible-table-row-header";
95 static const gchar* atk_object_name_property_table_summary = "accessible-table-summary";
96 static const gchar* atk_object_name_property_model = "accessible-model";
99 atk_object_get_type (void)
101 static GType type = 0;
105 static const GTypeInfo typeInfo =
107 sizeof (AtkObjectClass),
108 (GBaseInitFunc) NULL,
109 (GBaseFinalizeFunc) NULL,
110 (GClassInitFunc) atk_object_class_init,
111 (GClassFinalizeFunc) NULL,
115 (GInstanceInitFunc) atk_object_init,
117 type = g_type_register_static (G_TYPE_OBJECT, "AtkObject", &typeInfo, 0) ;
123 atk_object_class_init (AtkObjectClass *klass)
125 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
127 parent_class = g_type_class_ref (G_TYPE_OBJECT);
129 gobject_class->set_property = atk_object_real_set_property;
130 gobject_class->get_property = atk_object_real_get_property;
131 gobject_class->finalize = atk_object_finalize;
133 klass->ref_relation_set = atk_object_real_ref_relation_set;
134 klass->set_role = atk_object_real_set_role;
137 * We do not define default signal handlers here
139 klass->focus_event = NULL;
140 klass->children_changed = NULL;
142 g_object_class_install_property (gobject_class,
144 g_param_spec_string (atk_object_name_property_name,
146 "Object instance\'s name formatted for "
147 "assistive technology access",
150 g_object_class_install_property (gobject_class,
152 g_param_spec_string (atk_object_name_property_description,
153 "Accessible Description",
154 "Description of an object, formatted for "
155 "assistive technology access",
158 g_object_class_install_property (gobject_class,
160 g_param_spec_int (atk_object_name_property_state,
161 "Accessible State Set",
162 "The accessible state set of this object "
163 "or its UI component",
168 g_object_class_install_property (gobject_class,
170 g_param_spec_object (atk_object_name_property_child,
172 "Is used to notify that a child has been added or removed ",
175 g_object_class_install_property (gobject_class,
177 g_param_spec_object (atk_object_name_property_parent,
179 "Is used to notify that the parent has changed ",
182 g_object_class_install_property (gobject_class,
184 g_param_spec_object (atk_object_name_property_text,
186 "Is used to notify that the text has changed ",
189 g_object_class_install_property (gobject_class,
191 g_param_spec_int (atk_object_name_property_caret,
193 "Is used to notify that the caret position has changed ",
198 g_object_class_install_property (gobject_class,
200 g_param_spec_object (atk_object_name_property_selection,
201 "Accessible Selection",
202 "Is used to notify that the selection has changed ",
205 g_object_class_install_property (gobject_class,
207 g_param_spec_double (atk_object_name_property_value,
209 "Is used to notify that the value has changed ",
214 g_object_class_install_property (gobject_class,
216 g_param_spec_object (atk_object_name_property_visible,
217 "Accessible Visible Data",
218 "Is used to notify that the visual appearance of the object has changed ",
221 g_object_class_install_property (gobject_class,
223 g_param_spec_int (atk_object_name_property_role,
225 "The accessible role this object ",
230 g_object_class_install_property (gobject_class,
232 g_param_spec_object (atk_object_name_property_table_caption,
233 "Accessible Table Caption",
234 "Is used to notify that the table caption has changed ",
237 g_object_class_install_property (gobject_class,
238 PROP_TABLE_COLUMN_HEADER,
239 g_param_spec_object (atk_object_name_property_table_column_header,
240 "Accessible Table Column Header",
241 "Is used to notify that the table column header has changed ",
244 g_object_class_install_property (gobject_class,
245 PROP_TABLE_COLUMN_DESCRIPTION,
246 g_param_spec_int (atk_object_name_property_table_column_description,
247 "Accessible Table Column Description",
248 "Is used to notify that the table columnscription has changed ",
253 g_object_class_install_property (gobject_class,
254 PROP_TABLE_ROW_HEADER,
255 g_param_spec_object (atk_object_name_property_table_row_header,
256 "Accessible Table Row Header",
257 "Is used to notify that the table row header has changed ",
260 g_object_class_install_property (gobject_class,
261 PROP_TABLE_ROW_DESCRIPTION,
262 g_param_spec_int (atk_object_name_property_table_row_description,
263 "Accessible Table Row Description",
264 "Is used to notify that the table row description has changed ",
269 g_object_class_install_property (gobject_class,
271 g_param_spec_object (atk_object_name_property_table_summary,
272 "Accessible Table Summary",
273 "Is used to notify that the table summary has changed ",
276 g_object_class_install_property (gobject_class,
278 g_param_spec_object (atk_object_name_property_model,
280 "Is used to notify that the model for Table or Tree has changed ",
284 * The signal "children_changed" supports two details:
287 atk_object_signals[CHILDREN_CHANGED] =
288 g_signal_new ("children_changed",
289 G_TYPE_FROM_CLASS (klass),
290 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
291 G_STRUCT_OFFSET (AtkObjectClass, children_changed),
293 g_cclosure_marshal_VOID__UINT_POINTER,
295 2, G_TYPE_UINT, G_TYPE_POINTER);
296 atk_object_signals[FOCUS_EVENT] =
297 g_signal_new ("focus_event",
298 G_TYPE_FROM_CLASS (klass),
300 G_STRUCT_OFFSET (AtkObjectClass, focus_event),
302 g_cclosure_marshal_VOID__BOOLEAN,
308 atk_object_init (AtkObject *accessible,
309 AtkObjectClass *klass)
314 atk_implementor_get_type (void)
316 static GType type = 0;
320 static const GTypeInfo typeInfo =
322 sizeof (AtkImplementorIface),
323 (GBaseInitFunc) NULL,
324 (GBaseFinalizeFunc) NULL,
327 type = g_type_register_static (G_TYPE_INTERFACE, "AtkImplementorIface", &typeInfo, 0) ;
334 * atk_object_get_name:
335 * @accessible: an #AtkObject
337 * Gets the accessible name of the accessible.
339 * Returns: a character string representing the accessible name of the object.
341 G_CONST_RETURN gchar*
342 atk_object_get_name (AtkObject *accessible)
344 AtkObjectClass *klass;
346 g_return_val_if_fail (accessible != NULL, NULL);
347 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
349 klass = ATK_OBJECT_GET_CLASS (accessible);
351 return (klass->get_name) (accessible);
357 * atk_object_get_description:
358 * @accessible: an #AtkObject
360 * Gets the accessible description of the accessible.
362 * Returns: a character string representing the accessible description
366 G_CONST_RETURN gchar*
367 atk_object_get_description (AtkObject *accessible)
369 AtkObjectClass *klass;
371 g_return_val_if_fail (accessible != NULL, NULL);
372 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
374 klass = ATK_OBJECT_GET_CLASS (accessible);
375 if (klass->get_description)
376 return (klass->get_description) (accessible);
382 * atk_object_get_parent:
383 * @accessible: an #AtkObject
385 * Gets the accessible parent of the accessible.
387 * Returns: a #AtkObject representing the accessible parent of the accessible
390 atk_object_get_parent (AtkObject *accessible)
392 AtkObjectClass *klass;
394 g_return_val_if_fail (accessible != NULL, NULL);
395 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
397 klass = ATK_OBJECT_GET_CLASS (accessible);
398 if (klass->get_parent)
399 return (klass->get_parent) (accessible);
405 * atk_object_get_n_accessible_children:
406 * @accessible: an #AtkObject
408 * Gets the number of accessible children of the accessible.
410 * Returns: an integer representing the number of accessible children
414 atk_object_get_n_accessible_children (AtkObject *accessible)
416 AtkObjectClass *klass;
418 g_return_val_if_fail (accessible != NULL, 0);
419 g_return_val_if_fail (ATK_IS_OBJECT (accessible), 0);
421 klass = ATK_OBJECT_GET_CLASS (accessible);
422 if (klass->get_n_children)
423 return (klass->get_n_children) (accessible);
429 * atk_object_ref_accessible_child:
430 * @accessible: an #AtkObject
431 * @i: a gint representing the position of the child, starting from 0
433 * Gets a reference to the specified accessible child of the object.
434 * The accessible children are 0-based so the first accessible child is
435 * at index 0, the second at index 1 and so on.
437 * Returns: an #AtkObject representing the specified accessible child
441 atk_object_ref_accessible_child (AtkObject *accessible,
444 AtkObjectClass *klass;
446 g_return_val_if_fail (accessible != NULL, NULL);
447 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
449 klass = ATK_OBJECT_GET_CLASS (accessible);
450 if (klass->ref_child)
451 return (klass->ref_child) (accessible, i);
457 * atk_object_ref_relation_set:
458 * @accessible: an #AtkObject
460 * Gets the #AtkRelationSet associated with the object.
462 * Returns: an #AtkRelationSet representing the relation set of the object.
465 atk_object_ref_relation_set (AtkObject *accessible)
467 AtkObjectClass *klass;
469 g_return_val_if_fail (accessible != NULL, NULL);
470 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
472 klass = ATK_OBJECT_GET_CLASS (accessible);
473 if (klass->ref_relation_set)
474 return (klass->ref_relation_set) (accessible);
481 * @name: a character string describing the new role.
483 * Registers the role specified by @name.
485 * Returns: an #AtkRole for the new role.
488 atk_role_register (const gchar *name)
490 /* TODO: associate name with new type */
491 static guint type = ATK_ROLE_LAST_DEFINED;
496 * atk_object_get_role:
497 * @accessible: an #AtkObject
499 * Gets the role of the accessible.
501 * Returns: an #AtkRole which is the role of the accessible
504 atk_object_get_role (AtkObject *accessible) {
505 AtkObjectClass *klass;
507 g_return_val_if_fail (accessible != NULL, ATK_ROLE_UNKNOWN);
508 g_return_val_if_fail (ATK_IS_OBJECT (accessible), ATK_ROLE_UNKNOWN);
510 klass = ATK_OBJECT_GET_CLASS (accessible);
512 return (klass->get_role) (accessible);
514 return ATK_ROLE_UNKNOWN;
518 * atk_object_ref_state_set:
519 * @accessible: an #AtkObject
521 * Gets a reference to the state set of the accessible; the caller must
522 * unreference it when it is no longer needed.
524 * Returns: a reference to an #AtkStateSet which is the state
525 * set of the accessible
528 atk_object_ref_state_set (AtkObject *accessible) {
529 AtkObjectClass *klass;
531 g_return_val_if_fail (accessible != NULL, NULL);
532 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
534 klass = ATK_OBJECT_GET_CLASS (accessible);
535 if (klass->ref_state_set)
536 return (klass->ref_state_set) (accessible);
542 * atk_object_get_index_in_parent:
543 * @accessible: an #AtkObject
545 * Gets the 0-based index of this accessible in its parent; returns -1 if the
546 * accessible does not have an accessible parent.
548 * Returns: an integer which is the index of the accessible in its parent
551 atk_object_get_index_in_parent (AtkObject *accessible)
553 AtkObjectClass *klass;
555 g_return_val_if_fail (accessible != NULL, -1);
556 g_return_val_if_fail (ATK_OBJECT (accessible), -1);
558 klass = ATK_OBJECT_GET_CLASS (accessible);
559 if (klass->get_index_in_parent)
560 return (klass->get_index_in_parent) (accessible);
566 * atk_object_set_name:
567 * @accessible: an #AtkObject
568 * @name: a character string to be set as the accessible name
570 * Sets the accessible name of the accessible.
573 atk_object_set_name (AtkObject *accessible,
576 AtkObjectClass *klass;
578 g_return_if_fail (accessible != NULL);
579 g_return_if_fail (ATK_IS_OBJECT (accessible));
580 g_return_if_fail (name != NULL);
582 klass = ATK_OBJECT_GET_CLASS (accessible);
585 (klass->set_name) (accessible, name);
586 g_object_notify (G_OBJECT (accessible), atk_object_name_property_name);
591 * atk_object_set_description:
592 * @accessible: an #AtkObject
593 * @description : a character string to be set as the accessible description
595 * Sets the accessible description of the accessible.
598 atk_object_set_description (AtkObject *accessible,
599 const gchar *description)
601 AtkObjectClass *klass;
603 g_return_if_fail (accessible != NULL);
604 g_return_if_fail (ATK_IS_OBJECT (accessible));
605 g_return_if_fail (description != NULL);
607 klass = ATK_OBJECT_GET_CLASS (accessible);
608 if (klass->set_description)
610 (klass->set_description) (accessible, description);
611 g_object_notify (G_OBJECT (accessible), atk_object_name_property_description);
616 * atk_object_set_parent:
617 * @accessible: an #AtkObject
618 * @parent : an #AtkObject to be set as the accessible parent
620 * Sets the accessible parent of the accessible.
623 atk_object_set_parent (AtkObject *accessible,
626 AtkObjectClass *klass;
628 g_return_if_fail (accessible != NULL);
629 g_return_if_fail (ATK_IS_OBJECT (accessible));
631 klass = ATK_OBJECT_GET_CLASS (accessible);
632 if (klass->set_parent)
633 (klass->set_parent) (accessible, parent);
637 * atk_object_set_role:
638 * @accessible: an #AtkObject
639 * @role : an #AtkRole to be set as the role
641 * Sets the role of the accessible.
644 atk_object_set_role (AtkObject *accessible,
647 AtkObjectClass *klass;
649 g_return_if_fail (accessible != NULL);
650 g_return_if_fail (ATK_IS_OBJECT (accessible));
652 klass = ATK_OBJECT_GET_CLASS (accessible);
654 (klass->set_role) (accessible, role);
658 * atk_object_connect_property_change_handler:
659 * @accessible: an #AtkObject
660 * @handler : a function to be called when a property changes its value
662 * Specifies a function to be called when a property changes value.
664 * Returns: a #guint which is the handler id used in
665 * atk_object_remove_property_change_handler()
668 atk_object_connect_property_change_handler (AtkObject *accessible,
669 AtkPropertyChangeHandler *handler)
671 AtkObjectClass *klass;
673 g_return_val_if_fail (accessible != NULL, 0);
674 g_return_val_if_fail (ATK_IS_OBJECT (accessible), 0);
675 g_return_val_if_fail ((handler != NULL), 0);
677 klass = ATK_OBJECT_GET_CLASS (accessible);
678 if (klass->connect_property_change_handler)
679 return (klass->connect_property_change_handler) (accessible, handler);
685 * atk_object_remove_property_change_handler:
686 * @accessible: an #AtkObject
687 * @handler_id : a guint which identifies the handler to be removed.
689 * Removes a property change handler.
692 atk_object_remove_property_change_handler (AtkObject *accessible,
695 AtkObjectClass *klass;
697 g_return_if_fail (accessible != NULL);
698 g_return_if_fail (ATK_IS_OBJECT (accessible));
700 klass = ATK_OBJECT_GET_CLASS (accessible);
701 if (klass->remove_property_change_handler)
702 (klass->remove_property_change_handler) (accessible, handler_id);
706 * atk_implementor_ref_accessible:
707 * @implementor: The #GObject instance which should implement #AtkImplementorIface
708 * if a non-null return value is required.
710 * Gets a reference to an object's #AtkObject implementation, if
711 * the object implements #AtkObjectIface
713 * Returns: a reference to an object's #AtkObject implementation
716 atk_implementor_ref_accessible (AtkImplementor *object)
718 AtkImplementorIface *iface;
719 AtkObject *accessible = NULL;
721 g_return_val_if_fail (object != NULL, NULL);
722 g_return_val_if_fail (ATK_IS_IMPLEMENTOR (object), NULL);
724 iface = ATK_IMPLEMENTOR_GET_IFACE (object);
727 accessible = iface->ref_accessible (object);
729 g_return_val_if_fail ((accessible != NULL), NULL);
734 static AtkRelationSet*
735 atk_object_real_ref_relation_set (AtkObject *accessible)
737 if (accessible->relation_set)
738 g_object_ref (accessible->relation_set);
740 return accessible->relation_set;
744 atk_object_real_set_property (GObject *object,
749 AtkObject *accessible;
751 accessible = ATK_OBJECT (object);
756 atk_object_set_name (accessible, g_value_get_string (value));
758 case PROP_DESCRIPTION:
759 atk_object_set_description (accessible, g_value_get_string (value));
762 g_print ("This interface does not support setting the state set of an accessible object\n");
765 if (ATK_IS_VALUE (accessible))
766 atk_value_set_current_value (ATK_VALUE (accessible), value);
774 atk_object_real_get_property (GObject *object,
779 AtkObject *accessible;
781 accessible = ATK_OBJECT (object);
786 g_value_set_string (value, atk_object_get_name (accessible));
788 case PROP_DESCRIPTION:
789 g_value_set_string (value, atk_object_get_description (accessible));
792 if (ATK_IS_VALUE (accessible))
793 atk_value_get_current_value (ATK_VALUE (accessible), value);
801 atk_object_finalize (GObject *object)
803 AtkObject *accessible;
805 g_return_if_fail (ATK_IS_OBJECT (object));
807 accessible = ATK_OBJECT (object);
809 g_free (accessible->name);
810 g_free (accessible->description);
813 * Free memory allocated for relation set if it have been allocated.
815 if (accessible->relation_set)
817 g_object_unref (accessible->relation_set);
820 G_OBJECT_CLASS (parent_class)->finalize (object);
824 atk_object_real_set_role (AtkObject *object,