Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtksocket.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkSocket
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Container for widgets from other processes
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 Together with #GtkPlug, #GtkSocket provides the ability
  10 to embed widgets from one process into another process
  11 in a fashion that is transparent to the user. One
  12 process creates a #GtkSocket widget and, passes the
  13 that widget's window ID to the other process,
  14 which then creates a #GtkPlug with that window ID.
  15 Any widgets contained in the #GtkPlug then will appear
  16 inside the first applications window.
  17 </para>
  18
  19 <para>
  20 The socket's window ID is obtained by using
  21 gtk_socket_get_id(). Before using this function,
  22 the socket must have been realized, and for hence,
  23 have been added to its parent.
  24
  25 <example>
  26 <title>Obtaining the window ID of a socket.</title>
  27 <programlisting>
  28 GtkWidget *socket = gtk_socket_new (<!-- -->);
  29 gtk_widget_show (socket);
  30 gtk_container_add (GTK_CONTAINER (parent), socket);
  31
  32 /* The following call is only necessary if one of
  33  * the ancestors of the socket is not yet visible.
  34  */
  35 gtk_widget_realize (socket);
  36 g_print ("The ID of the sockets window is %#x\n",
  37          gtk_socket_get_id (socket));
  38 </programlisting>
  39 </example>
  40 </para>
  41
  42 <para>
  43 Note that if you pass the window ID of the socket to another
  44 process that will create a plug in the socket, you
  45 must make sure that the socket widget is not destroyed
  46 until that plug is created. Violating this rule will
  47 cause unpredictable consequences, the most likely
  48 consequence being that the plug will appear as a
  49 separate toplevel window. You can check if the plug
  50 has been created by examining the
  51 <structfield>plug_window</structfield> field of the
  52 #GtkSocket structure. If this field is non-%NULL,
  53 then the plug has been successfully created inside
  54 of the socket.
  55 </para>
  56
  57 <para>
  58 When GTK+ is notified that the embedded window has been
  59 destroyed, then it will destroy the socket as well. You
  60 should always, therefore, be prepared for your sockets
  61 to be destroyed at any time when the main event loop
  62 is running.
  63 </para>
  64
  65 <para>
  66 The communication between a #GtkSocket and a #GtkPlug follows the
  67 <ulink url="http://www.freedesktop.org/standards/xembed-spec">XEmbed</ulink>
  68 protocol. This protocol has also been implemented in other toolkits, e.g.
  69 <application>Qt</application>, allowing the same level of integration
  70 when embedding a <application>Qt</application> widget in GTK or vice versa.</para>
  71
  72 <para>
  73 A socket can also be used to swallow arbitrary
  74 pre-existing top-level windows using gtk_socket_steal(),
  75 though the integration when this is done will not be as close
  76 as between a #GtkPlug and a #GtkSocket.</para>
  77
  78 <note>
  79 <para>
  80 The #GtkPlug and #GtkSocket widgets are currently not available
  81 on all platforms supported by GTK+.
  82 </para>
  83 </note>
  84
  85 <!-- ##### SECTION See_Also ##### -->
  86 <para>
  87 <variablelist>
  88
  89 <varlistentry>
  90 <term>#GtkPlug</term>
  91 <listitem><para>the widget that plugs into a #GtkSocket.</para></listitem>
  92 </varlistentry>
  93
  94 <varlistentry>
  95 <term><ulink url="http://www.freedesktop.org/standards/xembed-spec">XEmbed</ulink></term>
  96 <listitem><para>the XEmbed Protocol Specification.</para></listitem>
  97 </varlistentry>
  98
  99 </variablelist>
 100 </para>
 101
 102 <!-- ##### SECTION Stability_Level ##### -->
 103
 104
 105 <!-- ##### STRUCT GtkSocket ##### -->
 106 <para>
 107 The #GtkSocket structure contains the <structfield>plug_window</structfield>
 108 field.  (This field should be considered read-only. It should
 109 never be set by an application.)
 110 </para>
 111
 112
 113 <!-- ##### SIGNAL GtkSocket::plug-added ##### -->
 114 <para>
 115 This signal is emitted when a client is successfully
 116 added to the socket.
 117 </para>
 118
 119 @socket: the object which received the signal.
 120 <!-- # Unused Parameters # -->
 121 @socket_: the object which received the signal.
 122
 123 <!-- ##### SIGNAL GtkSocket::plug-removed ##### -->
 124 <para>
 125 This signal is emitted when a client is removed from the socket. The
 126 default action is to destroy the #GtkSocket widget, so if you want to
 127 reuse it you must add a signal handler that returns %TRUE.
 128 </para>
 129
 130 @socket: the object which received the signal.
 131 @Returns:
 132 <!-- # Unused Parameters # -->
 133 @socket_: the object which received the signal.
 134
 135 <!-- ##### FUNCTION gtk_socket_new ##### -->
 136 <para>
 137 </para>
 138
 139 @Returns:
 140
 141
 142 <!-- ##### FUNCTION gtk_socket_steal ##### -->
 143 <para>
 144 </para>
 145
 146 @socket_: a #GtkSocket.
 147 @wid:
 148
 149
 150 <!-- ##### FUNCTION gtk_socket_add_id ##### -->
 151 <para>
 152
 153 </para>
 154
 155 @socket_:
 156 @window_id:
 157
 158
 159 <!-- ##### FUNCTION gtk_socket_get_id ##### -->
 160 <para>
 161
 162 </para>
 163
 164 @socket_:
 165 @Returns:
 166
 167