forked from AuroraMiddleware/gtk
372853b107
2001-09-08 Havoc Pennington <hp@pobox.com> * gtk/gtk-sections.txt: put GtkPacker back in here so it won't be in gtk-unused.txt, but don't put it back in gtk-docs.sgml. Tons of other additions from gtk-unused.txt, but mostly skipping all the tree stuff for now. 2001-09-08 Havoc Pennington <hp@pobox.com> * gtk/gtktreeviewcolumn.c (gtk_tree_view_column_add_attribute): docs fixes * gtk/gtktable.c (gtk_table_get_col_spacing): docs fixes * gtk/gtkspinbutton.c (gtk_spin_button_get_increments): docs fixes * gtk/gtksocket.c (gtk_socket_steal): docs fixes * gtk/gtkscrolledwindow.h: docs fixes * gtk/gtkimage.c (gtk_image_new): docs fixes
153 lines
3.6 KiB
Plaintext
153 lines
3.6 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
|
|
XID of that widget's window to the other process,
|
|
which then creates a #GtkPlug window with that XID.
|
|
Any widgets contained in the #GtkPlug then will appear
|
|
inside the first applications window.
|
|
</para>
|
|
|
|
<para>
|
|
The XID of the socket's window is obtained by using
|
|
the GTK_WINDOW_XWINDOW() macro from the header
|
|
file <gdk/gdkx.h>. Before using this macro,
|
|
the socket must have been realized, and for hence,
|
|
have been added to its parent.
|
|
|
|
<example>
|
|
<title> Obtaining the XID of a socket </title>
|
|
<programlisting>
|
|
#include <gdk/gdkx.h>
|
|
|
|
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 XID of the sockets window is %#x\n",
|
|
GDK_WINDOW_XWINDOW (socket->window));
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
Note that if you pass the XID 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 succesfully 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.
|
|
</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>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>#GtkPlug</term>
|
|
<listitem><para>the widget that plugs into a #GtkSocket.</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
<!-- ##### STRUCT GtkSocket ##### -->
|
|
<para>
|
|
The #GtkEditable structure contains the following field.
|
|
(This field should be considered read-only. It should
|
|
never be set by an application.)
|
|
|
|
<informaltable pgwide=1 frame="none" role="struct">
|
|
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
|
|
<tbody>
|
|
|
|
<row>
|
|
<entry>#GdkWindow *plug_window;</entry>
|
|
<entry>the window embedded inside this #GtkSocket.</entry>
|
|
</row>
|
|
|
|
</tbody></tgroup></informaltable>
|
|
</para>
|
|
|
|
|
|
<!-- ##### 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:
|
|
@id:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_socket_get_id ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@socket:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### SIGNAL GtkSocket::plug-added ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@socket: the object which received the signal.
|
|
|
|
<!-- ##### SIGNAL GtkSocket::plug-removed ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@socket: the object which received the signal.
|
|
@Returns:
|
|
|