<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /tmp/qt-4.2.1-harald-1161357942206/qt-x11-opensource-src-4.2.1/src/gui/kernel/qx11embed_x11.cpp -->
<head>
<title>Qt 4.2: QX11EmbedWidget Class Reference</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top" width="32"><a href="http://www.trolltech.com/products/qt"><img src="images/qt-logo.png" align="left" width="32" height="32" border="0" /></a></td>
<td width="1"> </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="mainclasses.html"><font color="#004faf">Main Classes</font></a> · <a href="groups.html"><font color="#004faf">Grouped Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a> · <a href="functions.html"><font color="#004faf">Functions</font></a></td>
<td align="right" valign="top" width="230"><a href="http://www.trolltech.com"><img src="images/trolltech-logo.png" align="right" width="203" height="32" border="0" /></a></td></tr></table><h1 align="center">QX11EmbedWidget Class Reference<br /><sup><sup>[<a href="qtgui.html">QtGui</a> module]</sup></sup></h1>
<p>The QX11EmbedWidget class provides an XEmbed client widget. <a href="#details">More...</a></p>
<pre> #include <QX11EmbedWidget></pre><p>Inherits <a href="qwidget.html">QWidget</a>.</p>
<ul>
<li><a href="qx11embedwidget-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-types"></a>
<h3>Public Types</h3>
<ul>
<li><div class="fn"/>enum <b><a href="qx11embedwidget.html#Error-enum">Error</a></b> { Unknown, InvalidWindowID }</li>
</ul>
<a name="public-functions"></a>
<h3>Public Functions</h3>
<ul>
<li><div class="fn"/><b><a href="qx11embedwidget.html#QX11EmbedWidget">QX11EmbedWidget</a></b> ( QWidget * <i>parent</i> = 0 )</li>
<li><div class="fn"/><b><a href="qx11embedwidget.html#dtor.QX11EmbedWidget">~QX11EmbedWidget</a></b> ()</li>
<li><div class="fn"/>WId <b><a href="qx11embedwidget.html#containerWinId">containerWinId</a></b> () const</li>
<li><div class="fn"/>void <b><a href="qx11embedwidget.html#embedInto">embedInto</a></b> ( WId <i>id</i> )</li>
<li><div class="fn"/>Error <b><a href="qx11embedwidget.html#error">error</a></b> () const</li>
</ul>
<ul>
<li><div class="fn"/>195 public functions inherited from <a href="qwidget.html#public-functions">QWidget</a></li>
<li><div class="fn"/>29 public functions inherited from <a href="qobject.html#public-functions">QObject</a></li>
<li><div class="fn"/>12 public functions inherited from <a href="qpaintdevice.html#public-functions">QPaintDevice</a></li>
</ul>
<a name="signals"></a>
<h3>Signals</h3>
<ul>
<li><div class="fn"/>void <b><a href="qx11embedwidget.html#containerClosed">containerClosed</a></b> ()</li>
<li><div class="fn"/>void <b><a href="qx11embedwidget.html#embedded">embedded</a></b> ()</li>
<li><div class="fn"/>void <b><a href="qx11embedwidget.html#error-2">error</a></b> ( QX11EmbedWidget::Error <i>error</i> )</li>
</ul>
<ul>
<li><div class="fn"/>1 signal inherited from <a href="qwidget.html#signals">QWidget</a></li>
<li><div class="fn"/>1 signal inherited from <a href="qobject.html#signals">QObject</a></li>
</ul>
<h3>Additional Inherited Members</h3>
<ul>
<li><div class="fn"/>55 properties inherited from <a href="qwidget.html#properties">QWidget</a></li>
<li><div class="fn"/>1 property inherited from <a href="qobject.html#properties">QObject</a></li>
<li><div class="fn"/>19 public slots inherited from <a href="qwidget.html#public-slots">QWidget</a></li>
<li><div class="fn"/>1 public slot inherited from <a href="qobject.html#public-slots">QObject</a></li>
<li><div class="fn"/>4 static public members inherited from <a href="qwidget.html#static-public-members">QWidget</a></li>
<li><div class="fn"/>5 static public members inherited from <a href="qobject.html#static-public-members">QObject</a></li>
<li><div class="fn"/>38 protected functions inherited from <a href="qwidget.html#protected-functions">QWidget</a></li>
<li><div class="fn"/>7 protected functions inherited from <a href="qobject.html#protected-functions">QObject</a></li>
<li><div class="fn"/>1 protected function inherited from <a href="qpaintdevice.html#protected-functions">QPaintDevice</a></li>
<li><div class="fn"/>1 protected slot inherited from <a href="qwidget.html#protected-slots">QWidget</a></li>
</ul>
<a name="details"></a>
<hr />
<h2>Detailed Description</h2>
<p>The QX11EmbedWidget class provides an XEmbed client widget.</p>
<p>XEmbed is an X11 protocol that supports the embedding of a widget from one application into another application.</p>
<p>An XEmbed <i>client widget</i> is a window that is embedded into a <i>container</i>. A container is the graphical location that embeds (or <i>swallows</i>) an external application.</p>
<p>QX11EmbedWidget 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 widget. When the widget 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.</p>
<p>The widget and container can both initiate the embedding. If the widget is the initiator, the X11 window ID of the container that it wants to embed itself into must be passed to <a href="qx11embedwidget.html#embedInto">embedInto</a>().</p>
<p>If the container initiates the embedding, the window ID of the embedded widget must be known. The container calls embed(), passing the window ID.</p>
<p>This example shows an application that embeds a QX11EmbedWidget subclass into the window whose ID is passed as a command-line argument:</p>
<pre> int main(int argc, char *argv[])
{
QApplication app(argc, argv);
if (app.arguments().count() != 2) {
qFatal("Error - expected window id as argument");
return 1;
}
QString windowId(app.arguments()[1]);
EmbedWidget window;
window.embedInto(windowId.toULong());
window.show();
return app.exec();
}</pre>
<p>The problem of obtaining the window IDs is often solved by the container invoking the application that provides the widget as a separate process (as a panel invokes a docked applet), passing its window ID to the new process as a command-line argument. The new process can then call <a href="qx11embedwidget.html#embedInto">embedInto</a>() with the container's window ID, as shown in the example code above. Similarily, the new process can report its window ID to the container through IPC, in which case the container can embed the widget.</p>
<p>When the widget has been embedded, it emits the signal <a href="qx11embedwidget.html#embedded">embedded</a>(). If it is closed by the container, the widget emits <a href="qx11embedwidget.html#containerClosed">containerClosed</a>(). If an error occurs when embedding, <a href="qx11embedwidget.html#error">error</a>() is emitted.</p>
<p>There are XEmbed widgets available for KDE and GTK+. The GTK+ equivalent of QX11EmbedWidget is GtkPlug. The KDE widget is called QXEmbed.</p>
<p>See also <a href="qx11embedcontainer.html">QX11EmbedContainer</a> and <a href="http://www.freedesktop.org/Standards/xembed-spec">XEmbed Specification</a>.</p>
<hr />
<h2>Member Type Documentation</h2>
<h3 class="fn"><a name="Error-enum"></a>enum QX11EmbedWidget::Error</h3>
<p><table border="1" cellpadding="2" cellspacing="1" width="100%">
<tr><th width="25%">Constant</th><th width="15%">Value</th><th width="60%">Description</th></tr>
<tr><td valign="top"><tt>QX11EmbedWidget::Unknown</tt></td><td align="center" valign="top"><tt>0</tt></td><td valign="top">An unrecognized error occurred.</td></tr>
<tr><td valign="top"><tt>QX11EmbedWidget::InvalidWindowID</tt></td><td align="center" valign="top"><tt>2</tt></td><td valign="top">The X11 window ID of the container was invalid. This error is usually triggered by passing an invalid window ID to <a href="qx11embedwidget.html#embedInto">embedInto</a>().</td></tr>
</table></p>
<hr />
<h2>Member Function Documentation</h2>
<h3 class="fn"><a name="QX11EmbedWidget"></a>QX11EmbedWidget::QX11EmbedWidget ( <a href="qwidget.html">QWidget</a> * <i>parent</i> = 0 )</h3>
<p>Constructs a <a href="qx11embedwidget.html">QX11EmbedWidget</a> object with the given <i>parent</i>.</p>
<h3 class="fn"><a name="dtor.QX11EmbedWidget"></a>QX11EmbedWidget::~QX11EmbedWidget ()</h3>
<p>Destructs the <a href="qx11embedwidget.html">QX11EmbedWidget</a> object. If the widget is embedded when deleted, it is hidden and then detached from its container, so that the container is free to embed a new widget.</p>
<h3 class="fn"><a name="containerClosed"></a>void QX11EmbedWidget::containerClosed () <tt> [signal]</tt></h3>
<p>This signal is emitted by the client widget when the container closes the widget. This can happen if the container itself closes, or if the widget is rejected.</p>
<p>The container can reject a widget for any reason, but the most common cause of a rejection is when an attempt is made to embed a widget into a container that already has an embedded widget.</p>
<h3 class="fn"><a name="containerWinId"></a>WId QX11EmbedWidget::containerWinId () const</h3>
<p>If the widget is embedded, returns the window ID of the container; otherwize returns 0.</p>
<h3 class="fn"><a name="embedInto"></a>void QX11EmbedWidget::embedInto ( WId <i>id</i> )</h3>
<p>When this function is called, the widget embeds itself into the container whose window ID is <i>id</i>.</p>
<p>If <i>id</i> is <i>not</i> the window ID of a container this function will behave unpredictably.</p>
<h3 class="fn"><a name="embedded"></a>void QX11EmbedWidget::embedded () <tt> [signal]</tt></h3>
<p>This signal is emitted by the widget that has been embedded by an XEmbed container.</p>
<h3 class="fn"><a name="error"></a><a href="qx11embedwidget.html#Error-enum">Error</a> QX11EmbedWidget::error () const</h3>
<p>Returns the last error that occurred.</p>
<h3 class="fn"><a name="error-2"></a>void QX11EmbedWidget::error ( <a href="qx11embedwidget.html#Error-enum">QX11EmbedWidget::Error</a> <i>error</i> ) <tt> [signal]</tt></h3>
<p>This is an overloaded member function, provided for convenience.</p>
<p>This signal is emitted if an error occurred as a result of embedding into or communicating with a container. The specified <i>error</i> describes the problem that occurred.</p>
<p>See also <a href="qx11embedwidget.html#Error-enum">QX11EmbedWidget::Error</a>.</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright © 2006 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt 4.2.1</div></td>
</tr></table></div></address></body>
</html>
