gtk.Socket
Prev | The gtk Class Reference | Next

## gtk.Socket

gtk.Socket — a container for widgets from other processes.

## Synopsis

    class gtk.Socket(gtk.Container):
        gtk.Socket()
        def add_id(window_id)
        def get_id()
        def get_plug_window()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Socket

## Implemented Interfaces

`gtk.Socket` implements `gtk.Buildable`

## gtk.Socket Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

## gtk.Socket Style Properties

gtk.Widget Style Properties

## gtk.Socket Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

"plug-added" | `def callback(`socket`, `user_param1`, `...`)`
"plug-removed" | `def callback(`socket`, `user_param1`, `...`)`

## Description

Together with a `gtk.Plug`, a `gtk.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 `gtk.Socket` widget and, passes the that widget's window ID to the other process, which then creates a `gtk.Plug` with that window ID. Any widgets contained in the `gtk.Plug` then will appear inside the first applications window. The socket's window ID is obtained by using the `get_id`() method. Before using this function, the socket must have been realized, and added to its parent.

When PyGTK 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 `gtk.Socket` and a `gtk.Plug` follows the XEmbed protocol.

## Constructor

        gtk.Socket()

Returns : | the new `gtk.Socket`.

Creates a new `gtk.Socket`.

## Methods

### gtk.Socket.add_id

        def add_id(window_id)

`window_id` : | the window ID of a client participating in the XEMBED protocol.

The `add_id`() method adds an XEMBED client specified by `window_id`, such as a `gtk.Plug`, to the `gtk.Socket`. The client may be in the same process or in a different process.

To embed a `gtk.Plug` in a `gtk.Socket`, you can either:

- create the `gtk.Plug` by calling gtk.Plug(), then call `gtk.Plug.get_id`() to get the window ID of the plug, and finally pass that to the `gtk.Socket.add_id()`; or,

- call the `gtk.Socket.get_id()` method to get the window ID for the socket, then create the `gtk.Plug` by calling gtk.Plug() passing in that ID. The `gtk.Socket` must have already be added into a toplevel window before you can make this call.

### gtk.Socket.get_id

        def get_id()

Returns : | the window ID for the socket

The `get_id`() method gets the window ID of a `gtk.Socket` widget, which can then be used to create a client embedded inside the socket, for instance with gtk.Plug(). The `gtk.Socket` must have already be added into a toplevel window before you can make this call.

### gtk.Socket.get_plug_window

        def get_plug_window()

Returns : | the window of the plug if available, or `None`.

The `get_plug_window`() method retrieves the window of the plug. Use this to check if the plug has been created inside of the socket.

## Signals

### The "plug-added" gtk.Socket Signal

        def callback(socket, user_param1, ...)

`socket` : | the socket that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "plug-added" signal is emitted when a plug is added to the socket.

### The "plug-removed" gtk.Socket Signal

        def callback(socket, user_param1, ...)

`socket` : | the socket that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the `gtk.Socket` should not be destroyed.

The "plug-removed" signal is emitted when a plug is removed from the socket. The default action is to destroy the `gtk.Socket` widget, so if you want to reuse it you must add a signal handler that returns `True`.

Prev | Up | Next
gtk.SizeGroup | Home | gtk.SpinButton