atk/atksocket.c

   1 /* ATK -  Accessibility Toolkit
   2  * Copyright (C) 2009 Novell, Inc.
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 #include "config.h"
  21
  22 #include "atk.h"
  23 #include "atksocket.h"
  24
  25 /**
  26  * SECTION:atksocket
  27  * @Short_description: Container for AtkPlug objects from other processes
  28  * @Title: AtkSocket
  29  * @See_also: #AtkPlug
  30  *
  31  * Together with #AtkPlug, #AtkSocket provides the ability to embed
  32  * accessibles from one process into another in a fashion that is
  33  * transparent to assistive technologies. #AtkSocket works as the
  34  * container of #AtkPlug, embedding it using the method
  35  * atk_socket_embed(). Any accessible contained in the #AtkPlug will
  36  * appear to the assistive technologies as being inside the
  37  * application that created the #AtkSocket.
  38  *
  39  * The communication between a #AtkSocket and a #AtkPlug is done by
  40  * the IPC layer of the accessibility framework, normally implemented
  41  * by the D-Bus based implementation of AT-SPI (at-spi2). If that is
  42  * the case, at-spi-atk2 is the responsible to implement the abstract
  43  * methods atk_plug_get_id() and atk_socket_embed(), so an ATK
  44  * implementor shouldn't reimplement them. The process that contains
  45  * the #AtkPlug is responsible to send the ID returned by
  46  * atk_plug_id() to the process that contains the #AtkSocket, so it
  47  * could call the method atk_socket_embed() in order to embed it.
  48  *
  49  * For the same reasons, an implementor doesn't need to implement
  50  * atk_object_get_n_accessible_children() and
  51  * atk_object_ref_accessible_child(). All the logic related to those
  52  * functions will be implemented by the IPC layer.
  53  */
  54
  55 static void atk_socket_finalize   (GObject *obj);
  56
  57 static void atk_component_interface_init (AtkComponentIface *iface);
  58
  59 static void atk_socket_component_real_get_extents (AtkComponent *component,
  60                                                    gint         *x,
  61                                                    gint         *y,
  62                                                    gint         *width,
  63                                                    gint         *height,
  64                                                    AtkCoordType  coord_type);
  65
  66 G_DEFINE_TYPE_WITH_CODE (AtkSocket, atk_socket, ATK_TYPE_OBJECT,
  67                          G_IMPLEMENT_INTERFACE (ATK_TYPE_COMPONENT, atk_component_interface_init))
  68
  69 static void
  70 atk_socket_init (AtkSocket* obj)
  71 {
  72   AtkObject *accessible = ATK_OBJECT (obj);
  73
  74   obj->embedded_plug_id = NULL;
  75
  76   accessible->role = ATK_ROLE_FILLER;
  77   accessible->layer = ATK_LAYER_WIDGET;
  78 }
  79
  80 static void
  81 atk_socket_class_init (AtkSocketClass* klass)
  82 {
  83   GObjectClass *obj_class = G_OBJECT_CLASS (klass);
  84
  85   obj_class->finalize = atk_socket_finalize;
  86
  87   klass->embed = NULL;
  88 }
  89
  90 static void
  91 atk_socket_finalize (GObject *_obj)
  92 {
  93   AtkSocket *obj = ATK_SOCKET (_obj);
  94
  95   g_free (obj->embedded_plug_id);
  96   obj->embedded_plug_id = NULL;
  97
  98   G_OBJECT_CLASS (atk_socket_parent_class)->finalize (_obj);
  99 }
 100
 101 static void
 102 atk_component_interface_init (AtkComponentIface *iface)
 103 {
 104   iface->get_extents = atk_socket_component_real_get_extents;
 105 }
 106
 107 /**
 108  * atk_socket_new:
 109  *
 110  * Creates a new #AtkSocket.
 111  *
 112  * Returns: (transfer full): the newly created #AtkSocket instance
 113  */
 114 AtkObject*
 115 atk_socket_new (void)
 116 {
 117   return g_object_new (ATK_TYPE_SOCKET, NULL);
 118 }
 119
 120 /**
 121  * atk_socket_embed:
 122  * @obj: an #AtkSocket
 123  * @plug_id: the ID of an #AtkPlug
 124  *
 125  * Embeds the children of an #AtkPlug as the children of the
 126  * #AtkSocket. The plug may be in the same process or in a different
 127  * process.
 128  *
 129  * The class item used by this function should be filled in by the IPC
 130  * layer (usually at-spi2-atk). The implementor of the AtkSocket
 131  * should call this function and pass the id for the plug as returned
 132  * by atk_plug_get_id().  It is the responsibility of the application
 133  * to pass the plug id on to the process implementing the #AtkSocket
 134  * as needed.
 135  *
 136  * Since: 1.30
 137  **/
 138 void
 139 atk_socket_embed (AtkSocket* obj, const gchar* plug_id)
 140 {
 141   AtkSocketClass *klass;
 142
 143   g_return_if_fail (plug_id != NULL);
 144   g_return_if_fail (ATK_IS_SOCKET (obj));
 145
 146   klass = g_type_class_peek (ATK_TYPE_SOCKET);
 147   if (klass && klass->embed)
 148     {
 149       if (obj->embedded_plug_id)
 150         g_free (obj->embedded_plug_id);
 151       obj->embedded_plug_id = g_strdup (plug_id);
 152       (klass->embed) (obj, plug_id);
 153     }
 154 }
 155
 156 /**
 157  * atk_socket_is_occupied:
 158  * @obj: an #AtkSocket
 159  *
 160  * Determines whether or not the socket has an embedded plug.
 161  *
 162  * Returns: TRUE if a plug is embedded in the socket
 163  *
 164  * Since: 1.30
 165  **/
 166 gboolean
 167 atk_socket_is_occupied (AtkSocket* obj)
 168 {
 169   g_return_val_if_fail (ATK_IS_SOCKET (obj), FALSE);
 170
 171   return (obj->embedded_plug_id != NULL);
 172 }
 173
 174 static void
 175 atk_socket_component_real_get_extents (AtkComponent *component,
 176                                        gint         *x,
 177                                        gint         *y,
 178                                        gint         *width,
 179                                        gint         *height,
 180                                        AtkCoordType  coord_type)
 181 {
 182   AtkObject *parent = atk_object_get_parent (ATK_OBJECT (component));
 183
 184   if (parent == NULL || !ATK_IS_COMPONENT (parent))
 185   {
 186     if (x)
 187       *x = -1;
 188     if (y)
 189       *y = -1;
 190     if (width)
 191       *width = -1;
 192     if (height)
 193       *height = -1;
 194
 195     return;
 196   }
 197
 198   atk_component_get_extents (ATK_COMPONENT (parent), x, y, width, height, coord_type);
 199 }