libs/gtkmm2/gtk/gtkmm/socket.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_SOCKET_H
   4 #define _GTKMM_SOCKET_H
   5
   6 #include <glibmm.h>
   7
   8 /* $Id$ */
   9
  10 /* Copyright (C) 1998-2002 The gtkmm Development Team
  11  *
  12  * This library is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Library General Public
  14  * License as published by the Free Software Foundation; either
  15  * version 2 of the License, or (at your option) any later version.
  16  *
  17  * This library is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with this library; if not, write to the Free
  24  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25  */
  26
  27 #include <gtkmm/container.h>
  28 #include <gdkmm/types.h>
  29
  30
  31 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  32 typedef struct _GtkSocket GtkSocket;
  33 typedef struct _GtkSocketClass GtkSocketClass;
  34 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  35
  36
  37 namespace Gtk
  38 { class Socket_Class; } // namespace Gtk
  39 namespace Gtk
  40 {
  41
  42 /** Container for widgets from other processes.
  43  * Together with Gtk::Plug, Gtk::Socket provides the ability to embed
  44  * widgets from one process into another process in a fashion that is
  45  * transparent to the user. One process creates a Gtk::Socket widget and,
  46  * passes the that widget's window ID to the other process, which then
  47  * creates a Gtk::Plug with that window ID. Any widgets contained in the
  48  * Gtk::Plug then will appear inside the first applications window.
  49  *
  50  * The socket's window ID is obtained by using get_id(). Before using this
  51  * function, the socket must have been realized, and for hence, have been
  52  * added to its parent.
  53  *
  54  * @code
  55  * Gtk::Socket socket;
  56  * parent.add(socket);
  57  *
  58  * // The following call is only necessary if one of the ancestors of the
  59  * // socket is not yet visible
  60  * socket.realize();
  61  *
  62  * cout << "The ID of the sockets window is: " << socket.get_id() << endl;
  63  *
  64  * @endcode
  65  *
  66  * Note that if you pass the window ID of the socket to another process that
  67  * will create a plug in the socket, you must make sure that the socket
  68  * widget is not destroyed until that plug is created. Violating this rule
  69  * will cause unpredictable consequences, the most likely consequence being
  70  * that the plug will appear as a separate toplevel window. You can check if
  71  * the plug has been created by examining the plug_window member of the
  72  * GtkSocket structure returned by gobj(). If this field is non-NULL, then
  73  * the plug has been successfully created inside of the socket.
  74  *
  75  * When gtkmm is notified that the embedded window has been destroyed, then
  76  * it will destroy the socket as well. You should always, therefore, be
  77  * prepared for your sockets to be destroyed at any time when the main event
  78  * loop is running.
  79  *
  80  * The communication between a Gtk::Socket and a Gtk::Plug follows the
  81  * XEmbed protocol. This protocol has also been implemented in other
  82  * toolkits, e.g. Qt, allowing the same level of integration when embedding
  83  * a Qt widget in gtkmm or vice versa.
  84  *
  85  * @ingroup Widgets
  86  * @ingroup Containers
  87  */
  88
  89 class Socket : public Container
  90 {
  91   public:
  92 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  93   typedef Socket CppObjectType;
  94   typedef Socket_Class CppClassType;
  95   typedef GtkSocket BaseObjectType;
  96   typedef GtkSocketClass BaseClassType;
  97 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  98
  99   virtual ~Socket();
 100
 101 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 102
 103 private:
 104   friend class Socket_Class;
 105   static CppClassType socket_class_;
 106
 107   // noncopyable
 108   Socket(const Socket&);
 109   Socket& operator=(const Socket&);
 110
 111 protected:
 112   explicit Socket(const Glib::ConstructParams& construct_params);
 113   explicit Socket(GtkSocket* castitem);
 114
 115 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 116
 117 public:
 118 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 119   static GType get_type()      G_GNUC_CONST;
 120   static GType get_base_type() G_GNUC_CONST;
 121 #endif
 122
 123   ///Provides access to the underlying C GtkObject.
 124   GtkSocket*       gobj()       { return reinterpret_cast<GtkSocket*>(gobject_); }
 125
 126   ///Provides access to the underlying C GtkObject.
 127   const GtkSocket* gobj() const { return reinterpret_cast<GtkSocket*>(gobject_); }
 128
 129
 130 public:
 131   //C++ methods used to invoke GTK+ virtual functions:
 132
 133 protected:
 134   //GTK+ Virtual Functions (override these to change behaviour):
 135
 136   //Default Signal Handlers::
 137   virtual void on_plug_added();
 138   virtual bool on_plug_removed();
 139
 140
 141 private:
 142
 143
 144   //This is not available in on Win32.
 145 //This source file will not be compiled,
 146 //and the class will not be registered in wrap_init.h or wrap_init.cc
 147
 148 public:
 149   Socket();
 150
 151
 152   /** Adds an XEMBED client, such as a Gtk::Plug, to the Gtk::Socket.  The
 153    * client may be in the same process or in a different process.
 154    *
 155    * To embed a Gtk::Plug in a Gtk::Socket, you can either create the
 156    * Gtk::Plug with <tt>gtk_plug_new (0)</tt>, call
 157    * Gtk::Plug::get_id() to get the window ID of the plug, and then pass that to the
 158    * add_id(), or you can call get_id() to get the
 159    * window ID for the socket, and call Gtk::Plug::new() passing in that
 160    * ID.
 161    *
 162    * The Gtk::Socket must have already be added into a toplevel window
 163    * before you can make this call.
 164    * @param window_id The window ID of a client participating in the XEMBED protocol.
 165    */
 166   void add_id(Gdk::NativeWindow window_id);
 167
 168   /** Gets the window ID of a Gtk::Socket widget, which can then
 169    * be used to create a client embedded inside the socket, for
 170    * instance with Gtk::Plug::new().
 171    *
 172    * The Gtk::Socket must have already be added into a toplevel window
 173    * before you can make this call.
 174    * @return The window ID for the socket.
 175    */
 176   Gdk::NativeWindow get_id() const;
 177
 178
 179   Glib::SignalProxy0< void > signal_plug_added();
 180
 181
 182   Glib::SignalProxy0< bool > signal_plug_removed();
 183
 184
 185 };
 186
 187 } // namespace Gtk
 188
 189
 190 namespace Glib
 191 {
 192   /** @relates Gtk::Socket
 193    * @param object The C instance
 194    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 195    * @result A C++ instance that wraps this C instance.
 196    */
 197   Gtk::Socket* wrap(GtkSocket* object, bool take_copy = false);
 198 }
 199 #endif /* _GTKMM_SOCKET_H */
 200