PageRenderTime 103ms CodeModel.GetById 40ms app.highlight 2ms RepoModel.GetById 58ms app.codeStats 0ms

/thirdparty/qxt/qxtweb-standalone/qxtweb/qxtglobal.cpp

http://github.com/tomahawk-player/tomahawk
C++ | 241 lines | 5 code | 15 blank | 221 comment | 0 complexity | 2255379ab5df533011b471ffe753cffa MD5 | raw file
  1/****************************************************************************
  2 **
  3 ** Copyright (C) Qxt Foundation. Some rights reserved.
  4 **
  5 ** This file is part of the QxtCore module of the Qxt library.
  6 **
  7 ** This library is free software; you can redistribute it and/or modify it
  8 ** under the terms of the Common Public License, version 1.0, as published
  9 ** by IBM, and/or under the terms of the GNU Lesser General Public License,
 10 ** version 2.1, as published by the Free Software Foundation.
 11 **
 12 ** This file is provided "AS IS", without WARRANTIES OR CONDITIONS OF ANY
 13 ** KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY
 14 ** WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR
 15 ** FITNESS FOR A PARTICULAR PURPOSE.
 16 **
 17 ** You should have received a copy of the CPL and the LGPL along with this
 18 ** file. See the LICENSE file and the cpl1.0.txt/lgpl-2.1.txt files
 19 ** included with the source distribution for more information.
 20 ** If you did not receive a copy of the licenses, contact the Qxt Foundation.
 21 **
 22 ** <http://libqxt.org>  <foundation@libqxt.org>
 23 **
 24 ****************************************************************************/
 25
 26#include "qxtglobal.h"
 27
 28/*!
 29    \headerfile <QxtGlobal>
 30    \title Global Qxt Declarations
 31    \inmodule QxtCore
 32
 33    \brief The <QxtGlobal> header provides basic declarations and
 34    is included by all other Qxt headers.
 35 */
 36
 37/*!
 38    \macro QXT_VERSION
 39    \relates <QxtGlobal>
 40
 41    This macro expands a numeric value of the form 0xMMNNPP (MM =
 42    major, NN = minor, PP = patch) that specifies Qxt's version
 43    number. For example, if you compile your application against Qxt
 44    0.4.0, the QXT_VERSION macro will expand to 0x000400.
 45
 46    You can use QXT_VERSION to use the latest Qt features where
 47    available. For example:
 48    \code
 49    #if QXT_VERSION >= 0x000400
 50        qxtTabWidget->setTabMovementMode(QxtTabWidget::InPlaceMovement);
 51    #endif
 52    \endcode
 53
 54    \sa QXT_VERSION_STR, qxtVersion()
 55 */
 56
 57/*!
 58    \macro QXT_VERSION_STR
 59    \relates <QxtGlobal>
 60
 61    This macro expands to a string that specifies Qxt's version number
 62    (for example, "0.4.0"). This is the version against which the
 63    application is compiled.
 64
 65    \sa qxtVersion(), QXT_VERSION
 66 */
 67
 68/*!
 69    \relates <QxtGlobal>
 70
 71    Returns the version number of Qxt at run-time as a string (for
 72    example, "0.4.0"). This may be a different version than the
 73    version the application was compiled against.
 74
 75    \sa QXT_VERSION_STR
 76 */
 77const char* qxtVersion()
 78{
 79    return QXT_VERSION_STR;
 80}
 81
 82/*!
 83\headerfile <QxtPimpl>
 84\title The Qxt private implementation
 85\inmodule QxtCore
 86
 87\brief The <QxtPimpl> header provides tools for hiding
 88details of a class.
 89
 90Application code generally doesn't have to be concerned about hiding its
 91implementation details, but when writing library code it is important to
 92maintain a constant interface, both source and binary. Maintaining a constant
 93source interface is easy enough, but keeping the binary interface constant
 94means moving implementation details into a private class. The PIMPL, or
 95d-pointer, idiom is a common method of implementing this separation. QxtPimpl
 96offers a convenient way to connect the public and private sides of your class.
 97
 98\section1 Getting Started
 99Before you declare the public class, you need to make a forward declaration
100of the private class. The private class must have the same name as the public
101class, followed by the word Private. For example, a class named MyTest would
102declare the private class with:
103\code
104class MyTestPrivate;
105\endcode
106
107\section1 The Public Class
108Generally, you shouldn't keep any data members in the public class without a
109good reason. Functions that are part of the public interface should be declared
110in the public class, and functions that need to be available to subclasses (for
111calling or overriding) should be in the protected section of the public class.
112To connect the private class to the public class, include the
113QXT_DECLARE_PRIVATE macro in the private section of the public class. In the
114example above, the private class is connected as follows:
115\code
116private:
117    QXT_DECLARE_PRIVATE(MyTest)
118\endcode
119
120Additionally, you must include the QXT_INIT_PRIVATE macro in the public class's
121constructor. Continuing with the MyTest example, your constructor might look
122like this:
123\code
124MyTest::MyTest() {
125    // initialization
126    QXT_INIT_PRIVATE(MyTest);
127}
128\endcode
129
130\section1 The Private Class
131As mentioned above, data members should usually be kept in the private class.
132This allows the memory layout of the private class to change without breaking
133binary compatibility for the public class. Functions that exist only as
134implementation details, or functions that need access to private data members,
135should be implemented here.
136
137To define the private class, inherit from the template QxtPrivate class, and
138include the QXT_DECLARE_PUBLIC macro in its public section. The template
139parameter should be the name of the public class. For example:
140\code
141class MyTestPrivate : public QxtPrivate<MyTest> {
142public:
143    MyTestPrivate();
144    QXT_DECLARE_PUBLIC(MyTest)
145};
146\endcode
147
148\section1 Accessing Private Members
149Use the qxt_d() function (actually a function-like object) from functions in
150the public class to access the private class. Similarly, functions in the
151private class can invoke functions in the public class by using the qxt_p()
152function (this one's actually a function).
153
154For example, assume that MyTest has methods named getFoobar and doBaz(),
155and MyTestPrivate has a member named foobar and a method named doQuux().
156The code might resemble this example:
157\code
158int MyTest::getFoobar() {
159    return qxt_d().foobar;
160}
161
162void MyTestPrivate::doQuux() {
163    qxt_p().doBaz(foobar);
164}
165\endcode
166*/
167
168/*! 
169 * \macro QXT_DECLARE_PRIVATE(PUB)
170 * \relates <QxtPimpl>
171 * Declares that a public class has a related private class.
172 *
173 * This shuold be put in the private section of the public class. The parameter is the name of the public class.
174 */
175
176/*!
177 * \macro QXT_DECLARE_PUBLIC(PUB)
178 * \relates <QxtPimpl>
179 * Declares that a private class has a related public class.
180 *
181 * This may be put anywhere in the declaration of the private class. The parameter is the name of the public class.
182 */
183
184/*!
185 * \macro QXT_INIT_PRIVATE(PUB)
186 * \relates <QxtPimpl>
187 * Initializes resources owned by the private class.
188 *
189 * This should be called from the public class's constructor,
190 * before qxt_d() is used for the first time. The parameter is the name of the public class.
191 */
192
193/*!
194 * \macro QXT_D(PUB)
195 * \relates <QxtPimpl>
196 * Returns a reference in the current scope named "d" to the private class.
197 *
198 * This function is only available in a class using \a QXT_DECLARE_PRIVATE.
199 */
200
201/*!
202 * \macro QXT_P(PUB)
203 * \relates <QxtPimpl>
204 * Creates a reference in the current scope named "q" to the public class.
205 *
206 * This macro only works in a class using \a QXT_DECLARE_PUBLIC.
207 */
208
209/*!
210 * \fn QxtPrivate<PUB>& PUB::qxt_d()
211 * \relates <QxtPimpl>
212 * Returns a reference to the private class.
213 *
214 * This function is only available in a class using \a QXT_DECLARE_PRIVATE.
215 */
216
217/*!
218 * \fn const QxtPrivate<PUB>& PUB::qxt_d() const
219 * \relates <QxtPimpl>
220 * Returns a const reference to the private class.
221 *
222 * This function is only available in a class using \a QXT_DECLARE_PRIVATE.
223 * This overload will be automatically used in const functions.
224 */
225
226/*!
227 * \fn PUB& QxtPrivate::qxt_p()
228 * \relates <QxtPimpl>
229 * Returns a reference to the public class.
230 *
231 * This function is only available in a class using \a QXT_DECLARE_PUBLIC.
232 */
233
234/*!
235 * \fn const PUB& QxtPrivate::qxt_p() const
236 * \relates <QxtPimpl>
237 * Returns a const reference to the public class.
238 *
239 * This function is only available in a class using \a QXT_DECLARE_PUBLIC.
240 * This overload will be automatically used in const functions.
241 */