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 */
60 static void atk_object_class_init (AtkObjectClass *klass);
61 static void atk_object_init (AtkObject *accessible,
62 AtkObjectClass *klass);
63 static AtkRelationSet* atk_object_real_ref_relation_set
64 (AtkObject *accessible);
66 static void atk_object_real_set_property (GObject *object,
70 static void atk_object_real_get_property (GObject *object,
74 static void atk_object_finalize (GObject *object);
75 static G_CONST_RETURN gchar*
76 atk_object_real_get_name (AtkObject *object);
77 static G_CONST_RETURN gchar*
78 atk_object_real_get_description
80 static AtkObject* atk_object_real_get_parent (AtkObject *object);
81 static AtkRole atk_object_real_get_role (AtkObject *object);
82 static void atk_object_real_set_name (AtkObject *object,
84 static void atk_object_real_set_description
86 const gchar *description);
87 static void atk_object_real_set_parent (AtkObject *object,
89 static void atk_object_real_set_role (AtkObject *object,
91 static guint atk_object_real_connect_property_change_handler
93 AtkPropertyChangeHandler
95 static void atk_object_real_remove_property_change_handler
98 static void atk_object_notify (GObject *obj,
102 static guint atk_object_signals[LAST_SIGNAL] = { 0, };
104 static gpointer parent_class = NULL;
106 static const gchar* atk_object_name_property_name = "accessible-name";
107 static const gchar* atk_object_name_property_state = "accessible-state";
108 static const gchar* atk_object_name_property_description = "accessible-description";
109 static const gchar* atk_object_name_property_child = "accessible-child";
110 static const gchar* atk_object_name_property_parent = "accessible-parent";
111 static const gchar* atk_object_name_property_text = "accessible-text";
112 static const gchar* atk_object_name_property_caret = "accessible-caret";
113 static const gchar* atk_object_name_property_selection = "accessible-selection";
114 static const gchar* atk_object_name_property_value = "accessible-value";
115 static const gchar* atk_object_name_property_visible = "accessible-visible-data";
116 static const gchar* atk_object_name_property_role = "accessible-role";
117 static const gchar* atk_object_name_property_table_caption = "accessible-table-caption";
118 static const gchar* atk_object_name_property_table_column_description = "accessible-table-column-description";
119 static const gchar* atk_object_name_property_table_column_header = "accessible-table-column-header";
120 static const gchar* atk_object_name_property_table_row_description = "accessible-table-row-description";
121 static const gchar* atk_object_name_property_table_row_header = "accessible-table-row-header";
122 static const gchar* atk_object_name_property_table_summary = "accessible-table-summary";
123 static const gchar* atk_object_name_property_model = "accessible-model";
126 atk_object_get_type (void)
128 static GType type = 0;
132 static const GTypeInfo typeInfo =
134 sizeof (AtkObjectClass),
135 (GBaseInitFunc) NULL,
136 (GBaseFinalizeFunc) NULL,
137 (GClassInitFunc) atk_object_class_init,
138 (GClassFinalizeFunc) NULL,
142 (GInstanceInitFunc) atk_object_init,
144 type = g_type_register_static (G_TYPE_OBJECT, "AtkObject", &typeInfo, 0) ;
150 atk_object_class_init (AtkObjectClass *klass)
152 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
154 parent_class = g_type_class_ref (G_TYPE_OBJECT);
156 gobject_class->set_property = atk_object_real_set_property;
157 gobject_class->get_property = atk_object_real_get_property;
158 gobject_class->finalize = atk_object_finalize;
159 gobject_class->notify = atk_object_notify;
161 klass->get_name = atk_object_real_get_name;
162 klass->get_description = atk_object_real_get_description;
163 klass->get_parent = atk_object_real_get_parent;
164 klass->get_n_children = NULL;
165 klass->ref_child = NULL;
166 klass->get_index_in_parent = NULL;
167 klass->ref_relation_set = atk_object_real_ref_relation_set;
168 klass->get_role = atk_object_real_get_role;
169 klass->ref_state_set = NULL;
170 klass->set_name = atk_object_real_set_name;
171 klass->set_description = atk_object_real_set_description;
172 klass->set_parent = atk_object_real_set_parent;
173 klass->set_role = atk_object_real_set_role;
174 klass->connect_property_change_handler =
175 atk_object_real_connect_property_change_handler;
176 klass->remove_property_change_handler =
177 atk_object_real_remove_property_change_handler;
180 * We do not define default signal handlers here
182 klass->children_changed = NULL;
183 klass->focus_event = NULL;
184 klass->property_change = NULL;
186 g_object_class_install_property (gobject_class,
188 g_param_spec_string (atk_object_name_property_name,
190 "Object instance\'s name formatted for "
191 "assistive technology access",
194 g_object_class_install_property (gobject_class,
196 g_param_spec_string (atk_object_name_property_description,
197 "Accessible Description",
198 "Description of an object, formatted for "
199 "assistive technology access",
202 g_object_class_install_property (gobject_class,
204 g_param_spec_int (atk_object_name_property_state,
205 "Accessible State Set",
206 "The accessible state set of this object "
207 "or its UI component",
212 g_object_class_install_property (gobject_class,
214 g_param_spec_object (atk_object_name_property_child,
216 "Is used to notify that a child has been added or removed ",
219 g_object_class_install_property (gobject_class,
221 g_param_spec_object (atk_object_name_property_parent,
223 "Is used to notify that the parent has changed ",
226 g_object_class_install_property (gobject_class,
228 g_param_spec_object (atk_object_name_property_text,
230 "Is used to notify that the text has changed ",
233 g_object_class_install_property (gobject_class,
235 g_param_spec_int (atk_object_name_property_caret,
237 "Is used to notify that the caret position has changed ",
242 g_object_class_install_property (gobject_class,
244 g_param_spec_object (atk_object_name_property_selection,
245 "Accessible Selection",
246 "Is used to notify that the selection has changed ",
249 g_object_class_install_property (gobject_class,
251 g_param_spec_double (atk_object_name_property_value,
253 "Is used to notify that the value has changed ",
258 g_object_class_install_property (gobject_class,
260 g_param_spec_object (atk_object_name_property_visible,
261 "Accessible Visible Data",
262 "Is used to notify that the visual appearance of the object has changed ",
265 g_object_class_install_property (gobject_class,
267 g_param_spec_int (atk_object_name_property_role,
269 "The accessible role this object ",
274 g_object_class_install_property (gobject_class,
276 g_param_spec_object (atk_object_name_property_table_caption,
277 "Accessible Table Caption",
278 "Is used to notify that the table caption has changed ",
281 g_object_class_install_property (gobject_class,
282 PROP_TABLE_COLUMN_HEADER,
283 g_param_spec_object (atk_object_name_property_table_column_header,
284 "Accessible Table Column Header",
285 "Is used to notify that the table column header has changed ",
288 g_object_class_install_property (gobject_class,
289 PROP_TABLE_COLUMN_DESCRIPTION,
290 g_param_spec_int (atk_object_name_property_table_column_description,
291 "Accessible Table Column Description",
292 "Is used to notify that the table columnscription has changed ",
297 g_object_class_install_property (gobject_class,
298 PROP_TABLE_ROW_HEADER,
299 g_param_spec_object (atk_object_name_property_table_row_header,
300 "Accessible Table Row Header",
301 "Is used to notify that the table row header has changed ",
304 g_object_class_install_property (gobject_class,
305 PROP_TABLE_ROW_DESCRIPTION,
306 g_param_spec_int (atk_object_name_property_table_row_description,
307 "Accessible Table Row Description",
308 "Is used to notify that the table row description has changed ",
313 g_object_class_install_property (gobject_class,
315 g_param_spec_object (atk_object_name_property_table_summary,
316 "Accessible Table Summary",
317 "Is used to notify that the table summary has changed ",
320 g_object_class_install_property (gobject_class,
322 g_param_spec_object (atk_object_name_property_model,
324 "Is used to notify that the model for Table or Tree has changed ",
328 * The signal "children_changed" supports two details:
331 atk_object_signals[CHILDREN_CHANGED] =
332 g_signal_new ("children_changed",
333 G_TYPE_FROM_CLASS (klass),
334 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
335 G_STRUCT_OFFSET (AtkObjectClass, children_changed),
337 g_cclosure_marshal_VOID__UINT_POINTER,
339 2, G_TYPE_UINT, G_TYPE_POINTER);
340 atk_object_signals[FOCUS_EVENT] =
341 g_signal_new ("focus_event",
342 G_TYPE_FROM_CLASS (klass),
344 G_STRUCT_OFFSET (AtkObjectClass, focus_event),
346 g_cclosure_marshal_VOID__BOOLEAN,
349 atk_object_signals[PROPERTY_CHANGE] =
350 g_signal_new ("property_change",
351 G_TYPE_FROM_CLASS (klass),
353 G_STRUCT_OFFSET (AtkObjectClass, property_change),
354 (GSignalAccumulator) NULL, NULL,
355 g_cclosure_marshal_VOID__POINTER,
361 atk_object_init (AtkObject *accessible,
362 AtkObjectClass *klass)
364 accessible->name = NULL;
365 accessible->description = NULL;
366 accessible->accessible_parent = NULL;
367 accessible->relation_set = NULL;
368 accessible->role = ATK_ROLE_UNKNOWN;
372 atk_implementor_get_type (void)
374 static GType type = 0;
378 static const GTypeInfo typeInfo =
380 sizeof (AtkImplementorIface),
381 (GBaseInitFunc) NULL,
382 (GBaseFinalizeFunc) NULL,
385 type = g_type_register_static (G_TYPE_INTERFACE, "AtkImplementorIface", &typeInfo, 0) ;
392 * atk_object_get_name:
393 * @accessible: an #AtkObject
395 * Gets the accessible name of the accessible.
397 * Returns: a character string representing the accessible name of the object.
399 G_CONST_RETURN gchar*
400 atk_object_get_name (AtkObject *accessible)
402 AtkObjectClass *klass;
404 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
406 klass = ATK_OBJECT_GET_CLASS (accessible);
408 return (klass->get_name) (accessible);
414 * atk_object_get_description:
415 * @accessible: an #AtkObject
417 * Gets the accessible description of the accessible.
419 * Returns: a character string representing the accessible description
423 G_CONST_RETURN gchar*
424 atk_object_get_description (AtkObject *accessible)
426 AtkObjectClass *klass;
428 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
430 klass = ATK_OBJECT_GET_CLASS (accessible);
431 if (klass->get_description)
432 return (klass->get_description) (accessible);
438 * atk_object_get_parent:
439 * @accessible: an #AtkObject
441 * Gets the accessible parent of the accessible.
443 * Returns: a #AtkObject representing the accessible parent of the accessible
446 atk_object_get_parent (AtkObject *accessible)
448 AtkObjectClass *klass;
450 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
452 klass = ATK_OBJECT_GET_CLASS (accessible);
453 if (klass->get_parent)
454 return (klass->get_parent) (accessible);
460 * atk_object_get_n_accessible_children:
461 * @accessible: an #AtkObject
463 * Gets the number of accessible children of the accessible.
465 * Returns: an integer representing the number of accessible children
469 atk_object_get_n_accessible_children (AtkObject *accessible)
471 AtkObjectClass *klass;
473 g_return_val_if_fail (ATK_IS_OBJECT (accessible), 0);
475 klass = ATK_OBJECT_GET_CLASS (accessible);
476 if (klass->get_n_children)
477 return (klass->get_n_children) (accessible);
483 * atk_object_ref_accessible_child:
484 * @accessible: an #AtkObject
485 * @i: a gint representing the position of the child, starting from 0
487 * Gets a reference to the specified accessible child of the object.
488 * The accessible children are 0-based so the first accessible child is
489 * at index 0, the second at index 1 and so on.
491 * Returns: an #AtkObject representing the specified accessible child
495 atk_object_ref_accessible_child (AtkObject *accessible,
498 AtkObjectClass *klass;
500 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
502 klass = ATK_OBJECT_GET_CLASS (accessible);
503 if (klass->ref_child)
504 return (klass->ref_child) (accessible, i);
510 * atk_object_ref_relation_set:
511 * @accessible: an #AtkObject
513 * Gets the #AtkRelationSet associated with the object.
515 * Returns: an #AtkRelationSet representing the relation set of the object.
518 atk_object_ref_relation_set (AtkObject *accessible)
520 AtkObjectClass *klass;
522 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
524 klass = ATK_OBJECT_GET_CLASS (accessible);
525 if (klass->ref_relation_set)
526 return (klass->ref_relation_set) (accessible);
533 * @name: a character string describing the new role.
535 * Registers the role specified by @name.
537 * Returns: an #AtkRole for the new role.
540 atk_role_register (const gchar *name)
542 /* TODO: associate name with new type */
543 static guint type = ATK_ROLE_LAST_DEFINED;
548 * atk_object_get_role:
549 * @accessible: an #AtkObject
551 * Gets the role of the accessible.
553 * Returns: an #AtkRole which is the role of the accessible
556 atk_object_get_role (AtkObject *accessible) {
557 AtkObjectClass *klass;
559 g_return_val_if_fail (ATK_IS_OBJECT (accessible), ATK_ROLE_UNKNOWN);
561 klass = ATK_OBJECT_GET_CLASS (accessible);
563 return (klass->get_role) (accessible);
565 return ATK_ROLE_UNKNOWN;
569 * atk_object_ref_state_set:
570 * @accessible: an #AtkObject
572 * Gets a reference to the state set of the accessible; the caller must
573 * unreference it when it is no longer needed.
575 * Returns: a reference to an #AtkStateSet which is the state
576 * set of the accessible
579 atk_object_ref_state_set (AtkObject *accessible) {
580 AtkObjectClass *klass;
582 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
584 klass = ATK_OBJECT_GET_CLASS (accessible);
585 if (klass->ref_state_set)
586 return (klass->ref_state_set) (accessible);
592 * atk_object_get_index_in_parent:
593 * @accessible: an #AtkObject
595 * Gets the 0-based index of this accessible in its parent; returns -1 if the
596 * accessible does not have an accessible parent.
598 * Returns: an integer which is the index of the accessible in its parent
601 atk_object_get_index_in_parent (AtkObject *accessible)
603 AtkObjectClass *klass;
605 g_return_val_if_fail (ATK_OBJECT (accessible), -1);
607 klass = ATK_OBJECT_GET_CLASS (accessible);
608 if (klass->get_index_in_parent)
609 return (klass->get_index_in_parent) (accessible);
615 * atk_object_set_name:
616 * @accessible: an #AtkObject
617 * @name: a character string to be set as the accessible name
619 * Sets the accessible name of the accessible.
622 atk_object_set_name (AtkObject *accessible,
625 AtkObjectClass *klass;
627 g_return_if_fail (ATK_IS_OBJECT (accessible));
628 g_return_if_fail (name != NULL);
630 klass = ATK_OBJECT_GET_CLASS (accessible);
633 (klass->set_name) (accessible, name);
634 g_object_notify (G_OBJECT (accessible), atk_object_name_property_name);
639 * atk_object_set_description:
640 * @accessible: an #AtkObject
641 * @description : a character string to be set as the accessible description
643 * Sets the accessible description of the accessible.
646 atk_object_set_description (AtkObject *accessible,
647 const gchar *description)
649 AtkObjectClass *klass;
651 g_return_if_fail (ATK_IS_OBJECT (accessible));
652 g_return_if_fail (description != NULL);
654 klass = ATK_OBJECT_GET_CLASS (accessible);
655 if (klass->set_description)
657 (klass->set_description) (accessible, description);
658 g_object_notify (G_OBJECT (accessible), atk_object_name_property_description);
663 * atk_object_set_parent:
664 * @accessible: an #AtkObject
665 * @parent : an #AtkObject to be set as the accessible parent
667 * Sets the accessible parent of the accessible.
670 atk_object_set_parent (AtkObject *accessible,
673 AtkObjectClass *klass;
675 g_return_if_fail (ATK_IS_OBJECT (accessible));
677 klass = ATK_OBJECT_GET_CLASS (accessible);
678 if (klass->set_parent)
679 (klass->set_parent) (accessible, parent);
683 * atk_object_set_role:
684 * @accessible: an #AtkObject
685 * @role : an #AtkRole to be set as the role
687 * Sets the role of the accessible.
690 atk_object_set_role (AtkObject *accessible,
693 AtkObjectClass *klass;
695 g_return_if_fail (ATK_IS_OBJECT (accessible));
697 klass = ATK_OBJECT_GET_CLASS (accessible);
699 (klass->set_role) (accessible, role);
703 * atk_object_connect_property_change_handler:
704 * @accessible: an #AtkObject
705 * @handler : a function to be called when a property changes its value
707 * Specifies a function to be called when a property changes value.
709 * Returns: a #guint which is the handler id used in
710 * atk_object_remove_property_change_handler()
713 atk_object_connect_property_change_handler (AtkObject *accessible,
714 AtkPropertyChangeHandler *handler)
716 AtkObjectClass *klass;
718 g_return_val_if_fail (ATK_IS_OBJECT (accessible), 0);
719 g_return_val_if_fail ((handler != NULL), 0);
721 klass = ATK_OBJECT_GET_CLASS (accessible);
722 if (klass->connect_property_change_handler)
723 return (klass->connect_property_change_handler) (accessible, handler);
729 * atk_object_remove_property_change_handler:
730 * @accessible: an #AtkObject
731 * @handler_id : a guint which identifies the handler to be removed.
733 * Removes a property change handler.
736 atk_object_remove_property_change_handler (AtkObject *accessible,
739 AtkObjectClass *klass;
741 g_return_if_fail (ATK_IS_OBJECT (accessible));
743 klass = ATK_OBJECT_GET_CLASS (accessible);
744 if (klass->remove_property_change_handler)
745 (klass->remove_property_change_handler) (accessible, handler_id);
749 * atk_implementor_ref_accessible:
750 * @implementor: The #GObject instance which should implement #AtkImplementorIface
751 * if a non-null return value is required.
753 * Gets a reference to an object's #AtkObject implementation, if
754 * the object implements #AtkObjectIface
756 * Returns: a reference to an object's #AtkObject implementation
759 atk_implementor_ref_accessible (AtkImplementor *object)
761 AtkImplementorIface *iface;
762 AtkObject *accessible = NULL;
764 g_return_val_if_fail (ATK_IS_IMPLEMENTOR (object), NULL);
766 iface = ATK_IMPLEMENTOR_GET_IFACE (object);
769 accessible = iface->ref_accessible (object);
771 g_return_val_if_fail ((accessible != NULL), NULL);
776 static AtkRelationSet*
777 atk_object_real_ref_relation_set (AtkObject *accessible)
779 if (accessible->relation_set)
780 g_object_ref (accessible->relation_set);
782 return accessible->relation_set;
786 atk_object_real_set_property (GObject *object,
791 AtkObject *accessible;
793 accessible = ATK_OBJECT (object);
798 atk_object_set_name (accessible, g_value_get_string (value));
800 case PROP_DESCRIPTION:
801 atk_object_set_description (accessible, g_value_get_string (value));
804 g_print ("This interface does not support setting the state set of an accessible object\n");
807 if (ATK_IS_VALUE (accessible))
808 atk_value_set_current_value (ATK_VALUE (accessible), value);
816 atk_object_real_get_property (GObject *object,
821 AtkObject *accessible;
823 accessible = ATK_OBJECT (object);
828 g_value_set_string (value, atk_object_get_name (accessible));
830 case PROP_DESCRIPTION:
831 g_value_set_string (value, atk_object_get_description (accessible));
834 if (ATK_IS_VALUE (accessible))
835 atk_value_get_current_value (ATK_VALUE (accessible), value);
843 atk_object_finalize (GObject *object)
845 AtkObject *accessible;
847 g_return_if_fail (ATK_IS_OBJECT (object));
849 accessible = ATK_OBJECT (object);
851 g_free (accessible->name);
852 g_free (accessible->description);
855 * Free memory allocated for relation set if it have been allocated.
857 if (accessible->relation_set)
859 g_object_unref (accessible->relation_set);
862 G_OBJECT_CLASS (parent_class)->finalize (object);
865 static G_CONST_RETURN gchar*
866 atk_object_real_get_name (AtkObject *object)
871 static G_CONST_RETURN gchar*
872 atk_object_real_get_description (AtkObject *object)
874 return object->description;
878 atk_object_real_get_parent (AtkObject *object)
880 return object->accessible_parent;
884 atk_object_real_get_role (AtkObject *object)
890 atk_object_real_set_name (AtkObject *object,
893 g_free (object->name);
894 object->name = g_strdup (name);
898 atk_object_real_set_description (AtkObject *object,
899 const gchar *description)
901 g_free (object->description);
902 object->description = g_strdup (description);
906 atk_object_real_set_parent (AtkObject *object,
909 object->accessible_parent = parent;
914 atk_object_real_set_role (AtkObject *object,
921 atk_object_real_connect_property_change_handler (AtkObject *obj,
922 AtkPropertyChangeHandler *handler)
924 return g_signal_connect_closure_by_id (obj,
925 atk_object_signals[PROPERTY_CHANGE],
928 G_CALLBACK (handler), NULL,
929 (GClosureNotify) NULL),
934 atk_object_real_remove_property_change_handler (AtkObject *obj,
937 g_signal_handler_disconnect (obj, handler_id);
941 * This function is a signal handler for notify signal which gets emitted
942 * when a property changes value.
944 * It constructs an AtkPropertyValues structure and emits a "property_changed"
945 * signal which causes the user specified AtkPropertyChangeHandler
949 atk_object_notify (GObject *obj,
952 AtkPropertyValues values;
954 memset (&values.old_value, 0, sizeof (GValue));
955 memset (&values.new_value, 0, sizeof (GValue));
956 g_value_init (&values.new_value, pspec->value_type);
957 g_object_get_property(obj, pspec->name, &values.new_value);
958 values.property_name = pspec->name;
959 g_signal_emit (obj, atk_object_signals[PROPERTY_CHANGE], 0,