Home

QtXEmbedContainer Class Reference

The QtXEmbedContainer class provides an XEmbed container widget. More...

#include <qtxembed.h>

List of all member functions.

Public Members

Signals


Detailed Description

The QtXEmbedContainer class provides an XEmbed container widget.

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

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

When a client has been embedded and the container receives tab focus, focus is passed on to the client. When the client reaches the end of his focus chain, focus is passed back to the container. Window activation, accelerator support, modality and drag and drop (XDND) are also handled.

QtXEmbedContainer is commonly used for writing panels or toolbars that hold applets, or for swallowing X11 applications. When writing a panel application, one container widget is created on the toolbar, and it can then either swallow another widget using embed(), or allow an XEmbed client to be embedded into itself. The container's X11 window ID, which is retrieved with winId(), must then be known to the client. After embedding, the client's window ID can be retrieved with clientWinId().

In the following example, a container widget is created as the main widget. It then invokes an application called "client" in the current working directory, passing its window ID as a command line argument.

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

            QtXEmbedContainer container(0);
            app.setMainWidget(&container);
            container.show();

            QProcess proc(&container);
            proc.addArgument("./client");
            proc.addArgument(container.winId());
            if (!proc.start()) {
                // An error occurred
                return 1;
            }

            return app.exec();
        }
    

When the client is embedded, the container emits the signal clientIsEmbedded(). The signal clientClosed() is emitted when a client closes.

It is possible for QtXEmbedContainer to embed XEmbed clients from toolkits other than Qt, such as GTK+. Non-XEmbed clients can also be embedded, but the XEmbed specific features such as window activation and focus handling are then lost.

The GTK+ equivalent of QtXEmbedContainer is GtkSocket. The KDE widget is called QXEmbed.

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


Member Type Documentation

QtXEmbedContainer::Errors


Member Function Documentation

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

Creates a QtXEmbedContainer object. The parent and name arguments are passed on to QWidget.

QtXEmbedContainer::~QtXEmbedContainer ()

Destructs a QtXEmbedContainer.

void QtXEmbedContainer::clientClosed () [signal]

This signal is emitted by the container when the client closes.

Example: swallow.cpp.

void QtXEmbedContainer::clientIsEmbedded () [signal]

This signal is emitted by the container when a client has been embedded.

Example: swallow.cpp.

WId QtXEmbedContainer::clientWinId () const

If the container has a client, this function returns the X11 window ID of the client; otherwise it returns 0.

void QtXEmbedContainer::discardClient ()

Detaches the client from the embedder. The client will appear as a standalone window on the desktop.

Example: swallow.cpp.

void QtXEmbedContainer::embed ( WId id, bool xEmbedClient = true )

Instructs the container to embed the X11 window with window ID id. The client window will then move on top of the container window and be resized to fit into the container.

The id should be the ID of a window controlled by an XEmbed enabled application, but this is not mandatory. If id does not belong to an XEmbed client, then focus handling, activation, accelerators and other features will not work properly.

Example: swallow.cpp.

void QtXEmbedContainer::error ( int ) [signal]

This signal is emitted if an error occurred when embedding or communicating with a client.

See also QtXEmbedContainer::Errors.

Example: swallow.cpp.


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

Copyright © 2003 TrolltechTrademarks
Qt Solutions