forked from AuroraMiddleware/gtk
171 lines
4.1 KiB
Plaintext
171 lines
4.1 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
GtkSocket
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
Container for widgets from other processes
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
Together with #GtkPlug, #GtkSocket provides the ability
|
|
to embed widgets from one process into another process
|
|
in a fashion that is transparent to the user. One
|
|
process creates a #GtkSocket widget and, passes the
|
|
that widget's window ID to the other process,
|
|
which then creates a #GtkPlug with that window ID.
|
|
Any widgets contained in the #GtkPlug then will appear
|
|
inside the first applications window.
|
|
</para>
|
|
|
|
<para>
|
|
The socket's window ID is obtained by using
|
|
gtk_socket_get_id(). Before using this function,
|
|
the socket must have been realized, and for hence,
|
|
have been added to its parent.
|
|
|
|
<example>
|
|
<title>Obtaining the window ID of a socket.</title>
|
|
<programlisting>
|
|
GtkWidget *socket = gtk_socket_new (<!-- -->);
|
|
gtk_widget_show (socket);
|
|
gtk_container_add (GTK_CONTAINER (parent), socket);
|
|
|
|
/* The following call is only necessary if one of
|
|
* the ancestors of the socket is not yet visible.
|
|
*/
|
|
gtk_widget_realize (socket);
|
|
g_print ("The ID of the sockets window is %#x\n",
|
|
gtk_socket_get_id (socket));
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
Note that if you pass the window ID of the socket to another
|
|
process that will create a plug in the socket, you
|
|
must make sure that the socket widget is not destroyed
|
|
until that plug is created. Violating this rule will
|
|
cause unpredictable consequences, the most likely
|
|
consequence being that the plug will appear as a
|
|
separate toplevel window. You can check if the plug
|
|
has been created by examining the
|
|
<structfield>plug_window</structfield> field of the
|
|
#GtkSocket structure. If this field is non-%NULL,
|
|
then the plug has been successfully created inside
|
|
of the socket.
|
|
</para>
|
|
|
|
<para>
|
|
When GTK+ is notified that the embedded window has been
|
|
destroyed, then it will destroy the socket as well. You
|
|
should always, therefore, be prepared for your sockets
|
|
to be destroyed at any time when the main event loop
|
|
is running. To prevent this from happening, you can
|
|
connect to the #GtkSocket::plug-removed signal.
|
|
</para>
|
|
|
|
<para>
|
|
The communication between a #GtkSocket and a #GtkPlug follows the
|
|
<ulink url="http://www.freedesktop.org/standards/xembed-spec">XEmbed</ulink>
|
|
protocol. This protocol has also been implemented in other toolkits, e.g.
|
|
<application>Qt</application>, allowing the same level of integration
|
|
when embedding a <application>Qt</application> widget in GTK or vice versa.</para>
|
|
|
|
<para>
|
|
A socket can also be used to swallow arbitrary
|
|
pre-existing top-level windows using gtk_socket_steal(),
|
|
though the integration when this is done will not be as close
|
|
as between a #GtkPlug and a #GtkSocket.</para>
|
|
|
|
<note>
|
|
<para>
|
|
The #GtkPlug and #GtkSocket widgets are currently not available
|
|
on all platforms supported by GTK+.
|
|
</para>
|
|
</note>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>#GtkPlug</term>
|
|
<listitem><para>the widget that plugs into a #GtkSocket.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><ulink url="http://www.freedesktop.org/standards/xembed-spec">XEmbed</ulink></term>
|
|
<listitem><para>the XEmbed Protocol Specification.</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### STRUCT GtkSocket ##### -->
|
|
<para>
|
|
The #GtkSocket structure contains the <structfield>plug_window</structfield>
|
|
field. (This field should be considered read-only. It should
|
|
never be set by an application.)
|
|
</para>
|
|
|
|
|
|
<!-- ##### SIGNAL GtkSocket::plug-added ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@socket_:
|
|
|
|
<!-- ##### SIGNAL GtkSocket::plug-removed ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@socket_:
|
|
@Returns:
|
|
|
|
<!-- ##### FUNCTION gtk_socket_new ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_socket_steal ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@socket_: a #GtkSocket.
|
|
@wid:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_socket_add_id ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@socket_:
|
|
@window_id:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_socket_get_id ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@socket_:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_socket_get_plug_window ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@socket_:
|
|
@Returns:
|
|
|
|
|