Home

QtXEmbedClient Class Reference

The QtXEmbedClient class provides an XEmbed client widget. More...

#include <qtxembed.h>

List of all member functions.

Public Members

Signals


Detailed Description

The QtXEmbedClient class provides an XEmbed client widget.

XEmbed is an X11 protocol that supports the embedding of a widget from one application into another application.

An XEmbed client is a window that is embedded into a container. A container is the graphical location that embeds (or swallows) an external client.

QtXEmbedClient is a widget used for writing XEmbed applets or plugins. When it has been embedded and the container receives tab focus, focus is passed on to the client. When the client reaches the end of its focus chain, focus is passed back to the container. Window activation, accelerator support, modality and drag and drop (XDND) are also handled.

The client and container can both initiate the embedding. If the client is the initiator, the X11 window ID of the container that it wants to embed itself into must be known. If the client calls embedInto() passing this window ID, it will be embedded.

If the container initiates the embedding, the window ID of the client must be known. The container calls embed(), passing the window ID, to embed the client.

This example shows an application where the client calls embedInto() with the window ID passed as a command line argument:

        int main(int argc, char *argv[])
        {
            QApplication app(argc, argv);

            if (app.argc() != 2) {
              // Error - expected window id as argument.
              return 1;
            }

            QtXEmbedClient client(0);
            app.setMainWindow(&client);

            client.embedInto(app.argv()[1]);
            client.show();

            return app.exec();
        }
    

The problem of obtaining the window IDs is often solved by the container invoking the client (as a panel invokes a docked applet) as a seperate process, passing its window ID to the client as a command line argument. The client can then call embedInto() with the container's window ID, as shown in the example code above. Similarily, the client can report its window ID to the container through IPC, in which case the container can embed the client.

When the client has been embedded, it emits the signal embedded(). If it is closed by the container, the client emits containerClosed(). If an error occurs when embedding, error() is emitted.

There are XEmbed widgets available for KDE and GTK+. The GTK+ equivalent of QtXEmbedClient is GtkPlug. The KDE widget is called QXEmbed.

See also QtXEmbedContainer and http://www.freedesktop.org/standards/xembed-spec/.


Member Type Documentation

QtXEmbedClient::Errors


Member Function Documentation

QtXEmbedClient::QtXEmbedClient ( QWidget * parent = 0, const char * name = 0 )

Constructs a QtXEmbedClient object. The parent and name arguments are passed on to QWidget's constructor.

QtXEmbedClient::~QtXEmbedClient ()

Destructs the QtXEmbedClient object. If the client is embedded when deleted, it is hidden and then detached from its container, so that the container is free to embed a new client.

void QtXEmbedClient::containerClosed () [signal]

This signal is emitted by the client when the container closes the client. This can happen if the container itself closes, or if the client is rejected.

The container can reject a client for any reason, but the most common cause of a rejection is when an attempt is made to embed a client into a container that already has an embedded client.

WId QtXEmbedClient::containerWinId () const

If the client is embedded, returns the window ID of the container; otherwize returns 0.

void QtXEmbedClient::embedInto ( WId id )

When this function is called, the client embeds itself into the container whose window ID is id.

If id is not the window ID of a container this function will behave unpredictably.

void QtXEmbedClient::embedded () [signal]

This signal is emitted by the client that has been embedded by an XEmbed container.

void QtXEmbedClient::error ( int ) [signal]

This signal is emitted if an error occurred as a result of embedding into or communicating with a container.

See also QtXEmbedClient::Errors.


This file is part of the Qt Solutions. Copyright © 1995-2003 Trolltech. All Rights Reserved.

Copyright © 2003 TrolltechTrademarks
Qt Solutions