[gtk+] Add a gtkx.h header for X11-specific GTK+ api

From: Matthias Clasen <matthiasc src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk+] Add a gtkx.h header for X11-specific GTK+ api
Date: Sat, 29 Jan 2011 19:35:18 +0000 (UTC)
commit f783a75d61dbe7ae511bf65b6c3aafaffa8b4216
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Jan 29 14:16:47 2011 -0500

    Add a gtkx.h header for X11-specific GTK+ api
    
    This keeps us from pulling gdkx.h into gtk.h
    
    https://bugzilla.gnome.org/show_bug.cgi?id=640902

 docs/reference/gtk/gtk3.types     |    2 +-
 docs/reference/gtk/x11.sgml       |    7 ++++
 gtk/Makefile.am                   |    5 ++-
 gtk/gtk.h                         |    2 -
 gtk/gtkplug.c                     |   31 +++++++++--------
 gtk/gtkplug.h                     |   41 ++++++++++-------------
 gtk/gtksocket.c                   |   67 ++++++++++++++++++-------------------
 gtk/gtksocket.h                   |   21 +++++-------
 gtk/gtkwidget.c                   |    1 +
 gtk/gtkx.h                        |   29 ++++++++++++++++
 modules/other/gail/gail.c         |    2 +-
 modules/other/gail/gailtoplevel.c |    2 +-
 modules/other/gail/gailwindow.c   |    2 +-
 tests/testsocket.c                |    1 +
 tests/testsocket_common.c         |    2 +-
 15 files changed, 123 insertions(+), 92 deletions(-)
---
diff --git a/docs/reference/gtk/gtk3.types b/docs/reference/gtk/gtk3.types
index 47295b1..bf2ca64 100644
--- a/docs/reference/gtk/gtk3.types
+++ b/docs/reference/gtk/gtk3.types
@@ -1,4 +1,4 @@
-#include <gtk/gtk.h>
+#include <gtk/gtkx.h>
 #include <gtk/gtkunixprint.h>
 
 gtk_about_dialog_get_type
diff --git a/docs/reference/gtk/x11.sgml b/docs/reference/gtk/x11.sgml
index 0fede1b..0a8ad33 100644
--- a/docs/reference/gtk/x11.sgml
+++ b/docs/reference/gtk/x11.sgml
@@ -31,6 +31,13 @@ see <link linkend="gdk-X-Window-System-Interaction">GDK X Window
 System interaction</link> in the GDK manual.
 </para>
 
+<para>
+GTK+ includes an cross-process embedding facility in the form of
+the #GtkSocket and #GtkPlug widgets. These are X11-specific, and
+you have to include the <filename>gtk/gtkx.h</filename> header
+to use them.
+</para>
+
 <refsect2 id="x11-cmdline">
 <title>X11-specific commandline options</title>
 
diff --git a/gtk/Makefile.am b/gtk/Makefile.am
index b456464..508c4aa 100644
--- a/gtk/Makefile.am
+++ b/gtk/Makefile.am
@@ -144,6 +144,7 @@ endif
 # by configure)
 gtk_public_h_sources = 		\
 	gtk.h			\
+	gtkx.h			\
 	gtkaboutdialog.h	\
 	gtkaccelgroup.h		\
 	gtkaccellabel.h		\
