X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=atk%2Fatkobject.c;h=fb61babfe0942df19b15bdbdfee100b4097e830c;hb=91469053dfedda0b56fd9eb62a234ccdf68cc6ad;hp=682c837cbc52ecaab622a04078c486d141827445;hpb=65234b02406950b3e2114b5f3d86abf9c746ef77;p=platform%2Fupstream%2Fatk.git diff --git a/atk/atkobject.c b/atk/atkobject.c old mode 100755 new mode 100644 index 682c837..fb61bab --- a/atk/atkobject.c +++ b/atk/atkobject.c @@ -17,13 +17,48 @@ * Boston, MA 02111-1307, USA. */ +#include "config.h" + #include +#include #include +#include #include "atk.h" +#include "atkmarshal.h" +#include "atkprivate.h" + +/** + * SECTION:atkobject + * @Short_description: The base object class for the Accessibility Toolkit API. + * @Title:AtkObject + * + * This class is the primary class for accessibility support via the + * Accessibility ToolKit (ATK). Objects which are instances of + * #AtkObject (or instances of AtkObject-derived types) are queried + * for properties which relate basic (and generic) properties of a UI + * component such as name and description. Instances of #AtkObject + * may also be queried as to whether they implement other ATK + * interfaces (e.g. #AtkAction, #AtkComponent, etc.), as appropriate + * to the role which a given UI component plays in a user interface. + * + * All UI components in an application which provide useful + * information or services to the user must provide corresponding + * #AtkObject instances on request (in GTK+, for instance, usually on + * a call to #gtk_widget_get_accessible ()), either via ATK support + * built into the toolkit for the widget class or ancestor class, or + * in the case of custom widgets, if the inherited #AtkObject + * implementation is insufficient, via instances of a new #AtkObject + * subclass. + * + * See also: #AtkObjectFactory, #AtkRegistry. (GTK+ users see also + * #GtkAccessible). + * + */ + +static GPtrArray *role_names = NULL; -/* New GObject properties registered by AtkObject */ enum { PROP_0, /* gobject convention */ @@ -31,15 +66,18 @@ enum PROP_NAME, PROP_DESCRIPTION, PROP_PARENT, /* ancestry has changed */ - PROP_STATE, /* AtkStateSet for the object has changed */ PROP_VALUE, PROP_ROLE, + PROP_LAYER, + PROP_MDI_ZORDER, PROP_TABLE_CAPTION, PROP_TABLE_COLUMN_DESCRIPTION, PROP_TABLE_COLUMN_HEADER, PROP_TABLE_ROW_DESCRIPTION, PROP_TABLE_ROW_HEADER, PROP_TABLE_SUMMARY, + PROP_TABLE_CAPTION_OBJECT, + PROP_HYPERTEXT_NUM_LINKS, PROP_LAST /* gobject convention */ }; @@ -47,17 +85,142 @@ enum { CHILDREN_CHANGED, FOCUS_EVENT, PROPERTY_CHANGE, + STATE_CHANGE, VISIBLE_DATA_CHANGED, - + ACTIVE_DESCENDANT_CHANGED, + LAST_SIGNAL }; +/* These are listed here for extraction by intltool */ +#if 0 + N_("invalid") + N_("accelerator label") + N_("alert") + N_("animation") + N_("arrow") + N_("calendar") + N_("canvas") + N_("check box") + N_("check menu item") + N_("color chooser") + N_("column header") + N_("combo box") + N_("dateeditor") + N_("desktop icon") + N_("desktop frame") + N_("dial") + N_("dialog") + N_("directory pane") + N_("drawing area") + N_("file chooser") + N_("filler") + /* I know it looks wrong but that is what Java returns */ + N_("fontchooser") + N_("frame") + N_("glass pane") + N_("html container") + N_("icon") + N_("image") + N_("internal frame") + N_("label") + N_("layered pane") + N_("list") + N_("list item") + N_("menu") + N_("menu bar") + N_("menu item") + N_("option pane") + N_("page tab") + N_("page tab list") + N_("panel") + N_("password text") + N_("popup menu") + N_("progress bar") + N_("push button") + N_("radio button") + N_("radio menu item") + N_("root pane") + N_("row header") + N_("scroll bar") + N_("scroll pane") + N_("separator") + N_("slider") + N_("split pane") + N_("spin button") + N_("statusbar") + N_("table") + N_("table cell") + N_("table column header") + N_("table row header") + N_("tear off menu item") + N_("terminal") + N_("text") + N_("toggle button") + N_("tool bar") + N_("tool tip") + N_("tree") + N_("tree table") + N_("unknown") + N_("viewport") + N_("window") + N_("header") + N_("footer") + N_("paragraph") + N_("ruler") + N_("application") + N_("autocomplete") + N_("edit bar") + N_("embedded component") + N_("entry") + N_("chart") + N_("caption") + N_("document frame") + N_("heading") + N_("page") + N_("section") + N_("redundant object") + N_("form") + N_("link") + N_("input method window") + N_("table row") + N_("tree item") + N_("document spreadsheet") + N_("document presentation") + N_("document text") + N_("document web") + N_("document email") + N_("comment") + N_("list box") + N_("grouping") + N_("image map") + N_("notification") + N_("info bar") + N_("level bar") + N_("title bar") + N_("block quote") + N_("audio") + N_("video") + N_("definition") + N_("article") + N_("landmark") + N_("log") + N_("marquee") + N_("math") + N_("rating") + N_("timer") + N_("description list") + N_("description term") + N_("description value") +#endif /* 0 */ + static void atk_object_class_init (AtkObjectClass *klass); static void atk_object_init (AtkObject *accessible, AtkObjectClass *klass); static AtkRelationSet* atk_object_real_ref_relation_set (AtkObject *accessible); - +static void atk_object_real_initialize (AtkObject *accessible, + gpointer data); static void atk_object_real_set_property (GObject *object, guint prop_id, const GValue *value, @@ -67,13 +230,12 @@ static void atk_object_real_get_property (GObject *object, GValue *value, GParamSpec *pspec); static void atk_object_finalize (GObject *object); -static G_CONST_RETURN gchar* - atk_object_real_get_name (AtkObject *object); -static G_CONST_RETURN gchar* - atk_object_real_get_description +static const gchar* atk_object_real_get_name (AtkObject *object); +static const gchar* atk_object_real_get_description (AtkObject *object); static AtkObject* atk_object_real_get_parent (AtkObject *object); static AtkRole atk_object_real_get_role (AtkObject *object); +static AtkLayer atk_object_real_get_layer (AtkObject *object); static AtkStateSet* atk_object_real_ref_state_set (AtkObject *object); static void atk_object_real_set_name (AtkObject *object, @@ -85,33 +247,59 @@ static void atk_object_real_set_parent (AtkObject *object, AtkObject *parent); static void atk_object_real_set_role (AtkObject *object, AtkRole role); -static guint atk_object_real_connect_property_change_handler - (AtkObject *obj, - AtkPropertyChangeHandler - *handler); -static void atk_object_real_remove_property_change_handler - (AtkObject *obj, - guint handler_id); static void atk_object_notify (GObject *obj, GParamSpec *pspec); - +static const gchar* atk_object_real_get_object_locale + (AtkObject *object); static guint atk_object_signals[LAST_SIGNAL] = { 0, }; static gpointer parent_class = NULL; -static const gchar* atk_object_name_property_name = "accessible-name"; -static const gchar* atk_object_name_property_state = "accessible-state"; -static const gchar* atk_object_name_property_description = "accessible-description"; -static const gchar* atk_object_name_property_parent = "accessible-parent"; -static const gchar* atk_object_name_property_value = "accessible-value"; -static const gchar* atk_object_name_property_role = "accessible-role"; -static const gchar* atk_object_name_property_table_caption = "accessible-table-caption"; -static const gchar* atk_object_name_property_table_column_description = "accessible-table-column-description"; -static const gchar* atk_object_name_property_table_column_header = "accessible-table-column-header"; -static const gchar* atk_object_name_property_table_row_description = "accessible-table-row-description"; -static const gchar* atk_object_name_property_table_row_header = "accessible-table-row-header"; -static const gchar* atk_object_name_property_table_summary = "accessible-table-summary"; +static const gchar* const atk_object_name_property_name = "accessible-name"; +static const gchar* const atk_object_name_property_description = "accessible-description"; +static const gchar* const atk_object_name_property_parent = "accessible-parent"; +static const gchar* const atk_object_name_property_value = "accessible-value"; +static const gchar* const atk_object_name_property_role = "accessible-role"; +static const gchar* const atk_object_name_property_component_layer = "accessible-component-layer"; +static const gchar* const atk_object_name_property_component_mdi_zorder = "accessible-component-mdi-zorder"; +static const gchar* const atk_object_name_property_table_caption = "accessible-table-caption"; +static const gchar* const atk_object_name_property_table_column_description = "accessible-table-column-description"; +static const gchar* const atk_object_name_property_table_column_header = "accessible-table-column-header"; +static const gchar* const atk_object_name_property_table_row_description = "accessible-table-row-description"; +static const gchar* const atk_object_name_property_table_row_header = "accessible-table-row-header"; +static const gchar* const atk_object_name_property_table_summary = "accessible-table-summary"; +static const gchar* const atk_object_name_property_table_caption_object = "accessible-table-caption-object"; +static const gchar* const atk_object_name_property_hypertext_num_links = "accessible-hypertext-nlinks"; + +static void +initialize_role_names () +{ + GTypeClass *enum_class; + GEnumValue *enum_value; + int i; + gchar *role_name = NULL; + + if (role_names) + return; + + role_names = g_ptr_array_new (); + enum_class = g_type_class_ref (ATK_TYPE_ROLE); + if (!G_IS_ENUM_CLASS(enum_class)) + return; + + for (i = 0; i < ATK_ROLE_LAST_DEFINED; i++) + { + enum_value = g_enum_get_value (G_ENUM_CLASS (enum_class), i); + role_name = g_strdup (enum_value->value_nick); + // We want the role names to be in the format "check button" and not "check-button" + _compact_name (role_name); + g_ptr_array_add (role_names, role_name); + } + + g_type_class_unref (enum_class); + +} GType atk_object_get_type (void) @@ -142,7 +330,7 @@ atk_object_class_init (AtkObjectClass *klass) { GObjectClass *gobject_class = G_OBJECT_CLASS (klass); - parent_class = g_type_class_ref (G_TYPE_OBJECT); + parent_class = g_type_class_peek_parent (klass); gobject_class->set_property = atk_object_real_set_property; gobject_class->get_property = atk_object_real_get_property; @@ -157,15 +345,15 @@ atk_object_class_init (AtkObjectClass *klass) klass->get_index_in_parent = NULL; klass->ref_relation_set = atk_object_real_ref_relation_set; klass->get_role = atk_object_real_get_role; + klass->get_layer = atk_object_real_get_layer; + klass->get_mdi_zorder = NULL; + klass->initialize = atk_object_real_initialize; klass->ref_state_set = atk_object_real_ref_state_set; klass->set_name = atk_object_real_set_name; klass->set_description = atk_object_real_set_description; klass->set_parent = atk_object_real_set_parent; klass->set_role = atk_object_real_set_role; - klass->connect_property_change_handler = - atk_object_real_connect_property_change_handler; - klass->remove_property_change_handler = - atk_object_real_remove_property_change_handler; + klass->get_object_locale = atk_object_real_get_object_locale; /* * We do not define default signal handlers here @@ -174,45 +362,46 @@ atk_object_class_init (AtkObjectClass *klass) klass->focus_event = NULL; klass->property_change = NULL; klass->visible_data_changed = NULL; + klass->active_descendant_changed = NULL; + + _gettext_initialization (); g_object_class_install_property (gobject_class, PROP_NAME, g_param_spec_string (atk_object_name_property_name, - "Accessible Name", - "Object instance\'s name formatted for " - "assistive technology access", + _("Accessible Name"), + _("Object instance’s name formatted for assistive technology access"), NULL, G_PARAM_READWRITE)); g_object_class_install_property (gobject_class, PROP_DESCRIPTION, g_param_spec_string (atk_object_name_property_description, - "Accessible Description", - "Description of an object, formatted for " - "assistive technology access", + _("Accessible Description"), + _("Description of an object, formatted for assistive technology access"), NULL, G_PARAM_READWRITE)); g_object_class_install_property (gobject_class, - PROP_STATE, - g_param_spec_int (atk_object_name_property_state, - "Accessible State Set", - "The accessible state set of this object " - "or its UI component", - 0, - G_MAXINT, - 0, - G_PARAM_READWRITE)); - g_object_class_install_property (gobject_class, PROP_PARENT, g_param_spec_object (atk_object_name_property_parent, - "Accessible Parent", - "Is used to notify that the parent has changed ", + _("Accessible Parent"), + _("Parent of the current accessible as returned by atk_object_get_parent()"), ATK_TYPE_OBJECT, G_PARAM_READWRITE)); + + /** + * AtkObject:accessible-value: + * + * Numeric value of this object, in case being and AtkValue. + * + * Deprecated: Since 2.12. Use atk_value_get_value_and_text() to get + * the value, and value-changed signal to be notified on their value + * changes. + */ g_object_class_install_property (gobject_class, PROP_VALUE, g_param_spec_double (atk_object_name_property_value, - "Accessible Value", - "Is used to notify that the value has changed ", + _("Accessible Value"), + _("Is used to notify that the value has changed"), 0.0, G_MAXDOUBLE, 0.0, @@ -220,57 +409,145 @@ atk_object_class_init (AtkObjectClass *klass) g_object_class_install_property (gobject_class, PROP_ROLE, g_param_spec_int (atk_object_name_property_role, - "Accessible Role", - "The accessible role this object ", + _("Accessible Role"), + _("The accessible role of this object"), 0, G_MAXINT, - 0, + ATK_ROLE_UNKNOWN, G_PARAM_READWRITE)); g_object_class_install_property (gobject_class, + PROP_LAYER, + g_param_spec_int (atk_object_name_property_component_layer, + _("Accessible Layer"), + _("The accessible layer of this object"), + 0, + G_MAXINT, + 0, + G_PARAM_READABLE)); + g_object_class_install_property (gobject_class, + PROP_MDI_ZORDER, + g_param_spec_int (atk_object_name_property_component_mdi_zorder, + _("Accessible MDI Value"), + _("The accessible MDI value of this object"), + G_MININT, + G_MAXINT, + G_MININT, + G_PARAM_READABLE)); + + /** + * AtkObject:accessible-table-caption: + * + * Table caption. + * + * Deprecated: Since 1.3. Use table-caption-object instead. + */ + g_object_class_install_property (gobject_class, PROP_TABLE_CAPTION, g_param_spec_string (atk_object_name_property_table_caption, - "Accessible Table Caption", - "Is used to notify that the table caption has changed ", + _("Accessible Table Caption"), + _("Is used to notify that the table caption has changed; this property should not be used. accessible-table-caption-object should be used instead"), NULL, G_PARAM_READWRITE)); + /** + * AtkObject:accessible-table-column-header: + * + * Accessible table column header. + * + * Deprecated: Since 2.12. Use atk_table_get_column_header() and + * atk_table_set_column_header() instead. + */ g_object_class_install_property (gobject_class, PROP_TABLE_COLUMN_HEADER, g_param_spec_object (atk_object_name_property_table_column_header, - "Accessible Table Column Header", - "Is used to notify that the table column header has changed ", + _("Accessible Table Column Header"), + _("Is used to notify that the table column header has changed"), ATK_TYPE_OBJECT, G_PARAM_READWRITE)); + + /** + * AtkObject:accessible-table-column-description: + * + * Accessible table column description. + * + * Deprecated: Since 2.12. Use atk_table_get_column_description() + * and atk_table_set_column_description() instead. + */ g_object_class_install_property (gobject_class, PROP_TABLE_COLUMN_DESCRIPTION, g_param_spec_string (atk_object_name_property_table_column_description, - "Accessible Table Column Description", - "Is used to notify that the table columnscription has changed ", + _("Accessible Table Column Description"), + _("Is used to notify that the table column description has changed"), NULL, G_PARAM_READWRITE)); + + /** + * AtkObject:accessible-table-row-header: + * + * Accessible table row header. + * + * Deprecated: Since 2.12. Use atk_table_get_row_header() and + * atk_table_set_row_header() instead. + */ g_object_class_install_property (gobject_class, PROP_TABLE_ROW_HEADER, g_param_spec_object (atk_object_name_property_table_row_header, - "Accessible Table Row Header", - "Is used to notify that the table row header has changed ", + _("Accessible Table Row Header"), + _("Is used to notify that the table row header has changed"), ATK_TYPE_OBJECT, G_PARAM_READWRITE)); + /** + * AtkObject:accessible-table-row-description: + * + * Accessible table row description. + * + * Deprecated: Since 2.12. Use atk_table_get_row_description() and + * atk_table_set_row_description() instead. + */ g_object_class_install_property (gobject_class, PROP_TABLE_ROW_DESCRIPTION, g_param_spec_string (atk_object_name_property_table_row_description, - "Accessible Table Row Description", - "Is used to notify that the table row description has changed ", + _("Accessible Table Row Description"), + _("Is used to notify that the table row description has changed"), NULL, G_PARAM_READWRITE)); g_object_class_install_property (gobject_class, PROP_TABLE_SUMMARY, g_param_spec_object (atk_object_name_property_table_summary, - "Accessible Table Summary", - "Is used to notify that the table summary has changed ", + _("Accessible Table Summary"), + _("Is used to notify that the table summary has changed"), ATK_TYPE_OBJECT, G_PARAM_READWRITE)); - /* - * The signal "children_changed" supports two details: - * "add" and "remove" + g_object_class_install_property (gobject_class, + PROP_TABLE_CAPTION_OBJECT, + g_param_spec_object (atk_object_name_property_table_caption_object, + _("Accessible Table Caption Object"), + _("Is used to notify that the table caption has changed"), + ATK_TYPE_OBJECT, + G_PARAM_READWRITE)); + g_object_class_install_property (gobject_class, + PROP_HYPERTEXT_NUM_LINKS, + g_param_spec_int (atk_object_name_property_hypertext_num_links, + _("Number of Accessible Hypertext Links"), + _("The number of links which the current AtkHypertext has"), + 0, + G_MAXINT, + 0, + G_PARAM_READABLE)); + + /** + * AtkObject::children-changed: + * @atkobject: the object which received the signal. + * @arg1: The index of the added or removed child. The value can be + * -1. This is used if the value is not known by the implementor + * when the child is added/removed or irrelevant. + * @arg2: A gpointer to the child AtkObject which was added or + * removed. If the child was removed, it is possible that it is not + * available for the implementor. In that case this pointer can be + * NULL. + * + * The signal "children-changed" is emitted when a child is added or + * removed form an object. It supports two details: "add" and + * "remove" */ atk_object_signals[CHILDREN_CHANGED] = g_signal_new ("children_changed", @@ -281,6 +558,18 @@ atk_object_class_init (AtkObjectClass *klass) g_cclosure_marshal_VOID__UINT_POINTER, G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_POINTER); + + /** + * AtkObject::focus-event: + * @atkobject: the object which received the signal + * @arg1: a boolean value which indicates whether the object gained + * or lost focus. + * + * The signal "focus-event" is emitted when an object gained or lost + * focus. + * + * Deprecated: 2.9.4: Use the #AtkObject::state-change signal instead. + */ atk_object_signals[FOCUS_EVENT] = g_signal_new ("focus_event", G_TYPE_FROM_CLASS (klass), @@ -290,6 +579,26 @@ atk_object_class_init (AtkObjectClass *klass) g_cclosure_marshal_VOID__BOOLEAN, G_TYPE_NONE, 1, G_TYPE_BOOLEAN); + /** + * AtkObject::property-change: + * @atkobject: the object which received the signal. + * @arg1: an #AtkPropertyValues containing the new value of the + * property which changed. + * + * The signal "property-change" is emitted when an object's property + * value changes. @arg1 contains an #AtkPropertyValues with the name + * and the new value of the property whose value has changed. Note + * that, as with GObject notify, getting this signal does not + * guarantee that the value of the property has actually changed; it + * may also be emitted when the setter of the property is called to + * reinstate the previous value. + * + * Toolkit implementor note: ATK implementors should use + * g_object_notify() to emit property-changed + * notifications. #AtkObject::property-changed is needed by the + * implementation of atk_add_global_event_listener() because GObject + * notify doesn't support emission hooks. + */ atk_object_signals[PROPERTY_CHANGE] = g_signal_new ("property_change", G_TYPE_FROM_CLASS (klass), @@ -299,6 +608,35 @@ atk_object_class_init (AtkObjectClass *klass) g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_POINTER); + + /** + * AtkObject::state-change: + * @atkobject: the object which received the signal. + * @arg1: The name of the state which has changed + * @arg2: A boolean which indicates whether the state has been set or unset. + * + * The "state-change" signal is emitted when an object's state + * changes. The detail value identifies the state type which has + * changed. + */ + atk_object_signals[STATE_CHANGE] = + g_signal_new ("state_change", + G_TYPE_FROM_CLASS (klass), + G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED, + G_STRUCT_OFFSET (AtkObjectClass, state_change), + (GSignalAccumulator) NULL, NULL, + atk_marshal_VOID__STRING_BOOLEAN, + G_TYPE_NONE, 2, + G_TYPE_STRING, + G_TYPE_BOOLEAN); + + /** + * AtkObject::visible-data-changed: + * @atkobject: the object which received the signal. + * + * The "visible-data-changed" signal is emitted when the visual + * appearance of the object changed. + */ atk_object_signals[VISIBLE_DATA_CHANGED] = g_signal_new ("visible_data_changed", G_TYPE_FROM_CLASS (klass), @@ -307,6 +645,26 @@ atk_object_class_init (AtkObjectClass *klass) (GSignalAccumulator) NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * AtkObject::active-descendant-changed: + * @atkobject: the object which received the signal. + * @arg1: the newly focused object. + * + * The "active-descendant-changed" signal is emitted by an object + * which has the state ATK_STATE_MANAGES_DESCENDANTS when the focus + * object in the object changes. For instance, a table will emit the + * signal when the cell in the table which has focus changes. + */ + atk_object_signals[ACTIVE_DESCENDANT_CHANGED] = + g_signal_new ("active_descendant_changed", + G_TYPE_FROM_CLASS (klass), + G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED, + G_STRUCT_OFFSET (AtkObjectClass, active_descendant_changed), + NULL, NULL, + g_cclosure_marshal_VOID__POINTER, + G_TYPE_NONE, + 1, G_TYPE_POINTER); } static void @@ -348,7 +706,7 @@ atk_implementor_get_type (void) * * Returns: a character string representing the accessible name of the object. **/ -G_CONST_RETURN gchar* +const gchar* atk_object_get_name (AtkObject *accessible) { AtkObjectClass *klass; @@ -372,7 +730,7 @@ atk_object_get_name (AtkObject *accessible) * of the accessible. * **/ -G_CONST_RETURN gchar* +const gchar* atk_object_get_description (AtkObject *accessible) { AtkObjectClass *klass; @@ -390,9 +748,17 @@ atk_object_get_description (AtkObject *accessible) * atk_object_get_parent: * @accessible: an #AtkObject * - * Gets the accessible parent of the accessible. + * Gets the accessible parent of the accessible. By default this is + * the one assigned with atk_object_set_parent(), but it is assumed + * that ATK implementors have ways to get the parent of the object + * without the need of assigning it manually with + * atk_object_set_parent(), and will return it with this method. + * + * If you are only interested on the parent assigned with + * atk_object_set_parent(), use atk_object_peek_parent(). * - * Returns: a #AtkObject representing the accessible parent of the accessible + * Returns: (transfer none): an #AtkObject representing the accessible + * parent of the accessible **/ AtkObject* atk_object_get_parent (AtkObject *accessible) @@ -409,6 +775,27 @@ atk_object_get_parent (AtkObject *accessible) } /** + * atk_object_peek_parent: + * @accessible: an #AtkObject + * + * Gets the accessible parent of the accessible, if it has been + * manually assigned with atk_object_set_parent. Otherwise, this + * function returns %NULL. + * + * This method is intended as an utility for ATK implementors, and not + * to be exposed to accessible tools. See atk_object_get_parent() for + * further reference. + * + * Returns: (transfer none): an #AtkObject representing the accessible + * parent of the accessible if assigned + **/ +AtkObject* +atk_object_peek_parent (AtkObject *accessible) +{ + return accessible->accessible_parent; +} + +/** * atk_object_get_n_accessible_children: * @accessible: an #AtkObject * @@ -440,8 +827,8 @@ atk_object_get_n_accessible_children (AtkObject *accessible) * The accessible children are 0-based so the first accessible child is * at index 0, the second at index 1 and so on. * - * Returns: an #AtkObject representing the specified accessible child - * of the accessible. + * Returns: (transfer full): an #AtkObject representing the specified + * accessible child of the accessible. **/ AtkObject* atk_object_ref_accessible_child (AtkObject *accessible, @@ -464,7 +851,8 @@ atk_object_ref_accessible_child (AtkObject *accessible, * * Gets the #AtkRelationSet associated with the object. * - * Returns: an #AtkRelationSet representing the relation set of the object. + * Returns: (transfer full): an #AtkRelationSet representing the relation set + * of the object. **/ AtkRelationSet* atk_object_ref_relation_set (AtkObject *accessible) @@ -484,16 +872,38 @@ atk_object_ref_relation_set (AtkObject *accessible) * atk_role_register: * @name: a character string describing the new role. * - * Registers the role specified by @name. + * Registers the role specified by @name. @name must be a meaningful + * name. So it should not be empty, or consisting on whitespaces. + * + * Deprecated: Since 2.12. If your application/toolkit doesn't find a + * suitable role for a specific object defined at #AtkRole, please + * submit a bug in order to add a new role to the specification. * - * Returns: an #AtkRole for the new role. + * Returns: an #AtkRole for the new role if added + * properly. ATK_ROLE_INVALID in case of error. **/ AtkRole atk_role_register (const gchar *name) { - /* TODO: associate name with new type */ - static guint type = ATK_ROLE_LAST_DEFINED; - return (++type); + gboolean valid = FALSE; + gint i = 0; + glong length = g_utf8_strlen (name, -1); + + for (i=0; i < length; i++) { + if (name[i]!=' ') { + valid = TRUE; + break; + } + } + + if (!valid) + return ATK_ROLE_INVALID; + + if (!role_names) + initialize_role_names (); + + g_ptr_array_add (role_names, g_strdup (name)); + return role_names->len - 1; } /** @@ -519,13 +929,65 @@ atk_object_get_role (AtkObject *accessible) } /** + * atk_object_get_layer: + * @accessible: an #AtkObject + * + * Gets the layer of the accessible. + * + * Deprecated: Use atk_component_get_layer instead. + * + * Returns: an #AtkLayer which is the layer of the accessible + **/ +AtkLayer +atk_object_get_layer (AtkObject *accessible) +{ + AtkObjectClass *klass; + + g_return_val_if_fail (ATK_IS_OBJECT (accessible), ATK_LAYER_INVALID); + + klass = ATK_OBJECT_GET_CLASS (accessible); + if (klass->get_layer) + return (klass->get_layer) (accessible); + else + return ATK_LAYER_INVALID; +} + +/** + * atk_object_get_mdi_zorder: + * @accessible: an #AtkObject + * + * Gets the zorder of the accessible. The value G_MININT will be returned + * if the layer of the accessible is not ATK_LAYER_MDI. + * + * Deprecated: Use atk_component_get_mdi_zorder instead. + * + * Returns: a gint which is the zorder of the accessible, i.e. the depth at + * which the component is shown in relation to other components in the same + * container. + * + **/ +gint +atk_object_get_mdi_zorder (AtkObject *accessible) +{ + AtkObjectClass *klass; + + g_return_val_if_fail (ATK_IS_OBJECT (accessible), G_MININT); + + klass = ATK_OBJECT_GET_CLASS (accessible); + if (klass->get_mdi_zorder) + return (klass->get_mdi_zorder) (accessible); + else + return G_MININT; +} + +/** * atk_object_ref_state_set: * @accessible: an #AtkObject * * Gets a reference to the state set of the accessible; the caller must * unreference it when it is no longer needed. * - * Returns: a reference to an #AtkStateSet which is the state + * Returns: (transfer full): a reference to an #AtkStateSet which is the state * set of the accessible **/ AtkStateSet* @@ -570,13 +1032,17 @@ atk_object_get_index_in_parent (AtkObject *accessible) * @accessible: an #AtkObject * @name: a character string to be set as the accessible name * - * Sets the accessible name of the accessible. + * Sets the accessible name of the accessible. You can't set the name + * to NULL. This is reserved for the initial value. In this aspect + * NULL is similar to ATK_ROLE_UNKNOWN. If you want to set the name to + * a empty value you can use "". **/ void atk_object_set_name (AtkObject *accessible, const gchar *name) { AtkObjectClass *klass; + gboolean notify = FALSE; g_return_if_fail (ATK_IS_OBJECT (accessible)); g_return_if_fail (name != NULL); @@ -584,23 +1050,31 @@ atk_object_set_name (AtkObject *accessible, klass = ATK_OBJECT_GET_CLASS (accessible); if (klass->set_name) { + /* Do not notify for initial name setting. See bug 665870 */ + notify = (accessible->name != NULL); + (klass->set_name) (accessible, name); - g_object_notify (G_OBJECT (accessible), atk_object_name_property_name); + if (notify) + g_object_notify (G_OBJECT (accessible), atk_object_name_property_name); } } /** * atk_object_set_description: * @accessible: an #AtkObject - * @description : a character string to be set as the accessible description + * @description: a character string to be set as the accessible description * - * Sets the accessible description of the accessible. + * Sets the accessible description of the accessible. You can't set + * the description to NULL. This is reserved for the initial value. In + * this aspect NULL is similar to ATK_ROLE_UNKNOWN. If you want to set + * the name to a empty value you can use "". **/ void atk_object_set_description (AtkObject *accessible, const gchar *description) { AtkObjectClass *klass; + gboolean notify = FALSE; g_return_if_fail (ATK_IS_OBJECT (accessible)); g_return_if_fail (description != NULL); @@ -608,17 +1082,22 @@ atk_object_set_description (AtkObject *accessible, klass = ATK_OBJECT_GET_CLASS (accessible); if (klass->set_description) { + /* Do not notify for initial name setting. See bug 665870 */ + notify = (accessible->description != NULL); + (klass->set_description) (accessible, description); - g_object_notify (G_OBJECT (accessible), atk_object_name_property_description); + if (notify) + g_object_notify (G_OBJECT (accessible), + atk_object_name_property_description); } } /** * atk_object_set_parent: * @accessible: an #AtkObject - * @parent : an #AtkObject to be set as the accessible parent + * @parent: an #AtkObject to be set as the accessible parent * - * Sets the accessible parent of the accessible. + * Sets the accessible parent of the accessible. @parent can be NULL. **/ void atk_object_set_parent (AtkObject *accessible, @@ -639,7 +1118,7 @@ atk_object_set_parent (AtkObject *accessible, /** * atk_object_set_role: * @accessible: an #AtkObject - * @role : an #AtkRole to be set as the role + * @role: an #AtkRole to be set as the role * * Sets the role of the accessible. **/ @@ -648,23 +1127,31 @@ atk_object_set_role (AtkObject *accessible, AtkRole role) { AtkObjectClass *klass; + AtkRole old_role; g_return_if_fail (ATK_IS_OBJECT (accessible)); klass = ATK_OBJECT_GET_CLASS (accessible); if (klass->set_role) { - (klass->set_role) (accessible, role); - g_object_notify (G_OBJECT (accessible), atk_object_name_property_role); + old_role = atk_object_get_role (accessible); + if (old_role != role) + { + (klass->set_role) (accessible, role); + if (old_role != ATK_ROLE_UNKNOWN) + /* Do not notify for initial role setting */ + g_object_notify (G_OBJECT (accessible), atk_object_name_property_role); + } } } /** - * atk_object_connect_property_change_handler: + * atk_object_connect_property_change_handler: (skip) * @accessible: an #AtkObject - * @handler : a function to be called when a property changes its value + * @handler: a function to be called when a property changes its value * - * Specifies a function to be called when a property changes value. + * Deprecated: Since 2.12. Connect directly to property-change or + * notify signals. * * Returns: a #guint which is the handler id used in * atk_object_remove_property_change_handler() @@ -688,8 +1175,10 @@ atk_object_connect_property_change_handler (AtkObject *accessible, /** * atk_object_remove_property_change_handler: * @accessible: an #AtkObject - * @handler_id : a guint which identifies the handler to be removed. - * + * @handler_id: a guint which identifies the handler to be removed. + * + * Deprecated: Since 2.12. + * * Removes a property change handler. **/ void @@ -709,49 +1198,26 @@ atk_object_remove_property_change_handler (AtkObject *accessible, * atk_object_notify_state_change: * @accessible: an #AtkObject * @state: an #AtkState whose state is changed - * @value : a gboolean which indicates whether the state is being set on or off + * @value: a gboolean which indicates whether the state is being set on or off * - * Emits a property_change signal for the specified state. - * This signal is caught by an #AtkPropertyChangeHandler + * Emits a state-change signal for the specified state. + * + * Note that as a general rule when the state of an existing object changes, + * emitting a notification is expected. **/ void atk_object_notify_state_change (AtkObject *accessible, AtkState state, gboolean value) { -#define N_TOGGLE_STATES 2 - AtkPropertyValues values = { 0, }; - AtkState toggle_states[N_TOGGLE_STATES] = { ATK_STATE_EXPANDED, - ATK_STATE_COLLAPSED }; - AtkState toggled_states[N_TOGGLE_STATES] = { ATK_STATE_COLLAPSED, - ATK_STATE_EXPANDED }; + const gchar* name; - values.property_name = atk_object_name_property_state; - if (value) - { - gint i; - - g_value_init (&values.new_value, G_TYPE_INT); - g_value_set_int (&values.new_value, state); - - for (i = 0; i < N_TOGGLE_STATES; i++) - { - if (toggle_states[i] == state) - { - g_value_init (&values.old_value, G_TYPE_INT); - g_value_set_int (&values.old_value, toggled_states[i]); - break; - } - } - } - else - { - g_value_init (&values.old_value, G_TYPE_INT); - g_value_set_int (&values.old_value, state); - } - g_signal_emit (accessible, atk_object_signals[PROPERTY_CHANGE], - g_quark_from_string (atk_object_name_property_state), - &values, NULL); + g_return_if_fail (ATK_IS_OBJECT (accessible)); + + name = atk_state_type_get_name (state); + g_signal_emit (accessible, atk_object_signals[STATE_CHANGE], + g_quark_from_string (name), + name, value, NULL); } /** @@ -762,26 +1228,60 @@ atk_object_notify_state_change (AtkObject *accessible, * Gets a reference to an object's #AtkObject implementation, if * the object implements #AtkObjectIface * - * Returns: a reference to an object's #AtkObject implementation + * Returns: (transfer full): a reference to an object's #AtkObject + * implementation */ AtkObject * -atk_implementor_ref_accessible (AtkImplementor *object) +atk_implementor_ref_accessible (AtkImplementor *implementor) { AtkImplementorIface *iface; AtkObject *accessible = NULL; - g_return_val_if_fail (ATK_IS_IMPLEMENTOR (object), NULL); + g_return_val_if_fail (ATK_IS_IMPLEMENTOR (implementor), NULL); - iface = ATK_IMPLEMENTOR_GET_IFACE (object); + iface = ATK_IMPLEMENTOR_GET_IFACE (implementor); if (iface != NULL) - accessible = iface->ref_accessible (object); + accessible = iface->ref_accessible (implementor); g_return_val_if_fail ((accessible != NULL), NULL); return accessible; } + +/** + * atk_object_get_attributes: + * @accessible: An #AtkObject. + * + * Get a list of properties applied to this object as a whole, as an #AtkAttributeSet consisting of + * name-value pairs. As such these attributes may be considered weakly-typed properties or annotations, + * as distinct from strongly-typed object data available via other get/set methods. + * Not all objects have explicit "name-value pair" #AtkAttributeSet properties. + * + * Since: 1.12 + * + * Returns: (transfer full): an #AtkAttributeSet consisting of all + * explicit properties/annotations applied to the object, or an empty + * set if the object has no name-value pair attributes assigned to + * it. This #atkattributeset should be freed by a call to + * atk_attribute_set_free(). + */ +AtkAttributeSet * +atk_object_get_attributes (AtkObject *accessible) +{ + AtkObjectClass *klass; + + g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL); + + klass = ATK_OBJECT_GET_CLASS (accessible); + if (klass->get_attributes) + return (klass->get_attributes) (accessible); + else + return NULL; + +} + static AtkRelationSet* atk_object_real_ref_relation_set (AtkObject *accessible) { @@ -819,6 +1319,14 @@ atk_object_real_set_property (GObject *object, if (ATK_IS_VALUE (accessible)) atk_value_set_current_value (ATK_VALUE (accessible), value); break; + case PROP_TABLE_SUMMARY: + if (ATK_IS_TABLE (accessible)) + atk_table_set_summary (ATK_TABLE (accessible), g_value_get_object (value)); + break; + case PROP_TABLE_CAPTION_OBJECT: + if (ATK_IS_TABLE (accessible)) + atk_table_set_caption (ATK_TABLE (accessible), g_value_get_object (value)); + break; default: break; } @@ -841,9 +1349,18 @@ atk_object_real_get_property (GObject *object, break; case PROP_DESCRIPTION: g_value_set_string (value, atk_object_get_description (accessible)); + break; case PROP_ROLE: g_value_set_int (value, atk_object_get_role (accessible)); break; + case PROP_LAYER: + if (ATK_IS_COMPONENT (accessible)) + g_value_set_int (value, atk_component_get_layer (ATK_COMPONENT (accessible))); + break; + case PROP_MDI_ZORDER: + if (ATK_IS_COMPONENT (accessible)) + g_value_set_int (value, atk_component_get_mdi_zorder (ATK_COMPONENT (accessible))); + break; case PROP_PARENT: g_value_set_object (value, atk_object_get_parent (accessible)); break; @@ -851,6 +1368,18 @@ atk_object_real_get_property (GObject *object, if (ATK_IS_VALUE (accessible)) atk_value_get_current_value (ATK_VALUE (accessible), value); break; + case PROP_TABLE_SUMMARY: + if (ATK_IS_TABLE (accessible)) + g_value_set_object (value, atk_table_get_summary (ATK_TABLE (accessible))); + break; + case PROP_TABLE_CAPTION_OBJECT: + if (ATK_IS_TABLE (accessible)) + g_value_set_object (value, atk_table_get_caption (ATK_TABLE (accessible))); + break; + case PROP_HYPERTEXT_NUM_LINKS: + if (ATK_IS_HYPERTEXT (accessible)) + g_value_set_int (value, atk_hypertext_get_n_links (ATK_HYPERTEXT (accessible))); + break; default: G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec); break; @@ -881,13 +1410,13 @@ atk_object_finalize (GObject *object) G_OBJECT_CLASS (parent_class)->finalize (object); } -static G_CONST_RETURN gchar* +static const gchar* atk_object_real_get_name (AtkObject *object) { return object->name; } -static G_CONST_RETURN gchar* +static const gchar* atk_object_real_get_description (AtkObject *object) { return object->description; @@ -896,7 +1425,7 @@ atk_object_real_get_description (AtkObject *object) static AtkObject* atk_object_real_get_parent (AtkObject *object) { - return object->accessible_parent; + return atk_object_peek_parent (object); } static AtkRole @@ -905,27 +1434,23 @@ atk_object_real_get_role (AtkObject *object) return object->role; } +static AtkLayer +atk_object_real_get_layer (AtkObject *object) +{ + return object->layer; +} + static AtkStateSet* atk_object_real_ref_state_set (AtkObject *accessible) { AtkStateSet *state_set; - AtkObject *ap; + AtkObject *focus_object; state_set = atk_state_set_new (); - ap = atk_object_get_parent (accessible); - if (ap) - if (ATK_IS_SELECTION (ap)) - { - int i; - - atk_state_set_add_state (state_set, ATK_STATE_SELECTABLE); - - i = atk_object_get_index_in_parent (accessible); - if (i >= 0) - if (atk_selection_is_child_selected(ATK_SELECTION (ap), i)) - atk_state_set_add_state (state_set, ATK_STATE_SELECTED); - } + focus_object = atk_get_focus_object (); + if (focus_object == accessible) + atk_state_set_add_state (state_set, ATK_STATE_FOCUSED); return state_set; } @@ -965,24 +1490,27 @@ atk_object_real_set_role (AtkObject *object, object->role = role; } -static guint -atk_object_real_connect_property_change_handler (AtkObject *obj, - AtkPropertyChangeHandler *handler) +/** + * atk_object_initialize: + * @accessible: a #AtkObject + * @data: a #gpointer which identifies the object for which the AtkObject was created. + * + * This function is called when implementing subclasses of #AtkObject. + * It does initialization required for the new object. It is intended + * that this function should called only in the ..._new() functions used + * to create an instance of a subclass of #AtkObject + **/ +void +atk_object_initialize (AtkObject *accessible, + gpointer data) { - return g_signal_connect_closure_by_id (obj, - atk_object_signals[PROPERTY_CHANGE], - 0, - g_cclosure_new ( - G_CALLBACK (handler), NULL, - (GClosureNotify) NULL), - FALSE); -} + AtkObjectClass *klass; -static void -atk_object_real_remove_property_change_handler (AtkObject *obj, - guint handler_id) -{ - g_signal_handler_disconnect (obj, handler_id); + g_return_if_fail (ATK_IS_OBJECT (accessible)); + + klass = ATK_OBJECT_GET_CLASS (accessible); + if (klass->initialize) + klass->initialize (accessible, data); } /* @@ -997,7 +1525,7 @@ static void atk_object_notify (GObject *obj, GParamSpec *pspec) { - AtkPropertyValues values = { 0, }; + AtkPropertyValues values = { NULL, }; g_value_init (&values.new_value, pspec->value_type); g_object_get_property (obj, pspec->name, &values.new_value); @@ -1005,4 +1533,186 @@ atk_object_notify (GObject *obj, g_signal_emit (obj, atk_object_signals[PROPERTY_CHANGE], g_quark_from_string (pspec->name), &values, NULL); + g_value_unset (&values.new_value); +} + +/** + * atk_role_get_name: + * @role: The #AtkRole whose name is required + * + * Gets the description string describing the #AtkRole @role. + * + * Returns: the string describing the AtkRole + */ +const gchar* +atk_role_get_name (AtkRole role) +{ + g_return_val_if_fail (role >= 0, NULL); + + if (!role_names) + initialize_role_names (); + + if (role < role_names->len) + return g_ptr_array_index (role_names, role); + + return NULL; +} + +/** + * atk_role_get_localized_name: + * @role: The #AtkRole whose localized name is required + * + * Gets the localized description string describing the #AtkRole @role. + * + * Returns: the localized string describing the AtkRole + **/ +const gchar* +atk_role_get_localized_name (AtkRole role) +{ + _gettext_initialization (); + + return dgettext (GETTEXT_PACKAGE, atk_role_get_name (role)); +} + +static const gchar* +atk_object_real_get_object_locale (AtkObject *object) +{ + return setlocale (LC_MESSAGES, NULL); +} + +/** + * atk_object_get_object_locale: + * @accessible: an #AtkObject + * + * Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale + * of @accessible. + * + * Since: 2.8 + * + * Returns: a UTF-8 string indicating the POSIX-style LC_MESSAGES + * locale of @accessible. + **/ +const gchar* +atk_object_get_object_locale (AtkObject *accessible) +{ + AtkObjectClass *klass; + + g_return_val_if_fail (ATK_IS_OBJECT (accessible), NULL); + + klass = ATK_OBJECT_GET_CLASS (accessible); + if (klass->get_object_locale) + return (klass->get_object_locale) (accessible); + else + return NULL; +} + + +/** + * atk_role_for_name: + * @name: a string which is the (non-localized) name of an ATK role. + * + * Get the #AtkRole type corresponding to a rolew name. + * + * Returns: the #AtkRole enumerated type corresponding to the specified name, + * or #ATK_ROLE_INVALID if no matching role is found. + **/ +AtkRole +atk_role_for_name (const gchar *name) +{ + AtkRole role = ATK_ROLE_INVALID; + gint i; + + g_return_val_if_fail (name, ATK_ROLE_INVALID); + + if (!role_names) + initialize_role_names (); + + for (i = 0; i < role_names->len; i++) + { + gchar *role_name = (gchar *)g_ptr_array_index (role_names, i); + + g_return_val_if_fail (role_name, ATK_ROLE_INVALID); + + if (strcmp (name, role_name) == 0) + { + role = i; + break; + } + } + + return role; +} + +/** + * atk_object_add_relationship: + * @object: The #AtkObject to which an AtkRelation is to be added. + * @relationship: The #AtkRelationType of the relation + * @target: The #AtkObject which is to be the target of the relation. + * + * Adds a relationship of the specified type with the specified target. + * + * Returns: TRUE if the relationship is added. + **/ +gboolean +atk_object_add_relationship (AtkObject *object, + AtkRelationType relationship, + AtkObject *target) +{ + AtkObject *array[1]; + AtkRelation *relation; + + g_return_val_if_fail (ATK_IS_OBJECT (object), FALSE); + g_return_val_if_fail (ATK_IS_OBJECT (target), FALSE); + + if (atk_relation_set_contains_target (object->relation_set, + relationship, target)) + return FALSE; + + array[0] = target; + relation = atk_relation_new (array, 1, relationship); + atk_relation_set_add (object->relation_set, relation); + g_object_unref (relation); + + return TRUE; +} + +/** + * atk_object_remove_relationship: + * @object: The #AtkObject from which an AtkRelation is to be removed. + * @relationship: The #AtkRelationType of the relation + * @target: The #AtkObject which is the target of the relation to be removed. + * + * Removes a relationship of the specified type with the specified target. + * + * Returns: TRUE if the relationship is removed. + **/ +gboolean +atk_object_remove_relationship (AtkObject *object, + AtkRelationType relationship, + AtkObject *target) +{ + gboolean ret = FALSE; + AtkRelation *relation; + GPtrArray *array; + + g_return_val_if_fail (ATK_IS_OBJECT (object), FALSE); + g_return_val_if_fail (ATK_IS_OBJECT (target), FALSE); + + relation = atk_relation_set_get_relation_by_type (object->relation_set, relationship); + + if (relation) + { + ret = atk_relation_remove_target (relation, target); + array = atk_relation_get_target (relation); + if (!array || array->len == 0) + atk_relation_set_remove (object->relation_set, relation); + } + return ret; +} + +static void +atk_object_real_initialize (AtkObject *accessible, + gpointer data) +{ + return; }