atspi/atspi-collection.c

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2007 IBM Corp.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include "atspi-private.h"
  24
  25 /* TODO: Improve documentation and implement some missing functions */
  26
  27 /**
  28  * atspi_collection_is_ancester_of:
  29  *
  30  * @collection: The #AtspiCollection to test against.
  31  * @test: The #AtspiAccessible to test.
  32  *
  33  * Returns: TRUE if @collection is an ancestor of @test; FALSE otherwise.
  34  *
  35  * Not yet implemented.
  36  **/
  37 gboolean
  38 atspi_collection_is_ancestor_of (AtspiCollection *collection,
  39                                  AtspiAccessible *test,
  40                                  GError **error)
  41 {
  42   g_warning ("Atspi: TODO: Implement is_ancester_of");
  43   return FALSE;
  44 }
  45
  46 static DBusMessage *
  47 new_message (AtspiCollection *collection, char *method)
  48 {
  49   AtspiAccessible *accessible;
  50
  51   if (!collection)
  52     return NULL;
  53
  54   accessible = ATSPI_ACCESSIBLE (collection);
  55   return dbus_message_new_method_call (accessible->parent.app->bus_name,
  56                                        accessible->parent.path,
  57                                        atspi_interface_collection,
  58                                        method);
  59 }
  60
  61 static gboolean
  62 append_match_rule (DBusMessage *message, AtspiMatchRule *rule)
  63 {
  64   DBusMessageIter iter;
  65
  66   dbus_message_iter_init_append (message, &iter);
  67   return _atspi_match_rule_marshal (rule, &iter);
  68 }
  69
  70 static gboolean
  71 append_accessible (DBusMessage *message, AtspiAccessible *accessible)
  72 {
  73   DBusMessageIter iter;
  74
  75   dbus_message_iter_init_append (message, &iter);
  76   dbus_message_iter_append_basic (&iter, DBUS_TYPE_OBJECT_PATH,
  77                                   &accessible->parent.path);
  78   return TRUE;  /* TODO: Check for out-of-memory */
  79 }
  80
  81 static GArray *
  82 return_accessibles (DBusMessage *message)
  83 {
  84   DBusMessageIter iter, iter_array;
  85   GArray *ret = g_array_new (TRUE, TRUE, sizeof (AtspiAccessible *));
  86
  87   _ATSPI_DBUS_CHECK_SIG (message, "a(so)", NULL, NULL);
  88
  89   dbus_message_iter_init (message, &iter);
  90   dbus_message_iter_recurse (&iter, &iter_array);
  91
  92   while (dbus_message_iter_get_arg_type (&iter_array) != DBUS_TYPE_INVALID)
  93   {
  94     AtspiAccessible *accessible;
  95     GArray *new_array;
  96     accessible = _atspi_dbus_return_accessible_from_iter (&iter_array);
  97     new_array = g_array_append_val (ret, accessible);
  98     if (new_array)
  99       ret = new_array;
 100     /* Iter was moved already, so no need to call dbus_message_iter_next */
 101   }
 102   dbus_message_unref (message);
 103   return ret;
 104 }
 105
 106 /**
 107  * atspi_collection_get_matches:
 108  *
 109  * @collection: The #AtspiCollection.
 110  * @rule: A #AtspiMatchRule describing the match criteria.
 111  * @sortby: An #AtspiCollectionSortOrder specifying the way the results are to
 112  *          be sorted.
 113  * @count: The maximum number of results to return, or 0 for no limit.
 114  * @traverse: TODO
 115  *
 116  * Returns: (element-type AtspiAccessible*) (transfer full): A #GArray of
 117  *          #AtspiAccessibles matching the given match rule.
 118  **/
 119 GArray *
 120 atspi_collection_get_matches (AtspiCollection *collection,
 121                               AtspiMatchRule *rule,
 122                               AtspiCollectionSortOrder sortby,
 123                               gint count,
 124                               gboolean traverse,
 125                               GError **error)
 126 {
 127   DBusMessage *message = new_message (collection, "GetMatches");
 128   DBusMessage *reply;
 129   dbus_int32_t d_sortby = sortby;
 130   dbus_int32_t d_count = count;
 131   dbus_bool_t d_traverse = traverse;
 132
 133   if (!message)
 134     return NULL;
 135
 136   if (!append_match_rule (message, rule))
 137     return NULL;
 138   dbus_message_append_args (message, DBUS_TYPE_UINT32, &d_sortby,
 139                             DBUS_TYPE_INT32, &d_count,
 140                             DBUS_TYPE_BOOLEAN, &d_traverse,
 141                             DBUS_TYPE_INVALID);
 142   reply = _atspi_dbus_send_with_reply_and_block (message, error);
 143   if (!reply)
 144     return NULL;
 145   return return_accessibles (reply);
 146 }
 147
 148 /**
 149  * atspi_collection_get_matches_to:
 150  *
 151  * @collection: The #AtspiCollection.
 152  * @current_object: The object at which to start searching.
 153  * @rule: A #AtspiMatchRule describing the match criteria.
 154  * @sortby: An #AtspiCollectionSortOrder specifying the way the results are to
 155  *          be sorted.
 156  * @tree: An #AtspiCollectionTreeTraversalType specifying restrictions on
 157  *        the objects to be traversed.
 158  * @recurse: TODO
 159  * @count: The maximum number of results to return, or 0 for no limit.
 160  * @traverse: TODO
 161  *
 162  * Returns: (element-type AtspiAccessible*) (transfer full): A #GArray of
 163  *          #AtspiAccessibles matching the given match rule after
 164  *          @current_object.
 165  **/
 166 GArray *
 167 atspi_collection_get_matches_to (AtspiCollection *collection,
 168                               AtspiAccessible *current_object,
 169                               AtspiMatchRule *rule,
 170                               AtspiCollectionSortOrder sortby,
 171                               AtspiCollectionTreeTraversalType tree,
 172                               gboolean recurse,
 173                               gint count,
 174                               gboolean traverse,
 175                               GError **error)
 176 {
 177   DBusMessage *message = new_message (collection, "GetMatchesTo");
 178   DBusMessage *reply;
 179   dbus_int32_t d_sortby = sortby;
 180   dbus_int32_t d_tree = tree;
 181   dbus_bool_t d_recurse = recurse;
 182   dbus_int32_t d_count = count;
 183   dbus_bool_t d_traverse = traverse;
 184
 185   if (!message)
 186     return NULL;
 187
 188   if (!append_accessible (message, current_object))
 189     return NULL;
 190   if (!append_match_rule (message, rule))
 191     return NULL;
 192   dbus_message_append_args (message, DBUS_TYPE_UINT32, &d_sortby,
 193                                      DBUS_TYPE_UINT32, &d_tree,
 194                             DBUS_TYPE_BOOLEAN, &d_recurse,
 195                             DBUS_TYPE_INT32, &d_count,
 196                             DBUS_TYPE_BOOLEAN, &d_traverse,
 197                             DBUS_TYPE_INVALID);
 198   reply = _atspi_dbus_send_with_reply_and_block (message, error);
 199   if (!reply)
 200     return NULL;
 201   return return_accessibles (reply);
 202 }
 203
 204 /**
 205  * atspi_collection_get_matches_from:
 206  *
 207  * @collection: The #AtspiCollection.
 208  * @current_object: Upon reaching this object, searching should stop.
 209  * @rule: A #AtspiMatchRule describing the match criteria.
 210  * @sortby: An #AtspiCollectionSortOrder specifying the way the results are to
 211  *          be sorted.
 212  * @tree: An #AtspiCollectionTreeTraversalType specifying restrictions on
 213  *        the objects to be traversed.
 214  * @count: The maximum number of results to return, or 0 for no limit.
 215  * @traverse: TODO
 216  *
 217  * Returns: (element-type AtspiAccessible*) (transfer full): A #GArray of
 218  *          #AtspiAccessibles matching the given match rule that preceed
 219  *          @current_object.
 220  **/
 221 GArray *
 222 atspi_collection_get_matches_from (AtspiCollection *collection,
 223                               AtspiAccessible *current_object,
 224                               AtspiMatchRule *rule,
 225                               AtspiCollectionSortOrder sortby,
 226                               AtspiCollectionTreeTraversalType tree,
 227                               gint count,
 228                               gboolean traverse,
 229                               GError **error)
 230 {
 231   DBusMessage *message = new_message (collection, "GetMatchesFrom");
 232   DBusMessage *reply;
 233   dbus_int32_t d_sortby = sortby;
 234   dbus_int32_t d_tree = tree;
 235   dbus_int32_t d_count = count;
 236   dbus_bool_t d_traverse = traverse;
 237
 238   if (!message)
 239     return NULL;
 240
 241   if (!append_accessible (message, current_object))
 242     return NULL;
 243   if (!append_match_rule (message, rule))
 244     return NULL;
 245   dbus_message_append_args (message, DBUS_TYPE_UINT32, &d_sortby,
 246                             DBUS_TYPE_UINT32, &d_tree,
 247                             DBUS_TYPE_INT32, &d_count,
 248                             DBUS_TYPE_BOOLEAN, &d_traverse,
 249                             DBUS_TYPE_INVALID);
 250   reply = _atspi_dbus_send_with_reply_and_block (message, error);
 251   if (!reply)
 252     return NULL;
 253   return return_accessibles (reply);
 254 }
 255
 256 /**
 257  * atspi_collection_get_active_descendant:
 258  *
 259  * @collection: The #AtspiCollection to query.
 260  *
 261  * Returns: (transfer full): The active descendant of #collection.
 262  *
 263  * Not yet implemented.
 264  **/
 265 AtspiAccessible *
 266 atspi_collection_get_active_descendant (AtspiCollection *collection, GError **error)
 267 {
 268   g_warning ("atspi: TODO: Implement get_active_descendants");
 269   return NULL;
 270 }
 271
 272 static void
 273 atspi_collection_base_init (AtspiCollection *klass)
 274 {
 275 }
 276
 277 GType
 278 atspi_collection_get_type (void)
 279 {
 280   static GType type = 0;
 281
 282   if (!type) {
 283     static const GTypeInfo tinfo =
 284     {
 285       sizeof (AtspiCollection),
 286       (GBaseInitFunc) atspi_collection_base_init,
 287       (GBaseFinalizeFunc) NULL,
 288     };
 289
 290     type = g_type_register_static (G_TYPE_INTERFACE, "AtspiCollection", &tinfo, 0);
 291
 292   }
 293   return type;
 294 }