@@ -866,7 +867,7 @@ gtktypebuiltins.c: @REBUILD@ $(gtk_public_h_sources) gtktypebuiltins.c.template
 	&& rm -f xgen-gtbc
 
 gtktypefuncs.c: @REBUILD@ stamp-gtktypebuiltins.h $(top_srcdir)/gtk/*.h $(top_srcdir)/gdk/*.h Makefile
-	$(AM_V_GEN) echo '#include <gtk/gtk.h>' > xgen-gtfsrc.c && \
+	$(AM_V_GEN) echo '#include <gtk/gtkx.h>' > xgen-gtfsrc.c && \
 	  ${CPP} $(DEFS) $(INCLUDES) -DGTK_ENABLE_BROKEN $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) xgen-gtfsrc.c | \
 	  $(GREP) -o '\bg[td]k_[a-zA-Z0-9_]*_get_type\b' | \
 	  sort | uniq | \
@@ -969,7 +970,7 @@ Gtk_3_0_gir_SCANNERFLAGS = 			\
 if USE_X11
 Gtk_3_0_gir_SCANNERFLAGS += --add-include-path=$(top_builddir)/gdk/x11
 endif
-Gtk_3_0_gir_SCANNERFLAGS += --c-include="gtk/gtk.h"
+Gtk_3_0_gir_SCANNERFLAGS += --c-include="gtk/gtkx.h"
 Gtk_3_0_gir_INCLUDES = Atk-1.0 Gdk-3.0
 Gtk_3_0_gir_CFLAGS = \
 		$(INCLUDES) \
diff --git a/gtk/gtk.h b/gtk/gtk.h
index 6f984ea..0a72d24 100644
--- a/gtk/gtk.h
+++ b/gtk/gtk.h
@@ -143,7 +143,6 @@
 #include <gtk/gtkpagesetup.h>
 #include <gtk/gtkpapersize.h>
 #include <gtk/gtkpaned.h>
-#include <gtk/gtkplug.h>
 #include <gtk/gtkprintcontext.h>
 #include <gtk/gtkprintoperation.h>
 #include <gtk/gtkprintoperationpreview.h>
@@ -175,7 +174,6 @@
 #include <gtk/gtkshow.h>
 #include <gtk/gtksizegroup.h>
 #include <gtk/gtksizerequest.h>
-#include <gtk/gtksocket.h>
 #include <gtk/gtkspinbutton.h>
 #include <gtk/gtkspinner.h>
 #include <gtk/gtkstatusbar.h>
diff --git a/gtk/gtkplug.c b/gtk/gtkplug.c
index 8cb9a4e..b363d1d 100644
--- a/gtk/gtkplug.c
+++ b/gtk/gtkplug.c
@@ -44,27 +44,30 @@
  * SECTION:gtkplug
  * @Short_description: Toplevel for embedding into other processes
  * @Title: GtkPlug
+ * @include: gtk/gtkx.h
  * @See_also: #GtkSocket
  *
- * Together with #GtkSocket, #GtkPlug 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
- * ID of that widget's window 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 application's window.
+ * Together with #GtkSocket, #GtkPlug 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 ID of that widget's window 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
+ * application's window.
  *
  * 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.
+ * 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.
  *
  * <note>
- * The #GtkPlug and #GtkSocket widgets are only available when GTK is
- * compiled for the X11 platform and %GDK_WINDOWING_X11 is defined.
- * They can only be used on a #GdkX11Display.
+ * The #GtkPlug and #GtkSocket widgets are only available when GTK+
+ * is compiled for the X11 platform and %GDK_WINDOWING_X11 is defined.
+ * They can only be used on a #GdkX11Display. To use #GtkPlug and
+ * #GtkSocket, you need to include the <filename>gtk/gtkx.h</filename>
+ * header.
  * </note>
  */
 
diff --git a/gtk/gtkplug.h b/gtk/gtkplug.h
index f34f6d2..77ea08b 100644
--- a/gtk/gtkplug.h
+++ b/gtk/gtkplug.h
@@ -23,21 +23,20 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  */
 
-#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
-#error "Only <gtk/gtk.h> can be included directly."
+#if !defined (__GTKX_H_INSIDE__) && !defined (GTK_COMPILATION)
+#error "Only <gtk/gtkx.h> can be included directly."
 #endif
 
 #ifndef __GTK_PLUG_H__
 #define __GTK_PLUG_H__
 
-#include <gdk/gdk.h>
+#include <gtk/gtk.h>
 
 #ifdef GDK_WINDOWING_X11
 
 #include <gdk/gdkx.h>
 
 #include <gtk/gtksocket.h>
-#include <gtk/gtkwindow.h>
 
 
 G_BEGIN_DECLS
@@ -50,9 +49,9 @@ G_BEGIN_DECLS
 #define GTK_PLUG_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_PLUG, GtkPlugClass))
 
 
-typedef struct _GtkPlug              GtkPlug;
-typedef struct _GtkPlugPrivate       GtkPlugPrivate;
-typedef struct _GtkPlugClass         GtkPlugClass;
+typedef struct _GtkPlug        GtkPlug;
+typedef struct _GtkPlugPrivate GtkPlugPrivate;
+typedef struct _GtkPlugClass   GtkPlugClass;
 
 
 struct _GtkPlug
@@ -75,26 +74,22 @@ struct _GtkPlugClass
   void (*_gtk_reserved4) (void);
 };
 
