1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Remove old and broken QDBus adaptor example

Browse Source 
Task-number: QTBUG-69091
Change-Id: I991a5bc01c316a5e23204550618d730af755292c
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This commit is contained in:
Paul Wicking 2018-06-27 12:31:02 +02:00
parent d5fd308d1f
commit 023a818738
2 changed files with 2 additions and 338 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

212
src/dbus/doc/snippets/code/doc_src_qdbusadaptors.cpp
View File

@ -48,218 +48,6 @@
** **
****************************************************************************/ ****************************************************************************/
//! [0]
class MainApplicationAdaptor: public QDBusAbstractAdaptor
{
Q_OBJECT
Q_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication")
Q_PROPERTY(QString caption READ caption WRITE setCaption)
Q_PROPERTY(QString organizationName READ organizationName)
Q_PROPERTY(QString organizationDomain READ organizationDomain)
private:
QApplication *app;
public:
MainApplicationAdaptor(QApplication *application)
: QDBusAbstractAdaptor(application), app(application)
{
connect(application, SIGNAL(aboutToQuit()), SIGNAL(aboutToQuit()));
connect(application, SIGNAL(focusChanged(QWidget*,QWidget*)),
SLOT(focusChangedSlot(QWidget*,QWidget*)));
}
QString caption()
{
if (app->hasMainWindow())
return app->mainWindow()->caption();
return QString(""); // must not return a null QString
}
void setCaption(const QString &newCaption)
{
if (app->hasMainWindow())
app->mainWindow()->setCaption(newCaption);
}
QString organizationName()
{
return app->organizationName();
}
QString organizationDomain()
{
return app->organizationDomain();
}
public slots:
Q_NOREPLY void quit()
{ app->quit(); }
void reparseConfiguration()
{ app->reparseConfiguration(); }
QString mainWindowObject()
{
if (app->hasMainWindow())
return QString("/%1/mainwindow").arg(app->applicationName());
return QString();
}
void setSessionManagement(bool enable)
{
if (enable)
app->enableSessionManagement();
else
app->disableSessionManagement();
}
private slots:
void focusChangedSlot(QWidget *, QWidget *now)
{
if (now == app->mainWindow())
emit mainWindowHasFocus();
}
signals:
void aboutToQuit();
void mainWindowHasFocus();
};
//! [0]
//! [1]
interface org.kde.DBus.MainApplication
{
property readwrite STRING caption
property read STRING organizationName
property read STRING organizationDomain
method quit() annotation("org.freedesktop.DBus.Method.NoReply", "true")
method reparseConfiguration()
method mainWindowObject(out STRING)
method disableSessionManagement(in BOOLEAN enable)
signal aboutToQuit()
signal mainWindowHasFocus()
}
//! [1]
//! [2]
int main(int argc, char **argv)
{
// create the QApplication object
QApplication app(argc, argv);
// create the MainApplication adaptor:
new MainApplicationAdaptor(app);
// connect to D-Bus and register as an object:
QDBusConnection::sessionBus().registerObject("/MainApplication", &app);
// add main window, etc.
[...]
app.exec();
}
//! [2]
//! [3]
class MainApplicationAdaptor: public QDBusAbstractAdaptor
{
Q_OBJECT
Q_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication")
//! [3]
//! [4]
Q_PROPERTY(QString caption READ caption WRITE setCaption)
Q_PROPERTY(QString organizationName READ organizationName)
Q_PROPERTY(QString organizationDomain READ organizationDomain)
//! [4]
//! [5]
QString caption()
{
if (app->hasMainWindow())
return app->mainWindow()->caption();
return QString();
}
void setCaption(const QString &newCaption)
{
if (app->hasMainWindow())
app->mainWindow()->setCaption(newCaption);
}
QString organizationName()
{
return app->organizationName();
}
QString organizationDomain()
{
return app->organizationDomain();
}
//! [5]
//! [6]
MyInterfaceAdaptor(QApplication *application)
: QDBusAbstractAdaptor(application), app(application)
{
connect(application, SIGNAL(aboutToQuit()), SIGNAL(aboutToQuit());
connect(application, SIGNAL(focusChanged(QWidget*,QWidget*)),
SLOT(focusChangedSlot(QWidget*,QWidget*)));
}
//! [6]
//! [7]
public slots:
Q_NOREPLY void quit()
{ app->quit(); }
void reparseConfiguration()
{ app->reparseConfiguration(); }
QString mainWindowObject()
{
if (app->hasMainWindow())
return QString("/%1/mainwindow").arg(app->applicationName());
return QString();
}
void setSessionManagement(bool enable)
{
if (enable)
app->enableSessionManagement();
else
app->disableSessionManagement();
}
//! [7]
//! [8]
signals:
void aboutToQuit();
void mainWindowHasFocus();
//! [8]
//! [9]
private slots:
void focusChangedSlot(QWidget *, QWidget *now)
{
if (now == app->mainWindow())
emit mainWindowHasFocus();
}
//! [9]
//! [10] //! [10]
struct RequestData struct RequestData
{ {

128
src/dbus/doc/src/dbus-adaptors.qdoc
View File

@ -68,132 +68,11 @@
\li \l{Declaring Slots in D-Bus Adaptors} \li \l{Declaring Slots in D-Bus Adaptors}
\li \l{Declaring Signals in D-Bus Adaptors} \li \l{Declaring Signals in D-Bus Adaptors}
\li \l{The Qt D-Bus Type System} \li \l{The Qt D-Bus Type System}
\li \l{D-Bus Adaptor Example}
\endlist \endlist
\sa QDBusAbstractAdaptor \sa QDBusAbstractAdaptor
*/ */
/*!
\page qdbusadaptorexample.html
\title D-Bus Adaptor Example
\previouspage The Qt D-Bus Type System
\contentspage Using Qt D-Bus Adaptors
The following example code shows how a D-Bus interface can be implemented
using an adaptor.
A sample usage of QDBusAbstractAdaptor is as follows:
\snippet code/doc_src_qdbusadaptors.cpp 0
The code above would create an interface that could be represented more or less in the following
canonical representation:
\snippet code/doc_src_qdbusadaptors.cpp 1
This adaptor could be used in the application's main function as follows
\snippet code/doc_src_qdbusadaptors.cpp 2
Break-down analysis:
\tableofcontents
\section1 The Header
The header of the example is:
\snippet code/doc_src_qdbusadaptors.cpp 3
The code does the following:
\list
\li it declares the adaptor MainApplicationAdaptor, which descends from QDBusAbstractAdaptor
\li it declares the Qt meta-object data using the Q_OBJECT macro
\li it declares the name of the D-Bus interface it implements.
\endlist
\section1 The Properties
The properties are declared as follows:
\snippet code/doc_src_qdbusadaptors.cpp 4
And are implemented as follows:
\snippet code/doc_src_qdbusadaptors.cpp 5
The code declares three properties: one of them is a read-write property called "caption" of
string type. The other two are read-only, also of the string type.
The properties organizationName and organizationDomain are simple relays of the app object's
organizationName and organizationDomain properties. However, the caption property requires
verifying if the application has a main window associated with it: if there isn't any, the
caption property is empty. Note how it is possible to access data defined in other objects
through the getter/setter functions.
\section1 The Constructor
The constructor:
\snippet code/doc_src_qdbusadaptors.cpp 6
The constructor does the following:
\list
\li it initialises its base class (QDBusAbstractAdaptor) with the parent object it is related to.
\li it stores the app pointer in a member variable. Note that it would be possible to access the
same object using the QDBusAbstractAdaptor::object() function, but it would be necessary to
use \a static_cast<> to properly access the methods in QApplication that are not part of
QObject.
\li it connects the application's signal \a aboutToQuit to its own signal \a aboutToQuit.
\li it connects the application's signal \a focusChanged to a private slot to do some further
processing before emitting a D-Bus signal.
\endlist
Note that there is no destructor in the example. An eventual destructor could be used to emit
one last signal before the object is destroyed, for instance.
\section1 Slots/methods
The public slots in the example (which will be exported as D-Bus methods) are the following:
\snippet code/doc_src_qdbusadaptors.cpp 7
This snippet of code defines 4 methods with different properties each:
\list 1
\li \c quit: this method takes no parameters and is defined to be asynchronous. That is, callers
are expected to use "fire-and-forget" mechanism when calling this method, since it provides no
useful reply. This is represented in D-Bus by the use of the
org.freedesktop.DBus.Method.NoReply annotation. See \l Q_NOREPLY for more information on
asynchronous methods
\li \c reparseConfiguration: this simple method, with no input or output arguments simply relays
the call to the application's reparseConfiguration member function.
\li \c mainWindowObject: this method takes no input parameter, but returns one string output
argument, containing the path to the main window object (if the application has a main
window), or an empty string if it has no main window. Note that this method could have also
been written: void mainWindowObject(QString &path).
\li \c setSessionManagement: this method takes one input argument (a boolean) and, depending on
its value, it calls one function or another in the application.
\endlist
See also: \l Q_NOREPLY.
\section1 Signals
The signals in this example are defined as follows:
\snippet code/doc_src_qdbusadaptors.cpp 8
However, signal definition isn't enough: signals have to be emitted. One simple way of emitting
signals is to connect another signal to them, so that Qt's signal handling system chains them
automatically. This is what is done for the \a aboutToQuit signal.
When this is the case, one can use the QDBusAbstractAdaptor::setAutoRelaySignals to
automatically connect every signal from the real object to the adaptor.
When simple signal-to-signal connection isn't enough, one can use a private slot do do some
work. This is what was done for the mainWindowHasFocus signal:
\snippet code/doc_src_qdbusadaptors.cpp 9
This private slot (which will not be exported as a method via D-Bus) was connected to the
\c focusChanged signal in the adaptor's constructor. It is therefore able to shape the
application's signal into what the interface expects it to be.
*/
/*! /*!
\page qdbusdeclaringslots.html \page qdbusdeclaringslots.html
\title Declaring Slots in D-Bus Adaptors \title Declaring Slots in D-Bus Adaptors
@ -230,8 +109,7 @@
synchronize with the caller should provide its own method of synchronization. synchronize with the caller should provide its own method of synchronization.
Asynchronous slots are marked by the keyword \l Q_NOREPLY in the method Asynchronous slots are marked by the keyword \l Q_NOREPLY in the method
signature, before the \c void return type and the slot name. (See the signature, before the \c void return type and the slot name.
\c quit() slot in the \l{D-Bus Adaptor Example}).
\section1 Input-Only Slots \section1 Input-Only Slots
@ -341,8 +219,7 @@
However, signals must still be emitted. The easiest way to emit an adaptor However, signals must still be emitted. The easiest way to emit an adaptor
signal is to connect another signal to it, so that Qt's signals and slots signal is to connect another signal to it, so that Qt's signals and slots
mechanism automatically emits the adaptor signal, too. This can be done in mechanism automatically emits the adaptor signal, too. This can be done in
the adaptor's constructor, as has been done in the the adaptor's constructor.
\l{D-Bus Adaptor Example}{D-Bus Adaptor example}.
The QDBusAbstractAdaptor::setAutoRelaySignals() convenience function can also The QDBusAbstractAdaptor::setAutoRelaySignals() convenience function can also
be used to make and break connections between signals in the real object and be used to make and break connections between signals in the real object and
@ -360,7 +237,6 @@
\previouspage Declaring Signals in D-Bus Adaptors \previouspage Declaring Signals in D-Bus Adaptors
\contentspage Using Qt D-Bus Adaptors \contentspage Using Qt D-Bus Adaptors
\nextpage D-Bus Adaptor Example
D-Bus has an extensible type system based on a few primitives and D-Bus has an extensible type system based on a few primitives and
composition of the primitives in arrays and structures. Qt D-Bus composition of the primitives in arrays and structures. Qt D-Bus