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.
23 #include <glib-object.h>
29 #undef FOCUS_EVENT /* <windows.h> pollutes the namespace
30 * like a six hundred pound gorilla */
34 #include "atkmarshal.h"
39 * @Short_description: The base object class for the Accessibility Toolkit API.
42 * This class is the primary class for accessibility support via the
43 * Accessibility ToolKit (ATK). Objects which are instances of
44 * #AtkObject (or instances of AtkObject-derived types) are queried
45 * for properties which relate basic (and generic) properties of a UI
46 * component such as name and description. Instances of #AtkObject
47 * may also be queried as to whether they implement other ATK
48 * interfaces (e.g. #AtkAction, #AtkComponent, etc.), as appropriate
49 * to the role which a given UI component plays in a user interface.
51 * All UI components in an application which provide useful
52 * information or services to the user must provide corresponding
53 * #AtkObject instances on request (in GTK+, for instance, usually on
54 * a call to #gtk_widget_get_accessible ()), either via ATK support
55 * built into the toolkit for the widget class or ancestor class, or
56 * in the case of custom widgets, if the inherited #AtkObject
57 * implementation is insufficient, via instances of a new #AtkObject
60 * See also: #AtkObjectFactory, #AtkRegistry. (GTK+ users see also
65 static GPtrArray *role_names = NULL;
69 PROP_0, /* gobject convention */
73 PROP_PARENT, /* ancestry has changed */
79 PROP_TABLE_COLUMN_DESCRIPTION,
80 PROP_TABLE_COLUMN_HEADER,
81 PROP_TABLE_ROW_DESCRIPTION,
82 PROP_TABLE_ROW_HEADER,
84 PROP_TABLE_CAPTION_OBJECT,
85 PROP_HYPERTEXT_NUM_LINKS,
86 PROP_LAST /* gobject convention */
95 ACTIVE_DESCENDANT_CHANGED,
100 /* These are listed here for extraction by intltool */
103 N_("accelerator label")
110 N_("check menu item")
123 /* I know it looks wrong but that is what Java returns */
147 N_("radio menu item")
159 N_("table column header")
160 N_("table row header")
161 N_("tear off menu item")
179 N_("embedded component")
187 N_("redundant object")
190 N_("input method window")
193 N_("document spreadsheet")
194 N_("document presentation")
217 N_("description list")
218 N_("description term")
219 N_("description value")
222 static void atk_object_class_init (AtkObjectClass *klass);
223 static void atk_object_init (AtkObject *accessible,
224 AtkObjectClass *klass);
225 static AtkRelationSet* atk_object_real_ref_relation_set
226 (AtkObject *accessible);
227 static void atk_object_real_initialize (AtkObject *accessible,
229 static void atk_object_real_set_property (GObject *object,
233 static void atk_object_real_get_property (GObject *object,
237 static void atk_object_finalize (GObject *object);
238 static const gchar* atk_object_real_get_name (AtkObject *object);
239 static const gchar* atk_object_real_get_description
241 static AtkObject* atk_object_real_get_parent (AtkObject *object);
242 static AtkRole atk_object_real_get_role (AtkObject *object);
243 static AtkLayer atk_object_real_get_layer (AtkObject *object);
244 static AtkStateSet* atk_object_real_ref_state_set
246 static void atk_object_real_set_name (AtkObject *object,
248 static void atk_object_real_set_description
250 const gchar *description);
251 static void atk_object_real_set_parent (AtkObject *object,
253 static void atk_object_real_set_role (AtkObject *object,
255 static void atk_object_notify (GObject *obj,
257 static const gchar* atk_object_real_get_object_locale
260 static guint atk_object_signals[LAST_SIGNAL] = { 0, };
262 static gpointer parent_class = NULL;
264 static const gchar* const atk_object_name_property_name = "accessible-name";
265 static const gchar* const atk_object_name_property_description = "accessible-description";
266 static const gchar* const atk_object_name_property_parent = "accessible-parent";
267 static const gchar* const atk_object_name_property_value = "accessible-value";
268 static const gchar* const atk_object_name_property_role = "accessible-role";
269 static const gchar* const atk_object_name_property_component_layer = "accessible-component-layer";
270 static const gchar* const atk_object_name_property_component_mdi_zorder = "accessible-component-mdi-zorder";
271 static const gchar* const atk_object_name_property_table_caption = "accessible-table-caption";
272 static const gchar* const atk_object_name_property_table_column_description = "accessible-table-column-description";
273 static const gchar* const atk_object_name_property_table_column_header = "accessible-table-column-header";
274 static const gchar* const atk_object_name_property_table_row_description = "accessible-table-row-description";
275 static const gchar* const atk_object_name_property_table_row_header = "accessible-table-row-header";
276 static const gchar* const atk_object_name_property_table_summary = "accessible-table-summary";
277 static const gchar* const atk_object_name_property_table_caption_object = "accessible-table-caption-object";
278 static const gchar* const atk_object_name_property_hypertext_num_links = "accessible-hypertext-nlinks";
282 static HMODULE atk_dll;
285 DllMain (HINSTANCE hinstDLL,
291 case DLL_PROCESS_ATTACH:
292 atk_dll = (HMODULE) hinstDLL;
300 get_atk_locale_dir (void)
302 static gchar *atk_localedir = NULL;
309 /* ATK_LOCALEDIR might end in either /lib/locale or
310 * /share/locale. Scan for that slash.
312 p = ATK_LOCALEDIR + strlen (ATK_LOCALEDIR);
318 root = g_win32_get_package_installation_directory_of_module (atk_dll);
319 temp = g_build_filename (root, p, NULL);
322 /* atk_localedir is passed to bindtextdomain() which isn't
325 atk_localedir = g_win32_locale_filename_from_utf8 (temp);
328 return atk_localedir;
333 #define ATK_LOCALEDIR get_atk_locale_dir()
338 gettext_initialization (void)
341 static gboolean gettext_initialized = FALSE;
343 if (!gettext_initialized)
345 const char *dir = g_getenv ("ATK_ALT_LOCALEDIR");
347 gettext_initialized = TRUE;
351 bindtextdomain (GETTEXT_PACKAGE, dir);
352 #ifdef HAVE_BIND_TEXTDOMAIN_CODESET
353 bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8");
360 compact_role_name (gchar *role_name)
362 gchar *p = role_name;
373 initialize_role_names ()
375 GTypeClass *enum_class;
376 GEnumValue *enum_value;
378 gchar *role_name = NULL;
383 role_names = g_ptr_array_new ();
384 enum_class = g_type_class_ref (ATK_TYPE_ROLE);
385 if (!G_IS_ENUM_CLASS(enum_class))
388 for (i = 0; i < ATK_ROLE_LAST_DEFINED; i++)
390 enum_value = g_enum_get_value (G_ENUM_CLASS (enum_class), i);
391 role_name = g_strdup (enum_value->value_nick);
392 // We want the role names to be in the format "check button" and not "check-button"
393 compact_role_name (role_name);
394 g_ptr_array_add (role_names, role_name);
397 g_type_class_unref (enum_class);
402 atk_object_get_type (void)
404 static GType type = 0;
408 static const GTypeInfo typeInfo =
410 sizeof (AtkObjectClass),
411 (GBaseInitFunc) NULL,
412 (GBaseFinalizeFunc) NULL,
413 (GClassInitFunc) atk_object_class_init,
414 (GClassFinalizeFunc) NULL,
418 (GInstanceInitFunc) atk_object_init,
420 type = g_type_register_static (G_TYPE_OBJECT, "AtkObject", &typeInfo, 0) ;
426 atk_object_class_init (AtkObjectClass *klass)
428 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
430 parent_class = g_type_class_peek_parent (klass);
432 gobject_class->set_property = atk_object_real_set_property;
433 gobject_class->get_property = atk_object_real_get_property;
434 gobject_class->finalize = atk_object_finalize;
435 gobject_class->notify = atk_object_notify;
437 klass->get_name = atk_object_real_get_name;
438 klass->get_description = atk_object_real_get_description;
439 klass->get_parent = atk_object_real_get_parent;
440 klass->get_n_children = NULL;
441 klass->ref_child = NULL;
442 klass->get_index_in_parent = NULL;
443 klass->ref_relation_set = atk_object_real_ref_relation_set;
444 klass->get_role = atk_object_real_get_role;
445 klass->get_layer = atk_object_real_get_layer;
446 klass->get_mdi_zorder = NULL;
447 klass->initialize = atk_object_real_initialize;
448 klass->ref_state_set = atk_object_real_ref_state_set;
449 klass->set_name = atk_object_real_set_name;
450 klass->set_description = atk_object_real_set_description;
451 klass->set_parent = atk_object_real_set_parent;
452 klass->set_role = atk_object_real_set_role;
453 klass->get_object_locale = atk_object_real_get_object_locale;
456 * We do not define default signal handlers here
458 klass->children_changed = NULL;
459 klass->focus_event = NULL;
460 klass->property_change = NULL;
461 klass->visible_data_changed = NULL;
462 klass->active_descendant_changed = NULL;
464 gettext_initialization ();
466 g_object_class_install_property (gobject_class,
468 g_param_spec_string (atk_object_name_property_name,
469 _("Accessible Name"),
470 _("Object instance\'s name formatted for assistive technology access"),
473 g_object_class_install_property (gobject_class,
475 g_param_spec_string (atk_object_name_property_description,
476 _("Accessible Description"),
477 _("Description of an object, formatted for assistive technology access"),
480 g_object_class_install_property (gobject_class,
482 g_param_spec_object (atk_object_name_property_parent,
483 _("Accessible Parent"),
484 _("Parent of the current accessible as returned by atk_object_get_parent()"),
487 g_object_class_install_property (gobject_class,
489 g_param_spec_double (atk_object_name_property_value,
490 _("Accessible Value"),
491 _("Is used to notify that the value has changed"),
496 g_object_class_install_property (gobject_class,
498 g_param_spec_int (atk_object_name_property_role,
499 _("Accessible Role"),
500 _("The accessible role of this object"),
505 g_object_class_install_property (gobject_class,
507 g_param_spec_int (atk_object_name_property_component_layer,
508 _("Accessible Layer"),
509 _("The accessible layer of this object"),
514 g_object_class_install_property (gobject_class,
516 g_param_spec_int (atk_object_name_property_component_mdi_zorder,
517 _("Accessible MDI Value"),
518 _("The accessible MDI value of this object"),
523 g_object_class_install_property (gobject_class,
525 g_param_spec_string (atk_object_name_property_table_caption,
526 _("Accessible Table Caption"),
527 _("Is used to notify that the table caption has changed; this property should not be used. accessible-table-caption-object should be used instead"),
530 g_object_class_install_property (gobject_class,
531 PROP_TABLE_COLUMN_HEADER,
532 g_param_spec_object (atk_object_name_property_table_column_header,
533 _("Accessible Table Column Header"),
534 _("Is used to notify that the table column header has changed"),
537 g_object_class_install_property (gobject_class,
538 PROP_TABLE_COLUMN_DESCRIPTION,
539 g_param_spec_string (atk_object_name_property_table_column_description,
540 _("Accessible Table Column Description"),
541 _("Is used to notify that the table column description has changed"),
544 g_object_class_install_property (gobject_class,
545 PROP_TABLE_ROW_HEADER,
546 g_param_spec_object (atk_object_name_property_table_row_header,
547 _("Accessible Table Row Header"),
548 _("Is used to notify that the table row header has changed"),
551 g_object_class_install_property (gobject_class,
552 PROP_TABLE_ROW_DESCRIPTION,
553 g_param_spec_string (atk_object_name_property_table_row_description,
554 _("Accessible Table Row Description"),
555 _("Is used to notify that the table row description has changed"),
558 g_object_class_install_property (gobject_class,
560 g_param_spec_object (atk_object_name_property_table_summary,
561 _("Accessible Table Summary"),
562 _("Is used to notify that the table summary has changed"),
565 g_object_class_install_property (gobject_class,
566 PROP_TABLE_CAPTION_OBJECT,
567 g_param_spec_object (atk_object_name_property_table_caption_object,
568 _("Accessible Table Caption Object"),
569 _("Is used to notify that the table caption has changed"),
572 g_object_class_install_property (gobject_class,
573 PROP_HYPERTEXT_NUM_LINKS,
574 g_param_spec_int (atk_object_name_property_hypertext_num_links,
575 _("Number of Accessible Hypertext Links"),
576 _("The number of links which the current AtkHypertext has"),
583 * AtkObject::children-changed:
584 * @atkobject: the object which received the signal.
585 * @arg1: The index of the added or removed child. The value can be
586 * -1. This is used if the value is not known by the implementor
587 * when the child is added/removed or irrelevant.
588 * @arg2: A gpointer to the child AtkObject which was added or
589 * removed. If the child was removed, it is possible that it is not
590 * available for the implementor. In that case this pointer can be
593 * The signal "children-changed" is emitted when a child is added or
594 * removed form an object. It supports two details: "add" and
597 atk_object_signals[CHILDREN_CHANGED] =
598 g_signal_new ("children_changed",
599 G_TYPE_FROM_CLASS (klass),
600 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
601 G_STRUCT_OFFSET (AtkObjectClass, children_changed),
603 g_cclosure_marshal_VOID__UINT_POINTER,
605 2, G_TYPE_UINT, G_TYPE_POINTER);
608 * AtkObject::focus-event:
609 * @atkobject: the object which received the signal
610 * @arg1: a boolean value which indicates whether the object gained
613 * The signal "focus-event" is emitted when an object gained or lost
616 * Deprecated: Since 2.9.4. Use #AtkObject::state-change signal instead.
618 atk_object_signals[FOCUS_EVENT] =
619 g_signal_new ("focus_event",
620 G_TYPE_FROM_CLASS (klass),
622 G_STRUCT_OFFSET (AtkObjectClass, focus_event),
624 g_cclosure_marshal_VOID__BOOLEAN,
628 * AtkObject::property-change:
629 * @atkobject: the object which received the signal.
630 * @arg1: an #AtkPropertyValues containing the new value of the
631 * property which changed.
633 * The signal "property-change" is emitted when an object's property
634 * value changes. @arg1 contains an #AtkPropertyValues with the name
635 * and the new value of the property whose value has changed. Note
636 * that, as with GObject notify, getting this signal does not
637 * guarantee that the value of the property has actually changed; it
638 * may also be emitted when the setter of the property is called to
639 * reinstate the previous value.
641 * Toolkit implementor note: ATK implementors should use
642 * g_object_notify() to emit property-changed
643 * notifications. #AtkObject::property-changed is needed by the
644 * implementation of atk_add_global_event_listener() because GObject
645 * notify doesn't support emission hooks.
647 atk_object_signals[PROPERTY_CHANGE] =
648 g_signal_new ("property_change",
649 G_TYPE_FROM_CLASS (klass),
650 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
651 G_STRUCT_OFFSET (AtkObjectClass, property_change),
652 (GSignalAccumulator) NULL, NULL,
653 g_cclosure_marshal_VOID__POINTER,
658 * AtkObject::state-change:
659 * @atkobject: the object which received the signal.
660 * @arg1: The name of the state which has changed
661 * @arg2: A boolean which indicates whether the state has been set or unset.
663 * The "state-change" signal is emitted when an object's state
664 * changes. The detail value identifies the state type which has
667 atk_object_signals[STATE_CHANGE] =
668 g_signal_new ("state_change",
669 G_TYPE_FROM_CLASS (klass),
670 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
671 G_STRUCT_OFFSET (AtkObjectClass, state_change),
672 (GSignalAccumulator) NULL, NULL,
673 atk_marshal_VOID__STRING_BOOLEAN,
679 * AtkObject::visible-data-changed:
680 * @atkobject: the object which received the signal.
682 * The "visible-data-changed" signal is emitted when the visual
683 * appearance of the object changed.
685 atk_object_signals[VISIBLE_DATA_CHANGED] =
686 g_signal_new ("visible_data_changed",
687 G_TYPE_FROM_CLASS (klass),
689 G_STRUCT_OFFSET (AtkObjectClass, visible_data_changed),
690 (GSignalAccumulator) NULL, NULL,
691 g_cclosure_marshal_VOID__VOID,
695 * AtkObject::active-descendant-changed:
696 * @atkobject: the object which received the signal.
697 * @arg1: the newly focused object.
699 * The "active-descendant-changed" signal is emitted by an object
700 * which has the state ATK_STATE_MANAGES_DESCENDANTS when the focus
701 * object in the object changes. For instance, a table will emit the
702 * signal when the cell in the table which has focus changes.
704 atk_object_signals[ACTIVE_DESCENDANT_CHANGED] =
705 g_signal_new ("active_descendant_changed",
706 G_TYPE_FROM_CLASS (klass),
707 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
708 G_STRUCT_OFFSET (AtkObjectClass, active_descendant_changed),
710 g_cclosure_marshal_VOID__POINTER,
716 atk_object_init (AtkObject *accessible,
717 AtkObjectClass *klass)
719 accessible->name = NULL;
720 accessible->description = NULL;
721 accessible->accessible_parent = NULL;
722 accessible->relation_set = atk_relation_set_new();
723 accessible->role = ATK_ROLE_UNKNOWN;
727 atk_implementor_get_type (void)
729 static GType type = 0;
733 static const GTypeInfo typeInfo =
735 sizeof (AtkImplementorIface),
736 (GBaseInitFunc) NULL,
737 (GBaseFinalizeFunc) NULL,
740 type = g_type_register_static (G_TYPE_INTERFACE, "AtkImplementorIface", &typeInfo, 0) ;
747 * atk_object_get_name:
748 * @accessible: an #AtkObject
750 * Gets the accessible name of the accessible.
752 * Returns: a character string representing the accessible name of the object.
755 atk_object_get_name (AtkObject *accessible)
757 AtkObjectClass *klass;
759 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
761 klass = ATK_OBJECT_GET_CLASS (accessible);
763 return (klass->get_name) (accessible);
769 * atk_object_get_description:
770 * @accessible: an #AtkObject
772 * Gets the accessible description of the accessible.
774 * Returns: a character string representing the accessible description
779 atk_object_get_description (AtkObject *accessible)
781 AtkObjectClass *klass;
783 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
785 klass = ATK_OBJECT_GET_CLASS (accessible);
786 if (klass->get_description)
787 return (klass->get_description) (accessible);
793 * atk_object_get_parent:
794 * @accessible: an #AtkObject
796 * Gets the accessible parent of the accessible. By default this is
797 * the one assigned with atk_object_set_parent(), but it is assumed
798 * that ATK implementors have ways to get the parent of the object
799 * without the need of assigning it manually with
800 * atk_object_set_parent(), and will return it with this method.
802 * If you are only interested on the parent assigned with
803 * atk_object_set_parent(), use atk_object_peek_parent().
805 * Returns: (transfer none): an #AtkObject representing the accessible
806 * parent of the accessible
809 atk_object_get_parent (AtkObject *accessible)
811 AtkObjectClass *klass;
813 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
815 klass = ATK_OBJECT_GET_CLASS (accessible);
816 if (klass->get_parent)
817 return (klass->get_parent) (accessible);
823 * atk_object_peek_parent:
824 * @accessible: an #AtkObject
826 * Gets the accessible parent of the accessible, if it has been
827 * manually assigned with atk_object_set_parent. Otherwise, this
828 * function returns %NULL.
830 * This method is intended as an utility for ATK implementors, and not
831 * to be exposed to accessible tools. See atk_object_get_parent() for
834 * Returns: (transfer none): an #AtkObject representing the accessible
835 * parent of the accessible if assigned
838 atk_object_peek_parent (AtkObject *accessible)
840 return accessible->accessible_parent;
844 * atk_object_get_n_accessible_children:
845 * @accessible: an #AtkObject
847 * Gets the number of accessible children of the accessible.
849 * Returns: an integer representing the number of accessible children
853 atk_object_get_n_accessible_children (AtkObject *accessible)
855 AtkObjectClass *klass;
857 g_return_val_if_fail (ATK_IS_OBJECT (accessible), 0);
859 klass = ATK_OBJECT_GET_CLASS (accessible);
860 if (klass->get_n_children)
861 return (klass->get_n_children) (accessible);
867 * atk_object_ref_accessible_child:
868 * @accessible: an #AtkObject
869 * @i: a gint representing the position of the child, starting from 0
871 * Gets a reference to the specified accessible child of the object.
872 * The accessible children are 0-based so the first accessible child is
873 * at index 0, the second at index 1 and so on.
875 * Returns: (transfer full): an #AtkObject representing the specified
876 * accessible child of the accessible.
879 atk_object_ref_accessible_child (AtkObject *accessible,
882 AtkObjectClass *klass;
884 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
886 klass = ATK_OBJECT_GET_CLASS (accessible);
887 if (klass->ref_child)
888 return (klass->ref_child) (accessible, i);
894 * atk_object_ref_relation_set:
895 * @accessible: an #AtkObject
897 * Gets the #AtkRelationSet associated with the object.
899 * Returns: (transfer full): an #AtkRelationSet representing the relation set
903 atk_object_ref_relation_set (AtkObject *accessible)
905 AtkObjectClass *klass;
907 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
909 klass = ATK_OBJECT_GET_CLASS (accessible);
910 if (klass->ref_relation_set)
911 return (klass->ref_relation_set) (accessible);
918 * @name: a character string describing the new role.
920 * Registers the role specified by @name. @name must be a meaningful
921 * name. So it should not be empty, or consisting on whitespaces.
923 * Deprecated: Since 2.12. If your application/toolkit doesn't find a
924 * suitable role for a specific object defined at #AtkRole, please
925 * submit a bug in order to add a new role to the specification.
927 * Returns: an #AtkRole for the new role if added
928 * properly. ATK_ROLE_INVALID in case of error.
931 atk_role_register (const gchar *name)
933 gboolean valid = FALSE;
935 glong length = g_utf8_strlen (name, -1);
937 for (i=0; i < length; i++) {
945 return ATK_ROLE_INVALID;
948 initialize_role_names ();
950 g_ptr_array_add (role_names, g_strdup (name));
951 return role_names->len - 1;
955 * atk_object_get_role:
956 * @accessible: an #AtkObject
958 * Gets the role of the accessible.
960 * Returns: an #AtkRole which is the role of the accessible
963 atk_object_get_role (AtkObject *accessible)
965 AtkObjectClass *klass;
967 g_return_val_if_fail (ATK_IS_OBJECT (accessible), ATK_ROLE_UNKNOWN);
969 klass = ATK_OBJECT_GET_CLASS (accessible);
971 return (klass->get_role) (accessible);
973 return ATK_ROLE_UNKNOWN;
977 * atk_object_get_layer:
978 * @accessible: an #AtkObject
980 * Gets the layer of the accessible.
982 * Deprecated: Use atk_component_get_layer instead.
984 * Returns: an #AtkLayer which is the layer of the accessible
987 atk_object_get_layer (AtkObject *accessible)
989 AtkObjectClass *klass;
991 g_return_val_if_fail (ATK_IS_OBJECT (accessible), ATK_LAYER_INVALID);
993 klass = ATK_OBJECT_GET_CLASS (accessible);
994 if (klass->get_layer)
995 return (klass->get_layer) (accessible);
997 return ATK_LAYER_INVALID;
1001 * atk_object_get_mdi_zorder:
1002 * @accessible: an #AtkObject
1004 * Gets the zorder of the accessible. The value G_MININT will be returned
1005 * if the layer of the accessible is not ATK_LAYER_MDI.
1007 * Deprecated: Use atk_component_get_mdi_zorder instead.
1009 * Returns: a gint which is the zorder of the accessible, i.e. the depth at
1010 * which the component is shown in relation to other components in the same
1015 atk_object_get_mdi_zorder (AtkObject *accessible)
1017 AtkObjectClass *klass;
1019 g_return_val_if_fail (ATK_IS_OBJECT (accessible), G_MININT);
1021 klass = ATK_OBJECT_GET_CLASS (accessible);
1022 if (klass->get_mdi_zorder)
1023 return (klass->get_mdi_zorder) (accessible);
1029 * atk_object_ref_state_set:
1030 * @accessible: an #AtkObject
1032 * Gets a reference to the state set of the accessible; the caller must
1033 * unreference it when it is no longer needed.
1035 * Returns: (transfer full): a reference to an #AtkStateSet which is the state
1036 * set of the accessible
1039 atk_object_ref_state_set (AtkObject *accessible)
1041 AtkObjectClass *klass;
1043 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
1045 klass = ATK_OBJECT_GET_CLASS (accessible);
1046 if (klass->ref_state_set)
1047 return (klass->ref_state_set) (accessible);
1053 * atk_object_get_index_in_parent:
1054 * @accessible: an #AtkObject
1056 * Gets the 0-based index of this accessible in its parent; returns -1 if the
1057 * accessible does not have an accessible parent.
1059 * Returns: an integer which is the index of the accessible in its parent
1062 atk_object_get_index_in_parent (AtkObject *accessible)
1064 AtkObjectClass *klass;
1066 g_return_val_if_fail (ATK_OBJECT (accessible), -1);
1068 klass = ATK_OBJECT_GET_CLASS (accessible);
1069 if (klass->get_index_in_parent)
1070 return (klass->get_index_in_parent) (accessible);
1076 * atk_object_set_name:
1077 * @accessible: an #AtkObject
1078 * @name: a character string to be set as the accessible name
1080 * Sets the accessible name of the accessible. You can't set the name
1081 * to NULL. This is reserved for the initial value. In this aspect
1082 * NULL is similar to ATK_ROLE_UNKNOWN. If you want to set the name to
1083 * a empty value you can use "".
1086 atk_object_set_name (AtkObject *accessible,
1089 AtkObjectClass *klass;
1090 gboolean notify = FALSE;
1092 g_return_if_fail (ATK_IS_OBJECT (accessible));
1093 g_return_if_fail (name != NULL);
1095 klass = ATK_OBJECT_GET_CLASS (accessible);
1096 if (klass->set_name)
1098 /* Do not notify for initial name setting. See bug 665870 */
1099 notify = (accessible->name != NULL);
1101 (klass->set_name) (accessible, name);
1103 g_object_notify (G_OBJECT (accessible), atk_object_name_property_name);
1108 * atk_object_set_description:
1109 * @accessible: an #AtkObject
1110 * @description: a character string to be set as the accessible description
1112 * Sets the accessible description of the accessible. You can't set
1113 * the description to NULL. This is reserved for the initial value. In
1114 * this aspect NULL is similar to ATK_ROLE_UNKNOWN. If you want to set
1115 * the name to a empty value you can use "".
1118 atk_object_set_description (AtkObject *accessible,
1119 const gchar *description)
1121 AtkObjectClass *klass;
1122 gboolean notify = FALSE;
1124 g_return_if_fail (ATK_IS_OBJECT (accessible));
1125 g_return_if_fail (description != NULL);
1127 klass = ATK_OBJECT_GET_CLASS (accessible);
1128 if (klass->set_description)
1130 /* Do not notify for initial name setting. See bug 665870 */
1131 notify = (accessible->description != NULL);
1133 (klass->set_description) (accessible, description);
1135 g_object_notify (G_OBJECT (accessible),
1136 atk_object_name_property_description);
1141 * atk_object_set_parent:
1142 * @accessible: an #AtkObject
1143 * @parent: an #AtkObject to be set as the accessible parent
1145 * Sets the accessible parent of the accessible. @parent can be NULL.
1148 atk_object_set_parent (AtkObject *accessible,
1151 AtkObjectClass *klass;
1153 g_return_if_fail (ATK_IS_OBJECT (accessible));
1155 klass = ATK_OBJECT_GET_CLASS (accessible);
1156 if (klass->set_parent)
1158 (klass->set_parent) (accessible, parent);
1159 g_object_notify (G_OBJECT (accessible), atk_object_name_property_parent);
1164 * atk_object_set_role:
1165 * @accessible: an #AtkObject
1166 * @role: an #AtkRole to be set as the role
1168 * Sets the role of the accessible.
1171 atk_object_set_role (AtkObject *accessible,
1174 AtkObjectClass *klass;
1177 g_return_if_fail (ATK_IS_OBJECT (accessible));
1179 klass = ATK_OBJECT_GET_CLASS (accessible);
1180 if (klass->set_role)
1182 old_role = atk_object_get_role (accessible);
1183 if (old_role != role)
1185 (klass->set_role) (accessible, role);
1186 if (old_role != ATK_ROLE_UNKNOWN)
1187 /* Do not notify for initial role setting */
1188 g_object_notify (G_OBJECT (accessible), atk_object_name_property_role);
1194 * atk_object_connect_property_change_handler:
1195 * @accessible: an #AtkObject
1196 * @handler: a function to be called when a property changes its value
1198 * Deprecated: Since 2.12. Connect directly to property-change or
1201 * Returns: a #guint which is the handler id used in
1202 * atk_object_remove_property_change_handler()
1205 atk_object_connect_property_change_handler (AtkObject *accessible,
1206 AtkPropertyChangeHandler *handler)
1208 AtkObjectClass *klass;
1210 g_return_val_if_fail (ATK_IS_OBJECT (accessible), 0);
1211 g_return_val_if_fail ((handler != NULL), 0);
1213 klass = ATK_OBJECT_GET_CLASS (accessible);
1214 if (klass->connect_property_change_handler)
1215 return (klass->connect_property_change_handler) (accessible, handler);
1221 * atk_object_remove_property_change_handler:
1222 * @accessible: an #AtkObject
1223 * @handler_id: a guint which identifies the handler to be removed.
1225 * Deprecated: Since 2.12.
1227 * Removes a property change handler.
1230 atk_object_remove_property_change_handler (AtkObject *accessible,
1233 AtkObjectClass *klass;
1235 g_return_if_fail (ATK_IS_OBJECT (accessible));
1237 klass = ATK_OBJECT_GET_CLASS (accessible);
1238 if (klass->remove_property_change_handler)
1239 (klass->remove_property_change_handler) (accessible, handler_id);
1243 * atk_object_notify_state_change:
1244 * @accessible: an #AtkObject
1245 * @state: an #AtkState whose state is changed
1246 * @value: a gboolean which indicates whether the state is being set on or off
1248 * Emits a state-change signal for the specified state.
1251 atk_object_notify_state_change (AtkObject *accessible,
1257 g_return_if_fail (ATK_IS_OBJECT (accessible));
1259 name = atk_state_type_get_name (state);
1260 g_signal_emit (accessible, atk_object_signals[STATE_CHANGE],
1261 g_quark_from_string (name),
1266 * atk_implementor_ref_accessible:
1267 * @implementor: The #GObject instance which should implement #AtkImplementorIface
1268 * if a non-null return value is required.
1270 * Gets a reference to an object's #AtkObject implementation, if
1271 * the object implements #AtkObjectIface
1273 * Returns: (transfer full): a reference to an object's #AtkObject
1277 atk_implementor_ref_accessible (AtkImplementor *implementor)
1279 AtkImplementorIface *iface;
1280 AtkObject *accessible = NULL;
1282 g_return_val_if_fail (ATK_IS_IMPLEMENTOR (implementor), NULL);
1284 iface = ATK_IMPLEMENTOR_GET_IFACE (implementor);
1287 accessible = iface->ref_accessible (implementor);
1289 g_return_val_if_fail ((accessible != NULL), NULL);
1296 * atk_object_get_attributes:
1297 * @accessible: An #AtkObject.
1299 * Get a list of properties applied to this object as a whole, as an #AtkAttributeSet consisting of
1300 * name-value pairs. As such these attributes may be considered weakly-typed properties or annotations,
1301 * as distinct from strongly-typed object data available via other get/set methods.
1302 * Not all objects have explicit "name-value pair" #AtkAttributeSet properties.
1306 * Returns: (transfer full): an #AtkAttributeSet consisting of all
1307 * explicit properties/annotations applied to the object, or an empty
1308 * set if the object has no name-value pair attributes assigned to
1309 * it. This #atkattributeset should be freed by a call to
1310 * atk_attribute_set_free().
1313 atk_object_get_attributes (AtkObject *accessible)
1315 AtkObjectClass *klass;
1317 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
1319 klass = ATK_OBJECT_GET_CLASS (accessible);
1320 if (klass->get_attributes)
1321 return (klass->get_attributes) (accessible);
1327 static AtkRelationSet*
1328 atk_object_real_ref_relation_set (AtkObject *accessible)
1330 g_return_val_if_fail (accessible->relation_set, NULL);
1331 g_object_ref (accessible->relation_set);
1333 return accessible->relation_set;
1337 atk_object_real_set_property (GObject *object,
1339 const GValue *value,
1342 AtkObject *accessible;
1344 accessible = ATK_OBJECT (object);
1349 atk_object_set_name (accessible, g_value_get_string (value));
1351 case PROP_DESCRIPTION:
1352 atk_object_set_description (accessible, g_value_get_string (value));
1355 atk_object_set_role (accessible, g_value_get_int (value));
1358 atk_object_set_parent (accessible, g_value_get_object (value));
1361 if (ATK_IS_VALUE (accessible))
1362 atk_value_set_current_value (ATK_VALUE (accessible), value);
1364 case PROP_TABLE_SUMMARY:
1365 if (ATK_IS_TABLE (accessible))
1366 atk_table_set_summary (ATK_TABLE (accessible), g_value_get_object (value));
1368 case PROP_TABLE_CAPTION_OBJECT:
1369 if (ATK_IS_TABLE (accessible))
1370 atk_table_set_caption (ATK_TABLE (accessible), g_value_get_object (value));
1378 atk_object_real_get_property (GObject *object,
1383 AtkObject *accessible;
1385 accessible = ATK_OBJECT (object);
1390 g_value_set_string (value, atk_object_get_name (accessible));
1392 case PROP_DESCRIPTION:
1393 g_value_set_string (value, atk_object_get_description (accessible));
1396 g_value_set_int (value, atk_object_get_role (accessible));
1399 if (ATK_IS_COMPONENT (accessible))
1400 g_value_set_int (value, atk_component_get_layer (ATK_COMPONENT (accessible)));
1402 case PROP_MDI_ZORDER:
1403 if (ATK_IS_COMPONENT (accessible))
1404 g_value_set_int (value, atk_component_get_mdi_zorder (ATK_COMPONENT (accessible)));
1407 g_value_set_object (value, atk_object_get_parent (accessible));
1410 if (ATK_IS_VALUE (accessible))
1411 atk_value_get_current_value (ATK_VALUE (accessible), value);
1413 case PROP_TABLE_SUMMARY:
1414 if (ATK_IS_TABLE (accessible))
1415 g_value_set_object (value, atk_table_get_summary (ATK_TABLE (accessible)));
1417 case PROP_TABLE_CAPTION_OBJECT:
1418 if (ATK_IS_TABLE (accessible))
1419 g_value_set_object (value, atk_table_get_caption (ATK_TABLE (accessible)));
1421 case PROP_HYPERTEXT_NUM_LINKS:
1422 if (ATK_IS_HYPERTEXT (accessible))
1423 g_value_set_int (value, atk_hypertext_get_n_links (ATK_HYPERTEXT (accessible)));
1426 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1432 atk_object_finalize (GObject *object)
1434 AtkObject *accessible;
1436 g_return_if_fail (ATK_IS_OBJECT (object));
1438 accessible = ATK_OBJECT (object);
1440 g_free (accessible->name);
1441 g_free (accessible->description);
1444 * Free memory allocated for relation set if it have been allocated.
1446 if (accessible->relation_set)
1447 g_object_unref (accessible->relation_set);
1449 if (accessible->accessible_parent)
1450 g_object_unref (accessible->accessible_parent);
1452 G_OBJECT_CLASS (parent_class)->finalize (object);
1456 atk_object_real_get_name (AtkObject *object)
1458 return object->name;
1462 atk_object_real_get_description (AtkObject *object)
1464 return object->description;
1468 atk_object_real_get_parent (AtkObject *object)
1470 return atk_object_peek_parent (object);
1474 atk_object_real_get_role (AtkObject *object)
1476 return object->role;
1480 atk_object_real_get_layer (AtkObject *object)
1482 return object->layer;
1486 atk_object_real_ref_state_set (AtkObject *accessible)
1488 AtkStateSet *state_set;
1489 AtkObject *focus_object;
1491 state_set = atk_state_set_new ();
1493 focus_object = atk_get_focus_object ();
1494 if (focus_object == accessible)
1495 atk_state_set_add_state (state_set, ATK_STATE_FOCUSED);
1501 atk_object_real_set_name (AtkObject *object,
1504 g_free (object->name);
1505 object->name = g_strdup (name);
1509 atk_object_real_set_description (AtkObject *object,
1510 const gchar *description)
1512 g_free (object->description);
1513 object->description = g_strdup (description);
1517 atk_object_real_set_parent (AtkObject *object,
1520 if (object->accessible_parent)
1521 g_object_unref (object->accessible_parent);
1523 object->accessible_parent = parent;
1524 if (object->accessible_parent)
1525 g_object_ref (object->accessible_parent);
1529 atk_object_real_set_role (AtkObject *object,
1532 object->role = role;
1536 * atk_object_initialize:
1537 * @accessible: a #AtkObject
1538 * @data: a #gpointer which identifies the object for which the AtkObject was created.
1540 * This function is called when implementing subclasses of #AtkObject.
1541 * It does initialization required for the new object. It is intended
1542 * that this function should called only in the ..._new() functions used
1543 * to create an instance of a subclass of #AtkObject
1546 atk_object_initialize (AtkObject *accessible,
1549 AtkObjectClass *klass;
1551 g_return_if_fail (ATK_IS_OBJECT (accessible));
1553 klass = ATK_OBJECT_GET_CLASS (accessible);
1554 if (klass->initialize)
1555 klass->initialize (accessible, data);
1559 * This function is a signal handler for notify signal which gets emitted
1560 * when a property changes value.
1562 * It constructs an AtkPropertyValues structure and emits a "property_changed"
1563 * signal which causes the user specified AtkPropertyChangeHandler
1567 atk_object_notify (GObject *obj,
1570 AtkPropertyValues values = { NULL, };
1572 g_value_init (&values.new_value, pspec->value_type);
1573 g_object_get_property (obj, pspec->name, &values.new_value);
1574 values.property_name = pspec->name;
1575 g_signal_emit (obj, atk_object_signals[PROPERTY_CHANGE],
1576 g_quark_from_string (pspec->name),
1578 g_value_unset (&values.new_value);
1582 * atk_role_get_name:
1583 * @role: The #AtkRole whose name is required
1585 * Gets the description string describing the #AtkRole @role.
1587 * Returns: the string describing the AtkRole
1590 atk_role_get_name (AtkRole role)
1592 g_return_val_if_fail (role >= 0, NULL);
1595 initialize_role_names ();
1597 if (role < role_names->len)
1598 return g_ptr_array_index (role_names, role);
1604 * atk_role_get_localized_name:
1605 * @role: The #AtkRole whose localized name is required
1607 * Gets the localized description string describing the #AtkRole @role.
1609 * Returns: the localized string describing the AtkRole
1612 atk_role_get_localized_name (AtkRole role)
1614 gettext_initialization ();
1616 return dgettext (GETTEXT_PACKAGE, atk_role_get_name (role));
1620 atk_object_real_get_object_locale (AtkObject *object)
1622 return setlocale (LC_MESSAGES, NULL);
1626 * atk_object_get_object_locale:
1627 * @accessible: an #AtkObject
1629 * Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale
1634 * Returns: a UTF-8 string indicating the POSIX-style LC_MESSAGES
1635 * locale of @accessible.
1638 atk_object_get_object_locale (AtkObject *accessible)
1640 AtkObjectClass *klass;
1642 g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL);
1644 klass = ATK_OBJECT_GET_CLASS (accessible);
1645 if (klass->get_object_locale)
1646 return (klass->get_object_locale) (accessible);
1653 * atk_role_for_name:
1654 * @name: a string which is the (non-localized) name of an ATK role.
1656 * Get the #AtkRole type corresponding to a rolew name.
1658 * Returns: the #AtkRole enumerated type corresponding to the specified name,
1659 * or #ATK_ROLE_INVALID if no matching role is found.
1662 atk_role_for_name (const gchar *name)
1664 AtkRole role = ATK_ROLE_INVALID;
1667 g_return_val_if_fail (name, ATK_ROLE_INVALID);
1670 initialize_role_names ();
1672 for (i = 0; i < role_names->len; i++)
1674 gchar *role_name = (gchar *)g_ptr_array_index (role_names, i);
1676 g_return_val_if_fail (role_name, ATK_ROLE_INVALID);
1678 if (strcmp (name, role_name) == 0)
1689 * atk_object_add_relationship:
1690 * @object: The #AtkObject to which an AtkRelation is to be added.
1691 * @relationship: The #AtkRelationType of the relation
1692 * @target: The #AtkObject which is to be the target of the relation.
1694 * Adds a relationship of the specified type with the specified target.
1696 * Returns: TRUE if the relationship is added.
1699 atk_object_add_relationship (AtkObject *object,
1700 AtkRelationType relationship,
1703 AtkObject *array[1];
1704 AtkRelation *relation;
1706 g_return_val_if_fail (ATK_IS_OBJECT (object), FALSE);
1707 g_return_val_if_fail (ATK_IS_OBJECT (target), FALSE);
1709 if (atk_relation_set_contains_target (object->relation_set,
1710 relationship, target))
1714 relation = atk_relation_new (array, 1, relationship);
1715 atk_relation_set_add (object->relation_set, relation);
1716 g_object_unref (relation);
1722 * atk_object_remove_relationship:
1723 * @object: The #AtkObject from which an AtkRelation is to be removed.
1724 * @relationship: The #AtkRelationType of the relation
1725 * @target: The #AtkObject which is the target of the relation to be removed.
1727 * Removes a relationship of the specified type with the specified target.
1729 * Returns: TRUE if the relationship is removed.
1732 atk_object_remove_relationship (AtkObject *object,
1733 AtkRelationType relationship,
1736 gboolean ret = FALSE;
1737 AtkRelation *relation;
1740 g_return_val_if_fail (ATK_IS_OBJECT (object), FALSE);
1741 g_return_val_if_fail (ATK_IS_OBJECT (target), FALSE);
1743 relation = atk_relation_set_get_relation_by_type (object->relation_set, relationship);
1747 ret = atk_relation_remove_target (relation, target);
1748 array = atk_relation_get_target (relation);
1749 if (!array || array->len == 0)
1750 atk_relation_set_remove (object->relation_set, relation);
1756 atk_object_real_initialize (AtkObject *accessible,