<?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">
<!-- /builddir/build/BUILD/libqxt/src/core/qxtglobal.cpp -->
<head>
<title><QxtPimpl> - The Qxt private implementation</title>
<link href="stylesheet.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://libqxt.org"><img src="images/qxt-logo.png" width="50" height="40" align="left" 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="modules.html"><font color="#004faf">Modules</font></a> · <a href="classes.html"><font color="#004faf">Classes</font></a> · <a href="namespaces.html"><font color="#004faf">Namespaces</font></a> · <a href="functions.html"><font color="#004faf">Functions</font></a></td>
<td align="right" valign="top" width="230"></td></tr></table><h1 class="title"><QxtPimpl> - The Qxt private implementation<br /><span class="subtitle"></span>
</h1>
<p>The <QxtPimpl> header provides tools for hiding details of a class. <a href="#details">More...</a></p>
<ul>
</ul>
<a name="Functions"></a>
<h3>Functions</h3>
<ul>
<li><div class="fn"></div>PUB & <b><a href="qxtpimpl.html#qxt_p">qxt_p</a></b> ()</li>
<li><div class="fn"></div>const PUB & <b><a href="qxtpimpl.html#qxt_p-2">qxt_p</a></b> () const</li>
</ul>
<a name="Macrosx"></a>
<h3>Macros</h3>
<ul>
<li><div class="fn"></div><b><a href="qxtpimpl.html#QXT_D">QXT_D</a></b> ( <i>PUB</i> )</li>
<li><div class="fn"></div><b><a href="qxtpimpl.html#QXT_DECLARE_PRIVATE">QXT_DECLARE_PRIVATE</a></b> ( <i>PUB</i> )</li>
<li><div class="fn"></div><b><a href="qxtpimpl.html#QXT_DECLARE_PUBLIC">QXT_DECLARE_PUBLIC</a></b> ( <i>PUB</i> )</li>
<li><div class="fn"></div><b><a href="qxtpimpl.html#QXT_INIT_PRIVATE">QXT_INIT_PRIVATE</a></b> ( <i>PUB</i> )</li>
<li><div class="fn"></div><b><a href="qxtpimpl.html#QXT_Px">QXT_P</a></b> ( <i>PUB</i> )</li>
</ul>
<p>Application code generally doesn't have to be concerned about hiding its implementation details, but when writing library code it is important to maintain a constant interface, both source and binary. Maintaining a constant source interface is easy enough, but keeping the binary interface constant means moving implementation details into a private class. The PIMPL, or d-pointer, idiom is a common method of implementing this separation. QxtPimpl offers a convenient way to connect the public and private sides of your class.</p>
<a name="getting-started"></a>
<h3>Getting Started</h3>
<p>Before you declare the public class, you need to make a forward declaration of the private class. The private class must have the same name as the public class, followed by the word Private. For example, a class named MyTest would declare the private class with:</p>
<pre> class MyTestPrivate;</pre>
<a name="the-public-class"></a>
<h3>The Public Class</h3>
<p>Generally, you shouldn't keep any data members in the public class without a good reason. Functions that are part of the public interface should be declared in the public class, and functions that need to be available to subclasses (for calling or overriding) should be in the protected section of the public class. To connect the private class to the public class, include the QXT_DECLARE_PRIVATE macro in the private section of the public class. In the example above, the private class is connected as follows:</p>
<pre> private:
QXT_DECLARE_PRIVATE(MyTest)</pre>
<p>Additionally, you must include the QXT_INIT_PRIVATE macro in the public class's constructor. Continuing with the MyTest example, your constructor might look like this:</p>
<pre> MyTest::MyTest() {
<span class="comment">// initialization</span>
QXT_INIT_PRIVATE(MyTest);
}</pre>
<a name="the-private-class"></a>
<h3>The Private Class</h3>
<p>As mentioned above, data members should usually be kept in the private class. This allows the memory layout of the private class to change without breaking binary compatibility for the public class. Functions that exist only as implementation details, or functions that need access to private data members, should be implemented here.</p>
<p>To define the private class, inherit from the template QxtPrivate class, and include the QXT_DECLARE_PUBLIC macro in its public section. The template parameter should be the name of the public class. For example:</p>
<pre> class MyTestPrivate : public QxtPrivate<MyTest> {
public:
MyTestPrivate();
QXT_DECLARE_PUBLIC(MyTest)
};</pre>
<a name="accessing-private-members"></a>
<h3>Accessing Private Members</h3>
<p>Use the qxt_d() function (actually a function-like object) from functions in the public class to access the private class. Similarly, functions in the private class can invoke functions in the public class by using the qxt_p() function (this one's actually a function).</p>
<p>For example, assume that MyTest has methods named getFoobar and doBaz(), and MyTestPrivate has a member named foobar and a method named doQuux(). The code might resemble this example:</p>
<pre> int MyTest::getFoobar() {
return qxt_d().foobar;
}
void MyTestPrivate::doQuux() {
qxt_p().doBaz(foobar);
}</pre>
<hr />
<h2>Function Documentation</h2>
<h3 class="fn"><a name="qxt_p"></a>PUB & QxtPrivate::qxt_p () <tt> [protected]</tt></h3>
<p>Returns a reference to the public class.</p>
<p>This function is only available in a class using <i>QXT_DECLARE_PUBLIC</i>.</p>
<h3 class="fn"><a name="qxt_p-2"></a>const PUB & QxtPrivate::qxt_p () const <tt> [protected]</tt></h3>
<p>Returns a const reference to the public class.</p>
<p>This function is only available in a class using <i>QXT_DECLARE_PUBLIC</i>. This overload will be automatically used in const functions.</p>
<hr />
<h2>Macro Documentation</h2>
<h3 class="fn"><a name="QXT_D"></a>QXT_D ( <i>PUB</i> )</h3>
<p>Returns a reference in the current scope named "d" to the private class.</p>
<p>This function is only available in a class using <i>QXT_DECLARE_PRIVATE</i>.</p>
<h3 class="fn"><a name="QXT_DECLARE_PRIVATE"></a>QXT_DECLARE_PRIVATE ( <i>PUB</i> )</h3>
<p>Declares that a public class has a related private class.</p>
<p>This shuold be put in the private section of the public class. The parameter is the name of the public class.</p>
<h3 class="fn"><a name="QXT_DECLARE_PUBLIC"></a>QXT_DECLARE_PUBLIC ( <i>PUB</i> )</h3>
<p>Declares that a private class has a related public class.</p>
<p>This may be put anywhere in the declaration of the private class. The parameter is the name of the public class.</p>
<h3 class="fn"><a name="QXT_INIT_PRIVATE"></a>QXT_INIT_PRIVATE ( <i>PUB</i> )</h3>
<p>Initializes resources owned by the private class.</p>
<p>This should be called from the public class's constructor, before qxt_d() is used for the first time. The parameter is the name of the public class.</p>
<h3 class="fn"><a name="QXT_Px"></a>QXT_P ( <i>PUB</i> )</h3>
<p>Creates a reference in the current scope named "q" to the public class.</p>
<p>This macro only works in a class using <i>QXT_DECLARE_PUBLIC</i>.</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td align="left">Copyright © 2007-2010
<a href="mailto:foundation@libqxt.org">Qxt Foundation</a></td>
<td align="right"><div align="right">
<a href="http://libqxt.org">Qxt</a> 0.6.1</div></td>
</tr></table></div></address></body>
</html>