-
-GType      gtk_plug_get_type  (void) G_GNUC_CONST;
+GType      gtk_plug_get_type              (void) G_GNUC_CONST;
 
 #ifndef GDK_MULTIHEAD_SAFE
-void       gtk_plug_construct             (GtkPlug         *plug,
-			                   Window           socket_id);
-GtkWidget* gtk_plug_new                   (Window           socket_id);
+void       gtk_plug_construct             (GtkPlug    *plug,
+                                           Window      socket_id);
+GtkWidget *gtk_plug_new                   (Window      socket_id);
 #endif
 
-void       gtk_plug_construct_for_display (GtkPlug         *plug,
-					   GdkDisplay      *display,
-					   Window           socket_id);
-GtkWidget* gtk_plug_new_for_display       (GdkDisplay      *display,
-					   Window           socket_id);
-
-Window     gtk_plug_get_id                (GtkPlug         *plug);
-
-gboolean  gtk_plug_get_embedded (GtkPlug         *plug);
-
-GdkWindow *gtk_plug_get_socket_window (GtkPlug   *plug);
+void       gtk_plug_construct_for_display (GtkPlug    *plug,
+                                           GdkDisplay *display,
+                                           Window      socket_id);
+GtkWidget *gtk_plug_new_for_display       (GdkDisplay *display,
+                                           Window      socket_id);
+Window     gtk_plug_get_id                (GtkPlug    *plug);
+gboolean   gtk_plug_get_embedded          (GtkPlug    *plug);
+GdkWindow *gtk_plug_get_socket_window     (GtkPlug    *plug);
 
 G_END_DECLS
 
diff --git a/gtk/gtksocket.c b/gtk/gtksocket.c
index 8b92a23..68b1042 100644
--- a/gtk/gtksocket.c
+++ b/gtk/gtksocket.c
@@ -56,21 +56,19 @@
  * SECTION:gtksocket
  * @Short_description: Container for widgets from other processes
  * @Title: GtkSocket
+ * @include: gtk/gtkx.h
  * @See_also: #GtkPlug, <ulink url="http://www.freedesktop.org/Standards/xembed-spec";>XEmbed</ulink>
  *
- * 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
- * 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 application's window.
+ * 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 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 application's window.
  *
- * 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.
+ * 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>
@@ -79,9 +77,9 @@
  * gtk_widget_show (socket);
  * gtk_container_add (GTK_CONTAINER (parent), socket);
  *
- * /<!---->* The following call is only necessary if one of
+ * /&ast; The following call is only necessary if one of
  *  * the ancestors of the socket is not yet visible.
- *  *<!---->/
+ *  &ast;/
  * gtk_widget_realize (socket);
  * g_print ("The ID of the sockets window is %#x\n",
  *          gtk_socket_get_id (socket));
@@ -89,33 +87,34 @@
  * </example>
  *
  * 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 using gtk_socket_get_plug_window(). If
- * it returns a non-%NULL value, then the plug has been
+ * 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 using gtk_socket_get_plug_window().
+ * If it returns a non-%NULL value, then the plug has been
  * successfully created inside of the socket.
  *
- * 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.
+ * 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.
  *
  * 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.
+ * 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.
  *
  * <note>
- * The #GtkPlug and #GtkSocket widgets are only available when GTK is
- * compiled for the X11 platform and %GDK_WINDOWING_X11 is defined.
- * They can only be used on a #GdkX11Display.
+ * The #GtkPlug and #GtkSocket widgets are only available when GTK+
+ * is compiled for the X11 platform and %GDK_WINDOWING_X11 is defined.
+ * They can only be used on a #GdkX11Display. To use #GtkPlug and
+ * #GtkSocket, you need to include the <filename>gtk/gtkx.h</filename>
+ * header.
  * </note>
  */
 
diff --git a/gtk/gtksocket.h b/gtk/gtksocket.h
index c5be024..2415b14 100644
--- a/gtk/gtksocket.h
+++ b/gtk/gtksocket.h
@@ -23,19 +23,18 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  */
 
-#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
-#error "Only <gtk/gtk.h> can be included directly."
+#if !defined (__GTKX_H_INSIDE__) && !defined (GTK_COMPILATION)
+#error "Only <gtk/gtkx.h> can be included directly."
 #endif
 
 #ifndef __GTK_SOCKET_H__
 #define __GTK_SOCKET_H__
 
