D-BUS Adaptor Example

The following example code shows how a D-BUS interface can be implemented using an adaptor.

A sample usage of QDBusAbstractAdaptor is as follows:

 class MainApplicationAdaptor: public QDBusAbstractAdaptor
 {
     Q_OBJECT
     Q_CLASSINFO("D-Bus Interface", "com.example.DBus.MainApplication")
     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:
     MyInterfaceAdaptor(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();
 };

The code above would create an interface that could be represented more or less in the following canonical representation:

 interface com.example.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()
 }

 interface org.kde.DBus.MainApplication
 {
     ....
 }

This adaptor could be used in the application's main function as follows

 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:
     QDBus::sessionBus().registerObject("/MainApplication", app);

     // add main window, etc.
     [...]

     app.exec();
 }

Break-down analysis:

• The header
• The properties
• The constructor
• Slots/methods
• Signals

 class MainApplicationAdaptor: public QDBusAbstractAdaptor
 {
     Q_OBJECT
     Q_CLASSINFO("D-Bus Interface", "com.example.DBus.MainApplication")
     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)

     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();
     }

     MyInterfaceAdaptor(QApplication *application)
         : QDBusAbstractAdaptor(application), app(application)
     {
         connect(application, SIGNAL(aboutToQuit()), SIGNAL(aboutToQuit());
         connect(application, SIGNAL(focusChanged(QWidget*, QWidget*)),
                 SLOT(focusChangedSlot(QWidget*, QWidget*)));
     }

 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();
     }

 signals:
     void aboutToQuit();
     void mainWindowHasFocus();

 private slots:
     void focusChangedSlot(QWidget *, QWidget *now)
     {
         if (now == app->mainWindow())
             emit mainWindowHasFocus();
     }