Xfce Foundation Classes

Xfc::Gtk::Socket Class Reference

A GtkSocket C++ wrapper class. More...

#include <xfc/gtk/socket.hh>

Inheritance diagram for Xfc::Gtk::Socket:

List of all members.

Signal Prototypes

const PlugAddedSignalType plug_added_signal
Plug added signal (see signal_plug_added()).
const PlugRemovedSignalType plug_removed_signal
Plug removed signal (see signal_plug_removed()).

Public Member Functions

Constructors

Socket ()
Construct a new socket.
virtual ~Socket ()
Destructor.

Accessors

GtkSocket * gtk_socket () const
Get a pointer to the GtkSocket structure.
operator GtkSocket * () const
Conversion operator; safely converts a Socket to a GtkSocket pointer.
bool has_plug () const
Returns true if this socket has a plug.
Gdk::Window * plug_window () const
Returns the Gdk::Window for the plug.
Widget * plug_widget () const
Returns the widget embedded into the socket.
bool same_app () const
Returns true if the plug and socket are in the same application.
GdkNativeWindow get_id () const
Gets the window ID of a Socket widget, which can then be used to create a client embedded inside the socket, for instance with Gtk::Plug.

Methods

void add_id (GdkNativeWindow window_id)
Adds an XEMBED client, such as a Plug, to the Socket.

Signal Proxies

const PlugAddedSignalProxy signal_plug_added ()
Connect to the plug_added_signal; emitted when a widget is embedded into a socket.
const PlugRemovedSignalProxy signal_plug_removed ()
Connect to the plug_removed_signal; emitted when a widget is removed from a socket.

Protected Member Functions

Constructors

Socket (GtkSocket *socket, bool owns_reference=false)
Construct a new Socket from an existing GtkSocket.

Detailed Description

A GtkSocket C++ wrapper class.

Together with Plug, Socket 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 Socket widget and, passes that widget's window ID to the other process, which then creates a Plug with that window ID. Any widgets contained in the Plug will then appear inside the first applications window.

The socket's window ID is obtained by using get_id(). Before using this method, the socket must have been realized, and hence, have been added to its parent.

Example: Obtaining the window ID of a socket.

    Gtk::Socket *socket = new Gtk::Socket;
    socket->show();
    parent->add(*socket);
   
    // The following call is only necessary if one of
    // the ancestors of the socket is not yet visible.
    socket->realize();
    g_print("The ID of the sockets window is %x\n", gtk_socket_get_id (socket));

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 plug_window(). If this accessor is non-null, 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. The communication between a Socket and a Plug follows the XEmbed protocol. This protocol has also been implemented in other toolkits, e.g. Qt, allowing the same level of integration when embedding a Qt widget in GTK or vice versa.

Constructor & Destructor Documentation

Xfc::Gtk::Socket::Socket ( GtkSocket * socket,

bool owns_reference = false

) [explicit, protected]

Construct a new Socket from an existing GtkSocket.

Parameters:

socket A pointer to a GtkSocket.

owns_reference Set false if the initial reference count is floating, set true if it's not.

The socket can be a newly created GtkSocket or an existing GtkSocket (see G::Object::Object).

Member Function Documentation

void Xfc::Gtk::Socket::add_id ( GdkNativeWindow window_id )

Adds an XEMBED client, such as a Plug, to the Socket.

Parameters:

window_id The window ID of a client participating in the XEMBED protocol.

The client may be in the same process or in a different process. To embed a Plug in a Socket, you can either create a new Plug, or call Gtk::Plug::get_id() to get the window ID of the plug, and then pass that to add_id(), or you can call Gtk::Socket::get_id() to get the window ID for the socket, and pass to Gtk::Plug in the ID. The Socket must have already be added into a toplevel window before you can make this call.

GdkNativeWindow Xfc::Gtk::Socket::get_id ( ) const

Gets the window ID of a Socket widget, which can then be used to create a client embedded inside the socket, for instance with Gtk::Plug.

Returns:
The window ID for the socket.
The Socket must have already been added into a toplevel window before you can make this call.

Member Data Documentation

const PlugAddedSignalType Xfc::Gtk::Socket::plug_added_signal [static, protected]

Plug added signal (see signal_plug_added()).
Calls a slot with the signature:
void function();

const PlugRemovedSignalType Xfc::Gtk::Socket::plug_removed_signal [static, protected]

Plug removed signal (see signal_plug_removed()).
Calls a slot with the signature:
bool function();

The documentation for this class was generated from the following file:

socket.hh

Xfce Foundation Classes

XFC 4.3