-#include <gdk/gdk.h>
+#include <gtk/gtk.h>
 
 #ifdef GDK_WINDOWING_X11
 
 #include <gdk/gdkx.h>
-#include <gtk/gtkcontainer.h>
 
 G_BEGIN_DECLS
 
@@ -72,14 +71,12 @@ struct _GtkSocketClass
   void (*_gtk_reserved4) (void);
 };
 
-
-GType          gtk_socket_get_type (void) G_GNUC_CONST;
-GtkWidget*     gtk_socket_new      (void);
-
-void            gtk_socket_add_id (GtkSocket       *socket_,
-				   Window            window);
-Window          gtk_socket_get_id (GtkSocket       *socket_);
-GdkWindow*      gtk_socket_get_plug_window (GtkSocket       *socket_);
+GType      gtk_socket_get_type        (void) G_GNUC_CONST;
+GtkWidget *gtk_socket_new             (void);
+void       gtk_socket_add_id          (GtkSocket *socket_,
+                                       Window     window);
+Window     gtk_socket_get_id          (GtkSocket *socket_);
+GdkWindow *gtk_socket_get_plug_window (GtkSocket *socket_);
 
 G_END_DECLS
 
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index e9ffc38..e77a5fb 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -63,6 +63,7 @@
 #include "gtkmodifierstyle.h"
 #include "gtkversion.h"
 #include "gtkdebug.h"
+#include "gtkplug.h"
 #include "gtktypebuiltins.h"
 
 
diff --git a/gtk/gtkx.h b/gtk/gtkx.h
new file mode 100644
index 0000000..8cd4b0f
--- /dev/null
+++ b/gtk/gtkx.h
@@ -0,0 +1,29 @@
+/* GTK - The GIMP Toolkit
+ * Copyright (C) 2011 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free
+ * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+#ifndef __GTK_X_H__
+#define __GTK_X_H__
+
+#define __GTKX_H_INSIDE__
+
+#include <gtk/gtksocket.h>
+#include <gtk/gtkplug.h>
+
+#undef __GTKX_H_INSIDE__
+
+#endif /* __GTK_X_H__ */
diff --git a/modules/other/gail/gail.c b/modules/other/gail/gail.c
index cb12163..ce4e6ce 100644
--- a/modules/other/gail/gail.c
+++ b/modules/other/gail/gail.c
@@ -22,7 +22,7 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-#include <gtk/gtk.h>
+#include <gtk/gtkx.h>
 #include "gail.h"
 #include "gailfactory.h"
 
diff --git a/modules/other/gail/gailtoplevel.c b/modules/other/gail/gailtoplevel.c
index 83a8583..29ff3a5 100644
--- a/modules/other/gail/gailtoplevel.c
+++ b/modules/other/gail/gailtoplevel.c
@@ -22,7 +22,7 @@
 #include <stdlib.h>
 #include <string.h>
 
-#include <gtk/gtk.h>
+#include <gtk/gtkx.h>
 
 #include "gailtoplevel.h"
 
diff --git a/modules/other/gail/gailwindow.c b/modules/other/gail/gailwindow.c
index 73b1993..1dd47b2 100644
--- a/modules/other/gail/gailwindow.c
+++ b/modules/other/gail/gailwindow.c
@@ -21,7 +21,7 @@
 
 #include <string.h>
 
-#include <gtk/gtk.h>
+#include <gtk/gtkx.h>
 
 #include "gailwindow.h"
 #include "gailtoplevel.h"
diff --git a/tests/testsocket.c b/tests/testsocket.c
index daa3053..f936ae5 100644
--- a/tests/testsocket.c
+++ b/tests/testsocket.c
@@ -21,6 +21,7 @@
 
 #include "config.h"
 #include <gtk/gtk.h>
+#include <gtk/gtkx.h>
 
 #include <string.h>
 #include <stdlib.h>
diff --git a/tests/testsocket_common.c b/tests/testsocket_common.c
index 995dbf9..510d6ff 100644
--- a/tests/testsocket_common.c
+++ b/tests/testsocket_common.c
@@ -21,7 +21,7 @@
 #include "config.h"
 #include <gtk/gtk.h>
 #if defined (GDK_WINDOWING_X11)
-#include "x11/gdkx.h"
+#include <gtk/gtkx.h>
 #elif defined (GDK_WINDOWING_WIN32)
 #include "win32/gdkwin32.h"
 #endif
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]