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  * Copyright 2010, 2011 Novell, 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
  26 /* TODO: Improve documentation and implement some missing functions */
  27
  28 /**
  29  * atspi_collection_is_ancester_of:
  30  *
  31  * @collection: The #AtspiCollection to test against.
  32  * @test: The #AtspiAccessible to test.
  33  *
  34  * Returns: TRUE if @collection is an ancestor of @test; FALSE otherwise.
  35  *
  36  * Not yet implemented.
  37  **/
  38 gboolean
  39 atspi_collection_is_ancestor_of (AtspiCollection *collection,
  40                                  AtspiAccessible *test,
  41                                  GError **error)
  42 {
  43   g_warning ("Atspi: TODO: Implement is_ancester_of");
  44   return FALSE;
  45 }
  46
  47 static DBusMessage *
  48 new_message (AtspiCollection *collection, char *method)
  49 {
  50   AtspiAccessible *accessible;
  51
  52   if (!collection)
  53     return NULL;
  54
  55   accessible = ATSPI_ACCESSIBLE (collection);
  56   return dbus_message_new_method_call (accessible->parent.app->bus_name,
  57                                        accessible->parent.path,
  58                                        atspi_interface_collection,
  59                                        method);
  60 }
  61
  62 static gboolean
  63 append_match_rule (DBusMessage *message, AtspiMatchRule *rule)
  64 {
  65   DBusMessageIter iter;
  66
  67   dbus_message_iter_init_append (message, &iter);
  68   return _atspi_match_rule_marshal (rule, &iter);
  69 }
  70
  71 static gboolean
  72 append_accessible (DBusMessage *message, AtspiAccessible *accessible)
  73 {
  74   DBusMessageIter iter;
  75
  76   dbus_message_iter_init_append (message, &iter);
  77   dbus_message_iter_append_basic (&iter, DBUS_TYPE_OBJECT_PATH,
  78                                   &accessible->parent.path);
  79   return TRUE;  /* TODO: Check for out-of-memory */
  80 }
  81
  82 static GArray *
  83 return_accessibles (DBusMessage *message)
  84 {
  85   DBusMessageIter iter, iter_array;
  86   GArray *ret = g_array_new (TRUE, TRUE, sizeof (AtspiAccessible *));
  87
  88   _ATSPI_DBUS_CHECK_SIG (message, "a(so)", NULL, NULL);
  89
  90   dbus_message_iter_init (message, &iter);
  91   dbus_message_iter_recurse (&iter, &iter_array);
  92
  93   while (dbus_message_iter_get_arg_type (&iter_array) != DBUS_TYPE_INVALID)
  94   {
  95     AtspiAccessible *accessible;
  96     GArray *new_array;
  97     accessible = _atspi_dbus_return_accessible_from_iter (&iter_array);
  98     new_array = g_array_append_val (ret, accessible);
  99     if (new_array)
 100       ret = new_array;
 101     /* Iter was moved already, so no need to call dbus_message_iter_next */
 102   }
 103   dbus_message_unref (message);
 104   return ret;
 105 }
 106
 107 /**
 108  * atspi_collection_get_matches:
 109  *
 110  * @collection: The #AtspiCollection.
 111  * @rule: A #AtspiMatchRule describing the match criteria.
 112  * @sortby: An #AtspiCollectionSortOrder specifying the way the results are to
 113  *          be sorted.
 114  * @count: The maximum number of results to return, or 0 for no limit.
 115  * @traverse: TODO
 116  *
 117  * Returns: (element-type AtspiAccessible*) (transfer full): A #GArray of
 118  *          #AtspiAccessibles matching the given match rule.
 119  **/
 120 GArray *
 121 atspi_collection_get_matches (AtspiCollection *collection,
 122                               AtspiMatchRule *rule,
 123                               AtspiCollectionSortOrder sortby,
 124                               gint count,
 125                               gboolean traverse,
 126                               GError **error)
 127 {
 128   DBusMessage *message = new_message (collection, "GetMatches");
 129   DBusMessage *reply;
 130   dbus_int32_t d_sortby = sortby;
 131   dbus_int32_t d_count = count;
 132   dbus_bool_t d_traverse = traverse;
 133
 134   if (!message)
 135     return NULL;
 136
 137   if (!append_match_rule (message, rule))
 138     return NULL;
 139   dbus_message_append_args (message, DBUS_TYPE_UINT32, &d_sortby,
 140                             DBUS_TYPE_INT32, &d_count,
 141                             DBUS_TYPE_BOOLEAN, &d_traverse,
 142                             DBUS_TYPE_INVALID);
 143   reply = _atspi_dbus_send_with_reply_and_block (message, error);
 144   if (!reply)
 145     return NULL;
 146   return return_accessibles (reply);
 147 }
 148
 149 /**
 150  * atspi_collection_get_matches_to:
 151  *
 152  * @collection: The #AtspiCollection.
 153  * @current_object: The object at which to start searching.
 154  * @rule: A #AtspiMatchRule describing the match criteria.
 155  * @sortby: An #AtspiCollectionSortOrder specifying the way the results are to
 156  *          be sorted.
 157  * @tree: An #AtspiCollectionTreeTraversalType specifying restrictions on
 158  *        the objects to be traversed.
 159  * @recurse: TODO
 160  * @count: The maximum number of results to return, or 0 for no limit.
 161  * @traverse: TODO
 162  *
 163  * Returns: (element-type AtspiAccessible*) (transfer full): A #GArray of
 164  *          #AtspiAccessibles matching the given match rule after
 165  *          @current_object.
 166  **/
 167 GArray *
 168 atspi_collection_get_matches_to (AtspiCollection *collection,
 169                               AtspiAccessible *current_object,
 170                               AtspiMatchRule *rule,
 171                               AtspiCollectionSortOrder sortby,
 172                               AtspiCollectionTreeTraversalType tree,
 173                               gboolean recurse,
 174                               gint count,
 175                               gboolean traverse,
 176                               GError **error)
 177 {
 178   DBusMessage *message = new_message (collection, "GetMatchesTo");
 179   DBusMessage *reply;
 180   dbus_int32_t d_sortby = sortby;
 181   dbus_int32_t d_tree = tree;
 182   dbus_bool_t d_recurse = recurse;
 183   dbus_int32_t d_count = count;
 184   dbus_bool_t d_traverse = traverse;
 185
 186   if (!message)
 187     return NULL;
 188
 189   if (!append_accessible (message, current_object))
 190     return NULL;
 191   if (!append_match_rule (message, rule))
 192     return NULL;
 193   dbus_message_append_args (message, DBUS_TYPE_UINT32, &d_sortby,
 194                                      DBUS_TYPE_UINT32, &d_tree,
 195                             DBUS_TYPE_BOOLEAN, &d_recurse,
 196                             DBUS_TYPE_INT32, &d_count,
 197                             DBUS_TYPE_BOOLEAN, &d_traverse,
 198                             DBUS_TYPE_INVALID);
 199   reply = _atspi_dbus_send_with_reply_and_block (message, error);
 200   if (!reply)
 201     return NULL;
 202   return return_accessibles (reply);
 203 }
 204
 205 /**
 206  * atspi_collection_get_matches_from:
 207  *
 208  * @collection: The #AtspiCollection.
 209  * @current_object: Upon reaching this object, searching should stop.
 210  * @rule: A #AtspiMatchRule describing the match criteria.
 211  * @sortby: An #AtspiCollectionSortOrder specifying the way the results are to
 212  *          be sorted.
 213  * @tree: An #AtspiCollectionTreeTraversalType specifying restrictions on
 214  *        the objects to be traversed.
 215  * @count: The maximum number of results to return, or 0 for no limit.
 216  * @traverse: TODO
 217  *
 218  * Returns: (element-type AtspiAccessible*) (transfer full): A #GArray of
 219  *          #AtspiAccessibles matching the given match rule that preceed
 220  *          @current_object.
 221  **/
 222 GArray *
 223 atspi_collection_get_matches_from (AtspiCollection *collection,
 224                               AtspiAccessible *current_object,
 225                               AtspiMatchRule *rule,
 226                               AtspiCollectionSortOrder sortby,
 227                               AtspiCollectionTreeTraversalType tree,
 228                               gint count,
 229                               gboolean traverse,
 230                               GError **error)
 231 {
 232   DBusMessage *message = new_message (collection, "GetMatchesFrom");
 233   DBusMessage *reply;
 234   dbus_int32_t d_sortby = sortby;
 235   dbus_int32_t d_tree = tree;
 236   dbus_int32_t d_count = count;
 237   dbus_bool_t d_traverse = traverse;
 238
 239   if (!message)
 240     return NULL;
 241
 242   if (!append_accessible (message, current_object))
 243     return NULL;
 244   if (!append_match_rule (message, rule))
 245     return NULL;
 246   dbus_message_append_args (message, DBUS_TYPE_UINT32, &d_sortby,
 247                             DBUS_TYPE_UINT32, &d_tree,
 248                             DBUS_TYPE_INT32, &d_count,
 249                             DBUS_TYPE_BOOLEAN, &d_traverse,
 250                             DBUS_TYPE_INVALID);
 251   reply = _atspi_dbus_send_with_reply_and_block (message, error);
 252   if (!reply)
 253     return NULL;
 254   return return_accessibles (reply);
 255 }
 256
 257 /**
 258  * atspi_collection_get_active_descendant:
 259  *
 260  * @collection: The #AtspiCollection to query.
 261  *
 262  * Returns: (transfer full): The active descendant of #collection.
 263  *
 264  * Not yet implemented.
 265  **/
 266 AtspiAccessible *
 267 atspi_collection_get_active_descendant (AtspiCollection *collection, GError **error)
 268 {
 269   g_warning ("atspi: TODO: Implement get_active_descendants");
 270   return NULL;
 271 }
 272
 273 static void
 274 atspi_collection_base_init (AtspiCollection *klass)
 275 {
 276 }
 277
 278 GType
 279 atspi_collection_get_type (void)
 280 {
 281   static GType type = 0;
 282
 283   if (!type) {
 284     static const GTypeInfo tinfo =
 285     {
 286       sizeof (AtspiCollection),
 287       (GBaseInitFunc) atspi_collection_base_init,
 288       (GBaseFinalizeFunc) NULL,
 289     };
 290
 291     type = g_type_register_static (G_TYPE_INTERFACE, "AtspiCollection", &tinfo, 0);
 292
 293   }
 294   return type;
 295 }