atspi/atspi-accessible.c

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001, 2002 Sun Microsystems Inc.,
   6  * Copyright 2001, 2002 Ximian, Inc.
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 #include "atspi-private.h"
  25 #include <string.h>
  26
  27 static void
  28 atspi_action_interface_init (AtspiAction *action)
  29 {
  30 }
  31
  32 static void
  33 atspi_collection_interface_init (AtspiCollection *component)
  34 {
  35 }
  36
  37 static void
  38 atspi_component_interface_init (AtspiComponent *component)
  39 {
  40 }
  41
  42 static void
  43 atspi_document_interface_init (AtspiDocument *document)
  44 {
  45 }
  46
  47 static void
  48 atspi_editable_text_interface_init (AtspiEditableText *editable_text)
  49 {
  50 }
  51
  52 static void
  53 atspi_hypertext_interface_init (AtspiHypertext *hypertext)
  54 {
  55 }
  56
  57 static void
  58 atspi_image_interface_init (AtspiImage *image)
  59 {
  60 }
  61
  62 static void
  63 atspi_selection_interface_init (AtspiSelection *selection)
  64 {
  65 }
  66
  67 static void
  68 atspi_table_interface_init (AtspiTable *table)
  69 {
  70 }
  71
  72 static void
  73 atspi_text_interface_init (AtspiText *text)
  74 {
  75 }
  76
  77 static void
  78 atspi_value_interface_init (AtspiValue *value)
  79 {
  80 }
  81
  82 G_DEFINE_TYPE_WITH_CODE (AtspiAccessible, atspi_accessible, ATSPI_TYPE_OBJECT,
  83                          G_IMPLEMENT_INTERFACE (ATSPI_TYPE_ACTION, atspi_action_interface_init)
  84                          G_IMPLEMENT_INTERFACE (ATSPI_TYPE_COLLECTION, atspi_collection_interface_init)
  85                          G_IMPLEMENT_INTERFACE (ATSPI_TYPE_COMPONENT, atspi_component_interface_init)
  86                          G_IMPLEMENT_INTERFACE (ATSPI_TYPE_DOCUMENT, atspi_document_interface_init)
  87                          G_IMPLEMENT_INTERFACE (ATSPI_TYPE_EDITABLE_TEXT, atspi_editable_text_interface_init)
  88                          G_IMPLEMENT_INTERFACE (ATSPI_TYPE_HYPERTEXT, atspi_hypertext_interface_init)
  89                          G_IMPLEMENT_INTERFACE (ATSPI_TYPE_IMAGE, atspi_image_interface_init)
  90                          G_IMPLEMENT_INTERFACE (ATSPI_TYPE_SELECTION, atspi_selection_interface_init)
  91                          G_IMPLEMENT_INTERFACE (ATSPI_TYPE_TABLE, atspi_table_interface_init)
  92                          G_IMPLEMENT_INTERFACE (ATSPI_TYPE_TEXT, atspi_text_interface_init)
  93                          G_IMPLEMENT_INTERFACE (ATSPI_TYPE_VALUE, atspi_value_interface_init))
  94
  95 #ifdef DEBUG_REF_COUNTS
  96 static gint accessible_count = 0;
  97 #endif
  98
  99 static void
 100 atspi_accessible_init (AtspiAccessible *accessible)
 101 {
 102 #ifdef DEBUG_REF_COUNTS
 103   accessible_count++;
 104   printf("at-spi: init: %d objects\n", accessible_count);
 105 #endif
 106 }
 107
 108 static void
 109 atspi_accessible_dispose (GObject *object)
 110 {
 111   AtspiAccessible *accessible = ATSPI_ACCESSIBLE (object);
 112   AtspiEvent e;
 113   AtspiAccessible *parent;
 114
 115   /* TODO: Only fire if object not already marked defunct */
 116   memset (&e, 0, sizeof (e));
 117   e.type = "object:state-change:defunct";
 118   e.source = accessible;
 119   e.detail1 = 1;
 120   e.detail2 = 0;
 121   _atspi_send_event (&e);
 122
 123   if (accessible->states)
 124   {
 125     g_object_unref (accessible->states);
 126     accessible->states = NULL;
 127   }
 128
 129   parent = accessible->accessible_parent;
 130   if (parent && parent->children)
 131   {
 132     GList*ls = g_list_find (parent->children, accessible);
 133     if(ls)
 134     {
 135       gboolean replace = (ls == parent->children);
 136       ls = g_list_remove (ls, accessible);
 137       if (replace)
 138         parent->children = ls;
 139       g_object_unref (object);
 140     }
 141   }
 142
 143   if (parent)
 144   {
 145     g_object_unref (parent);
 146     accessible->accessible_parent = NULL;
 147   }
 148
 149   G_OBJECT_CLASS (atspi_accessible_parent_class) ->dispose (object);
 150 }
 151
 152 static void
 153 atspi_accessible_finalize (GObject *object)
 154 {
 155   AtspiAccessible *accessible = ATSPI_ACCESSIBLE (object);
 156
 157     g_free (accessible->description);
 158     g_free (accessible->name);
 159
 160 #ifdef DEBUG_REF_COUNTS
 161   accessible_count--;
 162   printf("at-spi: finalize: %d objects\n", accessible_count);
 163 #endif
 164
 165   G_OBJECT_CLASS (atspi_accessible_parent_class)
 166     ->finalize (object);
 167 }
 168
 169 static void
 170 atspi_accessible_class_init (AtspiAccessibleClass *klass)
 171 {
 172   GObjectClass *object_class = G_OBJECT_CLASS (klass);
 173
 174   object_class->dispose = atspi_accessible_dispose;
 175   object_class->finalize = atspi_accessible_finalize;
 176 }
 177
 178 /* TODO: Generate following from spec? */
 179 static const char *role_names [] =
 180 {
 181   "invalid",
 182   "accel-label",
 183   "alert",
 184   "animation",
 185   "arrow",
 186   "calendar",
 187   "canvas",
 188   "check-box",
 189   "check-menu-item",
 190   "color-chooser",
 191   "column-header",
 192   "combo-box",
 193   "date-editor",
 194   "desktop-icon",
 195   "desktop-frame",
 196   "dial",
 197   "dialog",
 198   "directory-pane",
 199   "drawing-area",
 200   "file-chooser",
 201   "filler",
 202   "font-chooser",
 203   "frame",
 204   "glass-pane",
 205   "html-container",
 206   "icon",
 207   "image",
 208   "internalframe",
 209   "label",
 210   "layered-pane",
 211   "list",
 212   "list-item",
 213   "menu",
 214   "menu-bar",
 215   "menu-item",
 216   "option-pane",
 217   "page-tab",
 218   "page-tab-list",
 219   "panel",
 220   "password-text",
 221   "popup-menu",
 222   "progress-bar",
 223   "push-button",
 224   "radio-button",
 225   "radio-menu-item",
 226   "root-pane",
 227   "row-header",
 228   "scroll-bar",
 229   "scroll-pane",
 230   "separator",
 231   "slider",
 232   "spin-button",
 233   "split-pane",
 234   "statusbar",
 235   "table",
 236   "table-cell",
 237   "table-column-header",
 238   "table-row-header",
 239   "tear-off-menu-item",
 240   "terminal",
 241   "text",
 242   "toggle-button",
 243   "tool-bar",
 244   "tool-tip",
 245   "tree",
 246   "tree-table",
 247   "unknown",
 248   "viewport",
 249   "window",
 250   NULL,
 251   "header",
 252   "fooler",
 253   "paragraph",
 254   "ruler",
 255   "application",
 256   "autocomplete",
 257   "editbar",
 258   "embedded",
 259   "entry",
 260   "chart",
 261   "caption",
 262   "document_frame",
 263   "heading",
 264   "page",
 265   "section",
 266   "form",
 267   "redundant object",
 268   "link",
 269   "input method window"
 270 };
 271
 272 #define MAX_ROLES (sizeof (role_names) / sizeof (char *))
 273
 274 /**
 275  * atspi_role_get_name
 276  * @role: an #AtspiAccessibleRole object to query.
 277  *
 278  * Get a localizeable string that indicates the name of an #AtspiAccessibleRole.
 279  * <em>DEPRECATED.</em>
 280  *
 281  * Returns: a localizable string name for an #AtspiAccessibleRole enumerated type.
 282  **/
 283 gchar *
 284 atspi_role_get_name (AtspiRole role)
 285 {
 286   if (role < MAX_ROLES && role_names [(int) role])
 287     {
 288       return g_strdup (role_names [(int) role]);
 289     }
 290   else
 291     {
 292       return g_strdup ("");
 293     }
 294 }
 295
 296 /**
 297  * atspi_accessible_get_name:
 298  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 299  *
 300  * Get the name of an #AtspiAccessible object.
 301  *
 302  * Returns: a UTF-8 string indicating the name of the #AtspiAccessible object.
 303  * or NULL on exception
 304  **/
 305 gchar *
 306 atspi_accessible_get_name (AtspiAccessible *obj, GError **error)
 307 {
 308   g_return_val_if_fail (obj != NULL, g_strdup (""));
 309   if (!(obj->cached_properties & ATSPI_CACHE_NAME))
 310   {
 311     if (!_atspi_dbus_get_property (obj, atspi_interface_accessible, "Name", error,
 312                                    "s", &obj->name))
 313       return g_strdup ("");
 314     obj->cached_properties |= ATSPI_CACHE_NAME;
 315   }
 316   return g_strdup (obj->name);
 317 }
 318
 319 /**
 320  * atspi_accessible_get_description:
 321  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 322  *
 323  * Get the description of an #AtspiAccessible object.
 324  *
 325  * Returns: a UTF-8 string describing the #AtspiAccessible object.
 326  * or NULL on exception
 327  **/
 328 gchar *
 329 atspi_accessible_get_description (AtspiAccessible *obj, GError **error)
 330 {
 331   g_return_val_if_fail (obj != NULL, g_strdup (""));
 332
 333   if (!(obj->cached_properties & ATSPI_CACHE_DESCRIPTION))
 334   {
 335     if (!_atspi_dbus_get_property (obj, atspi_interface_accessible,
 336                                    "Description", error, "s",
 337                                    &obj->description))
 338       return g_strdup ("");
 339     obj->cached_properties |= ATSPI_CACHE_DESCRIPTION;
 340   }
 341   return g_strdup (obj->description);
 342 }
 343
 344 const char *str_parent = "Parent";
 345
 346 /**
 347  * atspi_accessible_get_parent:
 348  * @obj: a pointer to the #AtspiAccessible object to query.
 349  *
 350  * Get an #AtspiAccessible object's parent container.
 351  *
 352  * Returns: (transfer full): a pointer to the #AtspiAccessible object which
 353  *          contains the given #AtspiAccessible instance, or NULL if the @obj
 354  *          has no parent container.
 355  *
 356  **/
 357 AtspiAccessible *
 358 atspi_accessible_get_parent (AtspiAccessible *obj, GError **error)
 359 {
 360   g_return_val_if_fail (obj != NULL, NULL);
 361
 362   if (obj->parent.app && !(obj->cached_properties & ATSPI_CACHE_PARENT))
 363   {
 364     DBusMessage *message, *reply;
 365     DBusMessageIter iter, iter_variant;
 366     message = dbus_message_new_method_call (obj->parent.app->bus_name,
 367                                             obj->parent.path,
 368                                             DBUS_INTERFACE_PROPERTIES, "Get");
 369     if (!message)
 370       return NULL;
 371     dbus_message_append_args (message, DBUS_TYPE_STRING, &atspi_interface_accessible,
 372                                DBUS_TYPE_STRING, &str_parent,
 373                               DBUS_TYPE_INVALID);
 374     reply = _atspi_dbus_send_with_reply_and_block (message, error);
 375     if (!reply)
 376       return NULL;
 377     if (strcmp (dbus_message_get_signature (reply), "v") != 0)
 378     {
 379       dbus_message_unref (reply);
 380       return NULL;
 381     }
 382     dbus_message_iter_init (reply, &iter);
 383     dbus_message_iter_recurse (&iter, &iter_variant);
 384     obj->accessible_parent = _atspi_dbus_return_accessible_from_iter (&iter_variant);
 385     dbus_message_unref (reply);
 386     obj->cached_properties |= ATSPI_CACHE_PARENT;
 387   }
 388   if (!obj->accessible_parent)
 389     return NULL;
 390   return g_object_ref (obj->accessible_parent);
 391 }
 392
 393 /**
 394  * atspi_accessible_get_child_count:
 395  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 396  *
 397  * Get the number of children contained by an #AtspiAccessible object.
 398  *
 399  * Returns: a #long indicating the number of #AtspiAccessible children
 400  *          contained by an #AtspiAccessible object. or -1 on exception
 401  *
 402  **/
 403 gint
 404 atspi_accessible_get_child_count (AtspiAccessible *obj, GError **error)
 405 {
 406   g_return_val_if_fail (obj != NULL, -1);
 407
 408   if (!(obj->cached_properties & ATSPI_CACHE_CHILDREN))
 409   {
 410     dbus_int32_t ret;
 411     if (!_atspi_dbus_get_property (obj, atspi_interface_accessible,
 412                                    "ChildCount", error, "i", &ret))
 413       return -1;
 414     return ret;
 415   }
 416
 417   return g_list_length (obj->children);
 418 }
 419
 420 /**
 421  * atspi_accessible_get_child_at_index:
 422  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 423  * @child_index: a #long indicating which child is specified.
 424  *
 425  * Get the #AtspiAccessible child of an #AtspiAccessible object at a given index.
 426  *
 427  * Returns: (transfer full): a pointer to the #AtspiAccessible child object at
 428  * index @child_index. or NULL on exception
 429  **/
 430 AtspiAccessible *
 431 atspi_accessible_get_child_at_index (AtspiAccessible *obj,
 432                             gint    child_index,
 433                             GError **error)
 434 {
 435   AtspiAccessible *child;
 436
 437   g_return_val_if_fail (obj != NULL, NULL);
 438
 439   if (!(obj->cached_properties & ATSPI_CACHE_CHILDREN))
 440   {
 441     DBusMessage *reply;
 442     reply = _atspi_dbus_call_partial (obj, atspi_interface_accessible,
 443                                      "GetChildAtIndex", error, "i",
 444                                      child_index);
 445     return _atspi_dbus_return_accessible_from_message (reply);
 446   }
 447
 448   child = g_list_nth_data (obj->children, child_index);
 449   if (!child)
 450     return NULL;
 451   return g_object_ref (child);
 452 }
 453
 454 /**
 455  * atspi_accessible_get_index_in_parent
 456  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 457  *
 458  * Get the index of an #AtspiAccessible object in its containing #AtspiAccessible.
 459  *
 460  * Returns: a #glong indicating the index of the #AtspiAccessible object
 461  *          in its parent (i.e. containing) #AtspiAccessible instance,
 462  *          or -1 if @obj has no containing parent or on exception.
 463  **/
 464 gint
 465 atspi_accessible_get_index_in_parent (AtspiAccessible *obj, GError **error)
 466 {
 467   GList *l;
 468   gint i = 0;
 469
 470   g_return_val_if_fail (obj != NULL, -1);
 471   if (!obj->accessible_parent) return -1;
 472   if (!(obj->accessible_parent->cached_properties & ATSPI_CACHE_CHILDREN))
 473   {
 474     dbus_uint32_t ret = -1;
 475     _atspi_dbus_call (obj, atspi_interface_accessible,
 476                       "GetIndexInParent", NULL, "=>u", &ret);
 477     return ret;
 478   }
 479
 480   l = obj->accessible_parent->children;
 481   while (l)
 482   {
 483     if (l->data == obj) return i;
 484     l = g_list_next (l);
 485     i++;
 486   }
 487   return -1;
 488 }
 489
 490 typedef struct
 491 {
 492   dbus_uint32_t type;
 493   GArray *targets;
 494 } Accessibility_Relation;
 495
 496 /**
 497  * atspi_accessible_get_relation_set:
 498  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 499  *
 500  * Get the set of #AtspiRelation objects which describe this #AtspiAccessible object's
 501  *       relationships with other #AtspiAccessible objects.
 502  *
 503  * Returns: (element-type AtspiAccessible*) (transfer full): an array of
 504  *          #AtspiAccessibleRelation pointers. or NULL on exception
 505  **/
 506 GArray *
 507 atspi_accessible_get_relation_set (AtspiAccessible *obj, GError **error)
 508 {
 509   DBusMessage *reply;
 510   DBusMessageIter iter, iter_array;
 511   GArray *ret;
 512
 513   g_return_val_if_fail (obj != NULL, NULL);
 514
 515   reply = _atspi_dbus_call_partial (obj, atspi_interface_accessible, "GetRelationSet", error, "");
 516   if (!reply)
 517     return NULL;
 518   _ATSPI_DBUS_CHECK_SIG (reply, "a(ua(so))", error, NULL);
 519
 520   ret = g_array_new (TRUE, TRUE, sizeof (AtspiRelation *));
 521   dbus_message_iter_init (reply, &iter);
 522   dbus_message_iter_recurse (&iter, &iter_array);
 523   while (dbus_message_iter_get_arg_type (&iter_array) != DBUS_TYPE_INVALID)
 524   {
 525     GArray *new_array;
 526     AtspiRelation *relation;
 527     relation = _atspi_relation_new_from_iter (&iter_array);
 528     new_array = g_array_append_val (ret, relation);
 529     if (new_array)
 530       ret = new_array;
 531     dbus_message_iter_next (&iter_array);
 532   }
 533   dbus_message_unref (reply);
 534   return ret;
 535 }
 536
 537 /**
 538  * atspi_accessible_get_role:
 539  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 540  *
 541  * Get the UI role of an #AtspiAccessible object.
 542  * A UTF-8 string describing this role can be obtained via atspi_accessible_getRoleName ().
 543  *
 544  * Returns: the #AtspiRole of the object.
 545  *
 546  **/
 547 AtspiRole
 548 atspi_accessible_get_role (AtspiAccessible *obj, GError **error)
 549 {
 550   g_return_val_if_fail (obj != NULL, ATSPI_ROLE_INVALID);
 551
 552   if (!(obj->cached_properties & ATSPI_CACHE_ROLE))
 553   {
 554     dbus_uint32_t role;
 555     /* TODO: Make this a property */
 556     if (_atspi_dbus_call (obj, atspi_interface_accessible, "GetRole", error, "=>u", &role))
 557     {
 558       obj->cached_properties |= ATSPI_CACHE_ROLE;
 559       obj->role = role;
 560     }
 561   }
 562   return obj->role;
 563 }
 564
 565 /**
 566  * atspi_accessible_get_role_name:
 567  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 568  *
 569  * Get a UTF-8 string describing the role this object plays in the UI.
 570  * This method will return useful values for roles that fall outside the
 571  * enumeration used in atspi_accessible_getRole ().
 572  *
 573  * Returns: a UTF-8 string specifying the role of this #AtspiAccessible object.
 574  *
 575  **/
 576 gchar *
 577 atspi_accessible_get_role_name (AtspiAccessible *obj, GError **error)
 578 {
 579   char *retval = NULL;
 580
 581   g_return_val_if_fail (obj != NULL, NULL);
 582
 583   _atspi_dbus_call (obj, atspi_interface_accessible, "GetRoleName", error, "=>s", &retval);
 584
 585   if (!retval)
 586     retval = g_strdup ("");
 587
 588   return retval;
 589 }
 590
 591 /**
 592  * atspi_accessible_get_localized_role_name:
 593  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 594  *
 595  * Get a UTF-8 string describing the (localized) role this object plays in the UI.
 596  * This method will return useful values for roles that fall outside the
 597  * enumeration used in atspi_accessible_getRole ().
 598  *
 599  * Returns: a UTF-8 string specifying the role of this #AtspiAccessible object.
 600  *
 601  **/
 602 gchar *
 603 atspi_accessible_get_localized_role_name (AtspiAccessible *obj, GError **error)
 604 {
 605   char *retval = NULL;
 606
 607   g_return_val_if_fail (obj != NULL, NULL);
 608
 609   _atspi_dbus_call (obj, atspi_interface_accessible, "GetLocalizedRoleName", error, "=>s", &retval);
 610
 611   if (!retval)
 612     return g_strdup ("");
 613
 614   return retval;
 615 }
 616
 617 static AtspiStateSet *
 618 defunct_set ()
 619 {
 620   AtspiStateSet *set = atspi_state_set_new (NULL);
 621   atspi_state_set_add (set, ATSPI_STATE_DEFUNCT);
 622   return set;
 623 }
 624
 625 /**
 626  * atspi_accessible_get_state_set:
 627  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 628  *
 629  * Gets the current state of an object.
 630  *
 631  * Returns: (transfer full): a pointer to an #AtspiStateSet representing the
 632  *          object's current state.
 633  **/
 634 AtspiStateSet *
 635 atspi_accessible_get_state_set (AtspiAccessible *obj)
 636 {
 637   if (!obj->parent.app || !obj->parent.app->bus)
 638     return defunct_set ();
 639
 640
 641   if (!(obj->cached_properties & ATSPI_CACHE_STATES))
 642   {
 643     DBusMessage *reply;
 644     DBusMessageIter iter;
 645     reply = _atspi_dbus_call_partial (obj, atspi_interface_accessible,
 646                                       "GetState", NULL, "");
 647     _ATSPI_DBUS_CHECK_SIG (reply, "au", NULL, defunct_set ());
 648     dbus_message_iter_init (reply, &iter);
 649     _atspi_dbus_set_state (obj, &iter);
 650     dbus_message_unref (reply);
 651   }
 652
 653   return g_object_ref (obj->states);
 654 }
 655
 656 /**
 657  * atspi_accessible_get_attributes:
 658  * @obj: The #AtspiAccessible being queried.
 659  *
 660  * Get the #AttributeSet representing any assigned
 661  * name-value pair attributes or annotations for this object.
 662  * For typographic, textual, or textually-semantic attributes, see
 663  * atspi_text_get_attributes instead.
 664  *
 665  * Returns: (element-type gchar* gchar*) (transfer full): The name-value-pair
 666  *          attributes assigned to this object.
 667  */
 668 GHashTable *
 669 atspi_accessible_get_attributes (AtspiAccessible *obj, GError **error)
 670 {
 671   DBusMessage *message;
 672
 673     g_return_val_if_fail (obj != NULL, NULL);
 674
 675   message = _atspi_dbus_call_partial (obj, atspi_interface_accessible, "GetAttributes", error, "");
 676   return _atspi_dbus_return_hash_from_message (message);
 677 }
 678
 679 /**
 680  * atspi_accessible_get_attributes_as_array:
 681  * @obj: The #AtspiAccessible being queried.
 682  *
 683  * Get the #AttributeSet representing any assigned
 684  * name-value pair attributes or annotations for this object.
 685  * For typographic, textual, or textually-semantic attributes, see
 686  * atspi_text_get_attributes_as_array instead.
 687  *
 688  * Returns: (element-type gchar*) (transfer full): The name-value-pair
 689  *          attributes assigned to this object.
 690  */
 691 GArray *
 692 atspi_accessible_get_attributes_as_array (AtspiAccessible *obj, GError **error)
 693 {
 694   DBusMessage *message;
 695
 696     g_return_val_if_fail (obj != NULL, NULL);
 697
 698   message = _atspi_dbus_call_partial (obj, atspi_interface_accessible, "GetAttributes", error, "");
 699   return _atspi_dbus_return_attribute_array_from_message (message);
 700 }
 701
 702 /**
 703  * atspi_accessible_get_application:
 704  * @obj: The #AtspiAccessible being queried.
 705  *
 706  * Get the containing #AtspiApplication for an object.
 707  *
 708  * Returns: (transfer full): the containing AtspiApplication instance for
 709  *          this object.
 710  */
 711 AtspiAccessible *
 712 atspi_accessible_get_application (AtspiAccessible *obj, GError **error)
 713 {
 714   AtspiAccessible *parent;
 715
 716   g_object_ref (obj);
 717   for (;;)
 718   {
 719     parent = atspi_accessible_get_parent (obj, NULL);
 720     if (!parent || parent == obj ||
 721         atspi_accessible_get_role (parent, NULL) == ATSPI_ROLE_DESKTOP_FRAME)
 722     return obj;
 723     g_object_unref (obj);
 724     obj = parent;
 725   }
 726 }
 727
 728 /* Application-specific methods */
 729
 730 /**
 731  * atspi_accessible_get_toolkit_name:
 732  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 733  *
 734  * Get the toolkit for a #AtspiAccessible object.
 735  * Only works on application root objects.
 736  *
 737  * Returns: a UTF-8 string indicating the toolkit name for the #AtspiAccessible object.
 738  * or NULL on exception
 739  **/
 740 gchar *
 741 atspi_accessible_get_toolkit_name (AtspiAccessible *obj, GError **error)
 742 {
 743   gchar *ret = NULL;
 744
 745   g_return_val_if_fail (obj != NULL, NULL);
 746
 747   if (!_atspi_dbus_get_property (obj, atspi_interface_application, "ToolkitName", error, "s", &ret))
 748       return NULL;
 749   return g_strdup (ret);
 750 }
 751
 752 /**
 753  * atspi_accessible_get_toolkit_version:
 754  * @obj: a pointer to the #AtspiAccessible object on which to operate.
 755  *
 756  * Get the toolkit version for a #AtspiAccessible object.
 757  * Only works on application root objects.
 758  *
 759  * Returns: a UTF-8 string indicating the toolkit ersion for the #AtspiAccessible object.
 760  * or NULL on exception
 761  **/
 762 gchar *
 763 atspi_accessible_get_toolkit_version (AtspiAccessible *obj, GError **error)
 764 {
 765   gchar *ret = NULL;
 766
 767   g_return_val_if_fail (obj != NULL, NULL);
 768
 769   if (!_atspi_dbus_get_property (obj, atspi_interface_application, "ToolkitVersion", error, "s", &ret))
 770       return NULL;
 771   return g_strdup (ret);
 772 }
 773 /* Interface query methods */
 774
 775 static gboolean
 776 _atspi_accessible_is_a (AtspiAccessible *accessible,
 777                       const char *interface_name)
 778 {
 779   int n;
 780
 781   if (accessible == NULL)
 782     {
 783       return FALSE;
 784     }
 785
 786   if (!(accessible->cached_properties & ATSPI_CACHE_INTERFACES))
 787   {
 788     DBusMessage *reply;
 789     DBusMessageIter iter;
 790     reply = _atspi_dbus_call_partial (accessible, atspi_interface_accessible,
 791                                       "GetInterfaces", NULL, "");
 792     _ATSPI_DBUS_CHECK_SIG (reply, "as", NULL, FALSE);
 793     dbus_message_iter_init (reply, &iter);
 794     _atspi_dbus_set_interfaces (accessible, &iter);
 795     dbus_message_unref (reply);
 796   }
 797
 798   n = _atspi_get_iface_num (interface_name);
 799   if (n == -1) return FALSE;
 800   return (gboolean) ((accessible->interfaces & (1 << n))? TRUE: FALSE);
 801 }
 802
 803 /**
 804  * atspi_accessible_is_action:
 805  * @obj: a pointer to the #AtspiAccessible instance to query.
 806  *
 807  * Query whether the specified #AtspiAccessible implements #AtspiAction.
 808  *
 809  * Returns: #TRUE if @obj implements the #AtspiAction interface,
 810  *          #FALSE otherwise.
 811  **/
 812 gboolean
 813 atspi_accessible_is_action (AtspiAccessible *obj)
 814 {
 815   return _atspi_accessible_is_a (obj,
 816                               atspi_interface_action);
 817 }
 818
 819 /**
 820  * atspi_accessible_is_application:
 821  * @obj: a pointer to the #AtspiAccessible instance to query.
 822  *
 823  * Query whether the specified #AtspiAccessible implements #AtspiApplication.
 824  *
 825  * Returns: #TRUE if @obj implements the #AtspiApplication interface,
 826  *          #FALSE otherwise.
 827  **/
 828 gboolean
 829 atspi_accessible_is_application (AtspiAccessible *obj)
 830 {
 831   return _atspi_accessible_is_a (obj,
 832                               atspi_interface_application);
 833 }
 834
 835 /**
 836  * atspi_accessible_is_collection:                                                                                                                                                                          * @obj: a pointer to the #AtspiAccessible instance to query.
 837  *
 838  * Query whether the specified #AtspiAccessible implements #AtspiCollection.
 839  * Returns: #TRUE if @obj implements the #AtspiCollection interface,
 840  *          #FALSE otherwise.
 841  **/
 842 gboolean
 843 atspi_accessible_is_collection (AtspiAccessible *obj)
 844 {
 845      return _atspi_accessible_is_a (obj,
 846                               atspi_interface_collection);
 847 }
 848
 849 /**
 850  * atspi_accessible_is_component:
 851  * @obj: a pointer to the #AtspiAccessible instance to query.
 852  *
 853  * Query whether the specified #AtspiAccessible implements #AtspiComponent.
 854  *
 855  * Returns: #TRUE if @obj implements the #AtspiComponent interface,
 856  *          #FALSE otherwise.
 857  **/
 858 gboolean
 859 atspi_accessible_is_component (AtspiAccessible *obj)
 860 {
 861   return _atspi_accessible_is_a (obj,
 862                               atspi_interface_component);
 863 }
 864
 865 /**
 866  * atspi_accessible_is_document:
 867  * @obj: a pointer to the #AtspiAccessible instance to query.
 868  *
 869  * Query whether the specified #AtspiAccessible implements #AtspiDocument.
 870  *
 871  * Returns: #TRUE if @obj implements the #AtspiDocument interface,
 872  *          #FALSE otherwise.
 873  **/
 874 gboolean
 875 atspi_accessible_is_document (AtspiAccessible *obj)
 876 {
 877   return _atspi_accessible_is_a (obj,
 878                               atspi_interface_document);
 879 }
 880
 881 /**
 882  * atspi_accessible_is_editable_text:
 883  * @obj: a pointer to the #AtspiAccessible instance to query.
 884  *
 885  * Query whether the specified #AtspiAccessible implements #AtspiEditableText.
 886  *
 887  * Returns: #TRUE if @obj implements the #AtspiEditableText interface,
 888  *          #FALSE otherwise.
 889  **/
 890 gboolean
 891 atspi_accessible_is_editable_text (AtspiAccessible *obj)
 892 {
 893   return _atspi_accessible_is_a (obj,
 894                               atspi_interface_editable_text);
 895 }
 896
 897 /**
 898  * atspi_accessible_is_hypertext:
 899  * @obj: a pointer to the #AtspiAccessible instance to query.
 900  *
 901  * Query whether the specified #AtspiAccessible implements #AtspiHypertext.
 902  *
 903  * Returns: #TRUE if @obj implements the #AtspiHypertext interface,
 904  *          #FALSE otherwise.
 905  **/
 906 gboolean
 907 atspi_accessible_is_hypertext (AtspiAccessible *obj)
 908 {
 909   return _atspi_accessible_is_a (obj,
 910                               atspi_interface_hypertext);
 911 }
 912
 913 /**
 914  * atspi_accessible_is_hyperlink:
 915  * @obj: a pointer to the #AtspiAccessible instance to query.
 916  *
 917  * Query whether the specified #AtspiAccessible implements #AtspiHyperlink.
 918  *
 919  * Returns: #TRUE if @obj implements the #AtspiHypertext interface,
 920  *          #FALSE otherwise.
 921  **/
 922 gboolean
 923 atspi_accessible_is_hyperlink (AtspiAccessible *obj)
 924 {
 925   return _atspi_accessible_is_a (obj,
 926                               atspi_interface_hyperlink);
 927 }
 928
 929 /**
 930  * atspi_accessible_is_image:
 931  * @obj: a pointer to the #AtspiAccessible instance to query.
 932  *
 933  * Query whether the specified #AtspiAccessible implements #AtspiImage.
 934  *
 935  * Returns: #TRUE if @obj implements the #AtspiImage interface,
 936  *          #FALSE otherwise.
 937 **/
 938 gboolean
 939 atspi_accessible_is_image (AtspiAccessible *obj)
 940 {
 941   return _atspi_accessible_is_a (obj,
 942                               atspi_interface_image);
 943 }
 944
 945 /**
 946  * atspi_accessible_is_selection:
 947  * @obj: a pointer to the #AtspiAccessible instance to query.
 948  *
 949  * Query whether the specified #AtspiAccessible implements #AtspiSelection.
 950  *
 951  * Returns: #TRUE if @obj implements the #AtspiSelection interface,
 952  *          #FALSE otherwise.
 953 **/
 954 gboolean
 955 atspi_accessible_is_selection (AtspiAccessible *obj)
 956 {
 957   return _atspi_accessible_is_a (obj,
 958                               atspi_interface_selection);
 959 }
 960
 961 /**
 962  * atspi_accessible_is_table:
 963  * @obj: a pointer to the #AtspiAccessible instance to query.
 964  *
 965  * Query whether the specified #AtspiAccessible implements #AtspiTable.
 966  *
 967  * Returns: #TRUE if @obj implements the #AtspiTable interface,
 968  *          #FALSE otherwise.
 969 **/
 970 gboolean
 971 atspi_accessible_is_table (AtspiAccessible *obj)
 972 {
 973   return _atspi_accessible_is_a (obj,
 974                               atspi_interface_table);
 975 }
 976
 977 /**
 978  * atspi_accessible_is_streamable_content:
 979  * @obj: a pointer to the #AtspiAccessible instance to query.
 980  *
 981  * Query whether the specified #AtspiAccessible implements
 982  *          #AtspiStreamableContent.
 983  *
 984  * Returns: #TRUE if @obj implements the #AtspiStreamableContent interface,
 985  *          #FALSE otherwise.
 986 **/
 987 gboolean
 988 atspi_accessible_is_streamable_content (AtspiAccessible *obj)
 989 {
 990 #if 0
 991   return _atspi_accessible_is_a (obj,
 992                               atspi_interface_streamable_content);
 993 #else
 994   g_warning (_("Streamable content not implemented"));
 995   return FALSE;
 996 #endif
 997 }
 998
 999 /**
1000  * atspi_accessible_is_text:
1001  * @obj: a pointer to the #AtspiAccessible instance to query.
1002  *
1003  * Query whether the specified #AtspiAccessible implements #AtspiText.
1004  *
1005  * Returns: #TRUE if @obj implements the #AtspiText interface,
1006  *          #FALSE otherwise.
1007 **/
1008 gboolean
1009 atspi_accessible_is_text (AtspiAccessible *obj)
1010 {
1011   return _atspi_accessible_is_a (obj,
1012                               atspi_interface_text);
1013 }
1014
1015 /**
1016  * atspi_accessible_is_value:
1017  * @obj: a pointer to the #AtspiAccessible instance to query.
1018  *
1019  * Query whether the specified #AtspiAccessible implements #AtspiValue.
1020  *
1021  * Returns: #TRUE if @obj implements the #AtspiValue interface,
1022  *          #FALSE otherwise.
1023 **/
1024 gboolean
1025 atspi_accessible_is_value (AtspiAccessible *obj)
1026 {
1027   return _atspi_accessible_is_a (obj,
1028                               atspi_interface_value);
1029 }
1030
1031 /**
1032  * atspi_accessible_get_action:
1033  * @obj: a pointer to the #AtspiAccessible instance to query.
1034  *
1035  * Get the #AtspiAction interface for an #AtspiAccessible.
1036  *
1037  * Returns: (transfer full): a pointer to an #AtspiAction interface
1038  *          instance, or NULL if @obj does not implement #AtspiAction.
1039  **/
1040 AtspiAction *
1041 atspi_accessible_get_action (AtspiAccessible *accessible)
1042 {
1043   return (_atspi_accessible_is_a (accessible, atspi_interface_action) ?
1044           g_object_ref (ATSPI_ACTION (accessible)) : NULL);
1045 }
1046
1047 /**
1048  * atspi_accessible_get_collection:
1049  * @obj: a pointer to the #AtspiAccessible instance to query.
1050  *
1051  * Get the #AtspiCollection interface for an #AtspiAccessible.
1052  *
1053  * Returns: (transfer full): a pointer to an #AtspiCollection interface
1054  *          instance, or NULL if @obj does not implement #AtspiCollection.
1055  **/
1056 AtspiCollection *
1057 atspi_accessible_get_collection (AtspiAccessible *accessible)
1058 {
1059   return (_atspi_accessible_is_a (accessible, atspi_interface_collection) ?
1060           g_object_ref (ATSPI_COLLECTION (accessible)) : NULL);
1061 }
1062
1063 /**
1064  * atspi_accessible_get_component:
1065  * @obj: a pointer to the #AtspiAccessible instance to query.
1066  *
1067  * Get the #AtspiComponent interface for an #AtspiAccessible.
1068  *
1069  * Returns: (transfer full): a pointer to an #AtspiComponent interface
1070  *          instance, or NULL if @obj does not implement #AtspiComponent.
1071  **/
1072 AtspiComponent *
1073 atspi_accessible_get_component (AtspiAccessible *obj)
1074 {
1075   return (_atspi_accessible_is_a (obj, atspi_interface_component) ?
1076           g_object_ref (ATSPI_COMPONENT (obj)) : NULL);
1077 }
1078
1079 /**
1080  * atspi_accessible_get_document:
1081  * @obj: a pointer to the #AtspiAccessible instance to query.
1082  *
1083  * Get the #AtspiDocument interface for an #AtspiAccessible.
1084  *
1085  * Returns: (transfer full): a pointer to an #AtspiDocument interface
1086  *          instance, or NULL if @obj does not implement #AtspiDocument.
1087  **/
1088 AtspiDocument *
1089 atspi_accessible_get_document (AtspiAccessible *accessible)
1090 {
1091   return (_atspi_accessible_is_a (accessible, atspi_interface_document) ?
1092           g_object_ref (ATSPI_DOCUMENT (accessible)) : NULL);
1093 }
1094
1095 /**
1096  * atspi_accessible_get_editable_text:
1097  * @obj: a pointer to the #AtspiAccessible instance to query.
1098  *
1099  * Get the #AtspiEditableText interface for an #AtspiAccessible.
1100  *
1101  * Returns: (transfer full): a pointer to an #AtspiEditableText interface
1102  *          instance, or NULL if @obj does not implement #AtspiEditableText.
1103  **/
1104 AtspiEditableText *
1105 atspi_accessible_get_editable_text (AtspiAccessible *accessible)
1106 {
1107   return (_atspi_accessible_is_a (accessible, atspi_interface_editable_text) ?
1108           g_object_ref (ATSPI_EDITABLE_TEXT (accessible)) : NULL);
1109 }
1110
1111 /**
1112  * atspi_accessible_get_hyperlink:
1113  * @obj: a pointer to the #AtspiAccessible object on which to operate.
1114  *
1115  * Get the #AtspiHyperlink associated with the given #AtspiAccessible, if
1116  * supported.
1117  *
1118  * Returns: (transfer full): the #AtspiHyperlink object associated with
1119  *          the given #AtspiAccessible, or NULL if not supported.
1120  **/
1121 AtspiHyperlink *
1122 atspi_accessible_get_hyperlink (AtspiAccessible *accessible)
1123 {
1124   return (_atspi_accessible_is_a (accessible, atspi_interface_hyperlink) ?
1125           atspi_hyperlink_new (accessible->parent.app, accessible->parent.path) : NULL);
1126 }
1127
1128 /**
1129  * atspi_accessible_get_hypertext:
1130  * @obj: a pointer to the #AtspiAccessible instance to query.
1131  *
1132  * Get the #AtspiHypertext interface for an #AtspiAccessible.
1133  *
1134  * Returns: (transfer full): a pointer to an #AtspiHypertext interface
1135  *          instance, or NULL if @obj does not implement #AtspiHypertext.
1136  **/
1137 AtspiHypertext *
1138 atspi_accessible_get_hypertext (AtspiAccessible *accessible)
1139 {
1140   return (_atspi_accessible_is_a (accessible, atspi_interface_hypertext) ?
1141           g_object_ref (ATSPI_HYPERTEXT (accessible)) : NULL);
1142 }
1143
1144 /**
1145  * atspi_accessible_get_image:
1146  * @obj: a pointer to the #AtspiAccessible instance to query.
1147  *
1148  * Get the #AtspiImage interface for an #AtspiAccessible.
1149  *
1150  * Returns: (transfer full): a pointer to an #AtspiImage interface instance, or
1151  *          NULL if @obj does not implement #AtspiImage.
1152  **/
1153 AtspiImage *
1154 atspi_accessible_get_image (AtspiAccessible *accessible)
1155 {
1156   return (_atspi_accessible_is_a (accessible, atspi_interface_image) ?
1157           g_object_ref (ATSPI_IMAGE (accessible)) : NULL);
1158 }
1159
1160 /**
1161  * atspi_accessible_get_selection:
1162  * @obj: a pointer to the #AtspiAccessible instance to query.
1163  *
1164  * Get the #AtspiSelection interface for an #AtspiAccessible.
1165  *
1166  * Returns: (transfer full): a pointer to an #AtspiSelection interface
1167  *          instance, or NULL if @obj does not implement #AtspiSelection.
1168  **/
1169 AtspiSelection *
1170 atspi_accessible_get_selection (AtspiAccessible *accessible)
1171 {
1172   return (_atspi_accessible_is_a (accessible, atspi_interface_selection) ?
1173           g_object_ref (ATSPI_SELECTION (accessible)) : NULL);
1174 }
1175
1176 #if 0
1177 /**
1178  * atspi_accessible_get_streamable_content:
1179  * @obj: a pointer to the #AtspiAccessible instance to query.
1180  *
1181  * Get the #AtspiStreamableContent interface for an #AtspiAccessible.
1182  *
1183  * Returns: (transfer full): a pointer to an #AtspiStreamableContent interface
1184  *          instance, or NULL if @obj does not implement #AtspiStreamableContent.
1185  **/
1186 AtspiStreamableContent *
1187 atspi_accessible_get_streamable_content (AtspiAccessible *accessible)
1188 {
1189   return (_atspi_accessible_is_a (accessible, atspi_interface_streamable_content) ?
1190           accessible : NULL);
1191 }
1192 #endif
1193
1194 /**
1195  * atspi_accessible_get_table:
1196  * @obj: a pointer to the #AtspiAccessible instance to query.
1197  *
1198  * Get the #AtspiTable interface for an #AtspiAccessible.
1199  *
1200  * Returns: (transfer full): a pointer to an #AtspiTable interface instance, or
1201  *          NULL if @obj does not implement #AtspiTable.
1202  **/
1203 AtspiTable *
1204 atspi_accessible_get_table (AtspiAccessible *obj)
1205 {
1206   return (_atspi_accessible_is_a (obj, atspi_interface_table) ?
1207           g_object_ref (ATSPI_TABLE (obj)) : NULL);
1208 }
1209
1210 /**
1211  * atspi_accessible_get_text:
1212  * @obj: a pointer to the #AtspiAccessible instance to query.
1213  *
1214  * Get the #AtspiTable interface for an #AtspiAccessible.
1215  *
1216  * Returns: (transfer full): a pointer to an #AtspiText interface instance, or
1217  *          NULL if @obj does not implement #AtspiText.
1218  **/
1219 AtspiText *
1220 atspi_accessible_get_text (AtspiAccessible *obj)
1221 {
1222   return (_atspi_accessible_is_a (obj, atspi_interface_text) ?
1223           g_object_ref (ATSPI_TEXT (obj)) : NULL);
1224 }
1225
1226 /**
1227  * atspi_accessible_get_value:
1228  * @obj: a pointer to the #AtspiAccessible instance to query.
1229  *
1230  * Get the #AtspiTable interface for an #AtspiAccessible.
1231  *
1232  * Returns: (transfer full): a pointer to an #AtspiValue interface instance, or
1233  *          NULL if @obj does not implement #AtspiValue.
1234  **/
1235 AtspiValue *
1236 atspi_accessible_get_value (AtspiAccessible *accessible)
1237 {
1238   return (_atspi_accessible_is_a (accessible, atspi_interface_value) ?
1239           g_object_ref (ATSPI_VALUE (accessible)) : NULL);
1240 }
1241
1242 static void
1243 append_const_val (GArray *array, const gchar *val)
1244 {
1245   gchar *dup = g_strdup (val);
1246
1247   if (dup)
1248     g_array_append_val (array, dup);
1249 }
1250
1251 /**
1252  * atspi_accessible_get_interfaces:
1253  *
1254  * #obj: The #AtspiAccessible to query.
1255  *
1256  * Returns: (element-type gchar*) (transfer full): A #GArray of strings
1257  *          describing the interfaces supported by the object.  Interfaces are
1258  *          denoted in short-hand (ie, "Component", "Text", etc.)
1259  **/
1260 GArray *
1261 atspi_accessible_get_interfaces (AtspiAccessible *obj)
1262 {
1263   GArray *ret = g_array_new (TRUE, TRUE, sizeof (gchar *));
1264
1265   if (!ret)
1266     return NULL;
1267
1268   g_return_val_if_fail (obj != NULL, NULL);
1269
1270   if (atspi_accessible_is_action (obj))
1271     append_const_val (ret, "Action");
1272   if (atspi_accessible_is_collection (obj))
1273     append_const_val (ret, "Collection");
1274   if (atspi_accessible_is_component (obj))
1275     append_const_val (ret, "Component");
1276   if (atspi_accessible_is_document (obj))
1277     append_const_val (ret, "Document");
1278   if (atspi_accessible_is_editable_text (obj))
1279     append_const_val (ret, "EditableText");
1280   if (atspi_accessible_is_hypertext (obj))
1281     append_const_val (ret, "Hypertext");
1282   if (atspi_accessible_is_hyperlink (obj))
1283     append_const_val (ret, "Hyperlink");
1284   if (atspi_accessible_is_image (obj))
1285     append_const_val (ret, "Image");
1286   if (atspi_accessible_is_selection (obj))
1287     append_const_val (ret, "Selection");
1288   if (atspi_accessible_is_table (obj))
1289     append_const_val (ret, "Table");
1290   if (atspi_accessible_is_text (obj))
1291     append_const_val (ret, "Text");
1292   if (atspi_accessible_is_value (obj))
1293     append_const_val (ret, "Value");
1294
1295   return ret;
1296 }
1297
1298 AtspiAccessible *
1299 atspi_accessible_new (AtspiApplication *app, const gchar *path)
1300 {
1301   AtspiAccessible *accessible;
1302
1303   accessible = g_object_new (ATSPI_TYPE_ACCESSIBLE, NULL);
1304   g_return_val_if_fail (accessible != NULL, NULL);
1305
1306   accessible->parent.app = g_object_ref (app);
1307   accessible->parent.path = g_strdup (path);
1308
1309   return accessible;
1310 }