* Boston, MA 02111-1307, USA.
*/
+#include "config.h"
+
#include <string.h>
#include <locale.h>
#include <glib-object.h>
-
-#ifdef G_OS_WIN32
-#define STRICT
-#include <windows.h>
-#undef STRICT
-#undef FOCUS_EVENT /* <windows.h> pollutes the namespace
- * like a six hundred pound gorilla */
-#endif
+#include <glib/gi18n-lib.h>
#include "atk.h"
#include "atkmarshal.h"
-#include "atk-enum-types.h"
-#include "atkintl.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;
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);
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
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";
-#ifdef G_OS_WIN32
-
-static HMODULE atk_dll;
-
-BOOL WINAPI
-DllMain (HINSTANCE hinstDLL,
- DWORD fdwReason,
- LPVOID lpvReserved)
-{
- switch (fdwReason)
- {
- case DLL_PROCESS_ATTACH:
- atk_dll = (HMODULE) hinstDLL;
- break;
- }
-
- return TRUE;
-}
-
-static const char *
-get_atk_locale_dir (void)
-{
- static gchar *atk_localedir = NULL;
-
- if (!atk_localedir)
- {
- const gchar *p;
- gchar *root, *temp;
-
- /* ATK_LOCALEDIR might end in either /lib/locale or
- * /share/locale. Scan for that slash.
- */
- p = ATK_LOCALEDIR + strlen (ATK_LOCALEDIR);
- while (*--p != '/')
- ;
- while (*--p != '/')
- ;
-
- root = g_win32_get_package_installation_directory_of_module (atk_dll);
- temp = g_build_filename (root, p, NULL);
- g_free (root);
-
- /* atk_localedir is passed to bindtextdomain() which isn't
- * UTF-8-aware.
- */
- atk_localedir = g_win32_locale_filename_from_utf8 (temp);
- g_free (temp);
- }
- return atk_localedir;
-}
-
-#undef ATK_LOCALEDIR
-
-#define ATK_LOCALEDIR get_atk_locale_dir()
-
-#endif
-
-static void
-gettext_initialization (void)
-{
-#ifdef ENABLE_NLS
- static gboolean gettext_initialized = FALSE;
-
- if (!gettext_initialized)
- {
- const char *dir = g_getenv ("ATK_ALT_LOCALEDIR");
-
- gettext_initialized = TRUE;
- if (dir == NULL)
- dir = ATK_LOCALEDIR;
-
- bindtextdomain (GETTEXT_PACKAGE, dir);
-#ifdef HAVE_BIND_TEXTDOMAIN_CODESET
- bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8");
-#endif
- }
-#endif
-}
-
-static void
-compact_role_name (gchar *role_name)
-{
- gchar *p = role_name;
-
- while (*p)
- {
- if (*p == '-')
- *p = ' ';
- p++;
- }
-}
-
static void
initialize_role_names ()
{
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_role_name (role_name);
+ _compact_name (role_name);
g_ptr_array_add (role_names, role_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;
/*
klass->visible_data_changed = NULL;
klass->active_descendant_changed = NULL;
- gettext_initialization ();
+ _gettext_initialization ();
g_object_class_install_property (gobject_class,
PROP_NAME,
PROP_PARENT,
g_param_spec_object (atk_object_name_property_parent,
_("Accessible Parent"),
- _("Is used to notify that the parent has changed"),
+ _("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,
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,
_("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,
_("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,
_("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,
_("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,
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",
G_TYPE_FROM_CLASS (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 #AtkObject::state-change signal instead.
+ */
atk_object_signals[FOCUS_EVENT] =
g_signal_new ("focus_event",
G_TYPE_FROM_CLASS (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),
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_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),
(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),
* 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.
*
- * Returns: (transfer none): a #AtkObject representing the accessible parent
- * of the accessible
+ * If you are only interested on the parent assigned with
+ * atk_object_set_parent(), use atk_object_peek_parent().
+ *
+ * Returns: (transfer none): an #AtkObject representing the accessible
+ * parent of the accessible
**/
AtkObject*
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
*
* 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.
*
- * Returns: an #AtkRole for the new role.
+ * 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 if added
+ * properly. ATK_ROLE_INVALID in case of error.
**/
AtkRole
atk_role_register (const gchar *name)
{
+ 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 ();
* @accessible: an #AtkObject
* @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,
* @accessible: an #AtkObject
* @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()
* atk_object_remove_property_change_handler:
* @accessible: an #AtkObject
* @handler_id: a guint which identifies the handler to be removed.
- *
+ *
+ * Deprecated: Since 2.12.
+ *
* Removes a property change handler.
**/
void
* @state: an #AtkState whose state is changed
* @value: a gboolean which indicates whether the state is being set on or off
*
- * Emits a state-change signal for the specified state.
+ * 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,
static AtkObject*
atk_object_real_get_parent (AtkObject *object)
{
- return object->accessible_parent;
+ return atk_object_peek_parent (object);
}
static AtkRole
object->role = role;
}
-static guint
-atk_object_real_connect_property_change_handler (AtkObject *obj,
- AtkPropertyChangeHandler *handler)
-{
- return g_signal_connect_closure_by_id (obj,
- atk_object_signals[PROPERTY_CHANGE],
- 0,
- g_cclosure_new (
- G_CALLBACK (handler), NULL,
- (GClosureNotify) NULL),
- FALSE);
-}
-
-static void
-atk_object_real_remove_property_change_handler (AtkObject *obj,
- guint handler_id)
-{
- g_signal_handler_disconnect (obj, handler_id);
-}
-
/**
* atk_object_initialize:
* @accessible: a #AtkObject
const gchar*
atk_role_get_localized_name (AtkRole role)
{
- gettext_initialization ();
+ _gettext_initialization ();
return dgettext (GETTEXT_PACKAGE, atk_role_get_name (role));
}
* Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale
* of @accessible.
*
- * Since: 2.7.90
+ * Since: 2.8
*
* Returns: a UTF-8 string indicating the POSIX-style LC_MESSAGES
* locale of @accessible.
*
* Adds a relationship of the specified type with the specified target.
*
- * Returns TRUE if the relationship is added.
+ * Returns: TRUE if the relationship is added.
**/
gboolean
atk_object_add_relationship (AtkObject *object,
*
* Removes a relationship of the specified type with the specified target.
*
- * Returns TRUE if the relationship is removed.
+ * Returns: TRUE if the relationship is removed.
**/
gboolean
atk_object_remove_relationship (AtkObject *object,