docs: Improve documentation for AtkPlug and AtkSocket
[platform/upstream/atk.git] / atk / atkplug.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 "atk.h"
21 #include "atkplug.h"
22
23 /**
24  * SECTION:atkplug
25  * @Short_description: Toplevel for embedding into other processes
26  * @Title: AtkPlug
27  * @See_also: #AtkPlug
28  *
29  * See #AtkSocket
30  *
31  */
32
33 static void atk_component_interface_init (AtkComponentIface *iface);
34
35 static void atk_plug_class_init (AtkPlugClass *klass);
36
37 G_DEFINE_TYPE_WITH_CODE (AtkPlug, atk_plug, ATK_TYPE_OBJECT,
38                          G_IMPLEMENT_INTERFACE (ATK_TYPE_COMPONENT, atk_component_interface_init))
39
40 static void
41 atk_plug_init (AtkPlug* obj)
42 {
43 }
44
45 static void
46 atk_plug_class_init (AtkPlugClass* klass)
47 {
48   klass->get_object_id = NULL;
49 }
50
51 static void
52 atk_component_interface_init (AtkComponentIface *iface)
53 {
54 }
55
56 AtkObject*
57 atk_plug_new (void)
58 {
59   AtkObject* accessible;
60   
61   accessible = g_object_new (ATK_TYPE_PLUG, NULL);
62   g_return_val_if_fail (accessible != NULL, NULL);
63
64   accessible->role = ATK_ROLE_FILLER;
65   accessible->layer = ATK_LAYER_WIDGET;
66   
67   return accessible;
68 }
69
70 /**
71  * atk_plug_get_id:
72  * @obj: an #AtkPlug
73  *
74  * Gets the unique ID of an #AtkPlug object, which can be used to
75  * embed inside of an #AtkSocket using atk_socket_embed().
76  *
77  * Internally, this calls a class function that should be registered
78  * by the IPC layer (usually at-spi2-atk). The implementor of an
79  * #AtkPlug object should call this function (after atk-bridge is
80  * loaded) and pass the value to the process implementing the
81  * #AtkSocket, so it could embed the plug.
82  *
83  * Returns: the unique ID for the plug
84  *
85  * Since: 1.30
86  **/
87 gchar*
88 atk_plug_get_id (AtkPlug* obj)
89 {
90   AtkPlugClass *klass;
91
92   g_return_val_if_fail (ATK_IS_PLUG (obj), NULL);
93
94   klass = g_type_class_peek (ATK_TYPE_PLUG);
95
96   if (klass && klass->get_object_id)
97     return (klass->get_object_id) (obj);
98   else
99     return NULL;
100 }