diff options
author | Rainer Keller <rainer.keller@nokia.com> | 2011-06-14 09:49:24 +0200 |
---|---|---|
committer | Rainer Keller <rainer.keller@nokia.com> | 2011-06-21 11:49:59 +0200 |
commit | fe4604f01ce228141b35741a0b0f7427ca6452d6 (patch) | |
tree | 1df799f07a08ff69a7315ed8e78ff928ff339c74 | |
parent | 092b3624a2bf162c02b9c462320561b89be5ad1f (diff) |
Add documentation for plugin support
Documentation was
Reviewed-by: Leena Miettinen
-rw-r--r-- | doc/example/application/exampleapp.cpp | 89 | ||||
-rw-r--r-- | doc/example/application/exampleapp.h | 66 | ||||
-rw-r--r-- | doc/example/application/exampleapp.pro | 3 | ||||
-rw-r--r-- | doc/example/plugin/example-plugin.cpp | 45 | ||||
-rw-r--r-- | doc/example/plugin/example-plugin.h | 52 | ||||
-rw-r--r-- | doc/example/plugin/example-plugin.pro | 10 | ||||
-rw-r--r-- | doc/example/plugin/examplepage.cpp | 124 | ||||
-rw-r--r-- | doc/example/plugin/examplepage.h | 76 | ||||
-rw-r--r-- | doc/simulator.qdoc | 96 |
9 files changed, 559 insertions, 2 deletions
diff --git a/doc/example/application/exampleapp.cpp b/doc/example/application/exampleapp.cpp new file mode 100644 index 0000000..c6e1269 --- /dev/null +++ b/doc/example/application/exampleapp.cpp @@ -0,0 +1,89 @@ +/************************************************************************** +** +** This file is part of Qt Simulator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** No Commercial Usage +** +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +**************************************************************************/ + + +#include "exampleapp.h" + +#include <QApplication> +#include <QDebug> +#include <QtGui/QLineEdit> +#include <QtGui/QHBoxLayout> +#include <QtSimulator/connection.h> +#include <QtSimulator/connectionworker.h> + +using namespace Simulator; + +//! [2] +ExampleApp::ExampleApp(QWidget *parent) + : QWidget(parent) + , mConnection(new Connection(Connection::Client, "example", 1)) +{ + mWorker = mConnection->connectToServer(); + mWorker->addReceiver(this); + + QHBoxLayout *layout = new QHBoxLayout(this); + mLineEdit = new QLineEdit(this); + layout->addWidget(mLineEdit); + setLayout(layout); + connect(mLineEdit, SIGNAL(textEdited ( const QString &)), this, SLOT(textEdited(const QString &))); +} +//! [2] + +ExampleApp::~ExampleApp() +{ + delete mWorker; +} + +//! [0] +void ExampleApp::showText(const QString &text) +{ + mLineEdit->setText(text); + qWarning() << "showText:" << text; +} +//! [0] + +//! [1] +void ExampleApp::textEdited(const QString &text) +{ + mWorker->call("showText", text); +} +//! [1] + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + ExampleApp ex; + ex.showFullScreen(); + return app.exec(); +} + diff --git a/doc/example/application/exampleapp.h b/doc/example/application/exampleapp.h new file mode 100644 index 0000000..02b95c4 --- /dev/null +++ b/doc/example/application/exampleapp.h @@ -0,0 +1,66 @@ +/************************************************************************** +** +** This file is part of Qt Simulator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** No Commercial Usage +** +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +**************************************************************************/ + +#ifndef EXAMPLEAPP_H +#define EXAMPLEAPP_H + +#include <QtGui/QWidget> +class QLineEdit; + +namespace Simulator { + class Connection; + class ConnectionWorker; +} + +//! [0] +class ExampleApp : public QWidget +{ + Q_OBJECT + +public: + explicit ExampleApp(QWidget *parent = 0); + virtual ~ExampleApp(); + +public slots: + void showText(const QString &); + void textEdited(const QString &); + +private: + QLineEdit *mLineEdit; + Simulator::Connection *mConnection; + Simulator::ConnectionWorker *mWorker; +}; +//! [0] + + +#endif // EXAMPLEAPP_H diff --git a/doc/example/application/exampleapp.pro b/doc/example/application/exampleapp.pro new file mode 100644 index 0000000..60bc696 --- /dev/null +++ b/doc/example/application/exampleapp.pro @@ -0,0 +1,3 @@ +SOURCES+=exampleapp.cpp +HEADERS+=exampleapp.h +QT+=simulator diff --git a/doc/example/plugin/example-plugin.cpp b/doc/example/plugin/example-plugin.cpp new file mode 100644 index 0000000..574f5e9 --- /dev/null +++ b/doc/example/plugin/example-plugin.cpp @@ -0,0 +1,45 @@ +/************************************************************************** +** +** This file is part of Qt Simulator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** No Commercial Usage +** +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +**************************************************************************/ + +#include "example-plugin.h" +#include "examplepage.h" + +//! [0] +QList<ToolBoxPage *> ExamplePlugin::pages(QWidget *parent) +{ + return QList<ToolBoxPage *>() << new ExamplePage(parent); +} + +Q_EXPORT_PLUGIN2(example_plugin, ExamplePlugin) +//! [0] + diff --git a/doc/example/plugin/example-plugin.h b/doc/example/plugin/example-plugin.h new file mode 100644 index 0000000..0f05071 --- /dev/null +++ b/doc/example/plugin/example-plugin.h @@ -0,0 +1,52 @@ +/************************************************************************** +** +** This file is part of Qt Simulator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** No Commercial Usage +** +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +**************************************************************************/ + +#ifndef EXAMPLE_PLUGIN_H +#define EXAMPLE_PLUGIN_H + +#include <remotecontrolwidget/plugininterface.h> +#include <QtCore/QList> + +//! [0] +class ExamplePlugin : public QObject, public PluginInterface +{ + Q_OBJECT + Q_INTERFACES(PluginInterface) + +public: + QList<ToolBoxPage *> pages(QWidget *); +}; +//! [0] + +#endif // EXAMPLE_PLUGIN_H + diff --git a/doc/example/plugin/example-plugin.pro b/doc/example/plugin/example-plugin.pro new file mode 100644 index 0000000..e31fcba --- /dev/null +++ b/doc/example/plugin/example-plugin.pro @@ -0,0 +1,10 @@ +SOURCES += example-plugin.cpp examplepage.cpp +HEADERS += example-plugin.h examplepage.h +QT += network + +TEMPLATE = lib +CONFIG += plugin +INCLUDEPATH += $$QT_NOKIA_SDK_PATH/simulator-dependencies/include/ +TARGET = $$qtLibraryTarget(example_plugin) +DESTDIR = $${QT_NOKIA_SDK_PATH}/Simulator/Application/plugins/simulator +LIBS += -L $$QT_NOKIA_SDK_PATH/simulator-dependencies/lib -lsimulatorplugin diff --git a/doc/example/plugin/examplepage.cpp b/doc/example/plugin/examplepage.cpp new file mode 100644 index 0000000..8f7fd59 --- /dev/null +++ b/doc/example/plugin/examplepage.cpp @@ -0,0 +1,124 @@ +/************************************************************************** +** +** This file is part of Qt Simulator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** No Commercial Usage +** +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +**************************************************************************/ + + +#include "examplepage.h" +#include <remotecontrolwidget/optionsitem.h> +#include <QtGui/QLineEdit> +#include <QtGui/QIcon> +#include <QtCore/QSettings> +#include "simulatorplugin/connection.h" +#include "simulatorplugin/connectionworker.h" + +using namespace Simulator; + +//! [0] +ExamplePage::ExamplePage(QWidget *parent) + : ToolBoxPage(parent) + , mConnection(0) +{ + QList<OptionsItem *> optionsList; + target = new QLineEdit(this); + optionsList << new OptionsItem(tr("Example control"), target); + setOptions(optionsList); + + setTitle(tr("Example Page")); + + mConnection = new Connection(Connection::Server, "example", 1, this); + + connect(target, SIGNAL(textEdited ( const QString &)), this, SLOT(textEdited(const QString &))); + connect(mConnection, SIGNAL(newConnection(Simulator::ConnectionWorker *)), this, SLOT(newConnection(Simulator::ConnectionWorker *))); +} +//! [0] + +ExamplePage::~ExamplePage() +{ +} + +//! [1] +void ExamplePage::textEdited(const QString &text) +{ + foreach (ConnectionWorker *worker, mWorkers) + worker->call("showText", text); +} +//! [1] + +void ExamplePage::showText(const QString &text) +{ + target->setText(text); +} + +// These functions can be used to read/write persistent settings. If you overwrite these as shown here +// you have to make sure the base class function if called first. +// If you do not need to save anything just remove these functions. +//! [2] +void ExamplePage::writeSettings(QSettings &settings) const +{ + ToolBoxPage::writeSettings(settings); + + settings.beginGroup(title()); + settings.setValue("myValue", 5); + settings.endGroup(); +} + +void ExamplePage::readSettings(QSettings &settings) +{ + ToolBoxPage::readSettings(settings); + + settings.beginGroup(title()); + if (settings.contains("myValue")) + int myValue = settings.value("myValue").toInt(); + settings.endGroup(); +} +//! [2] + +//! [3] +void ExamplePage::newConnection(ConnectionWorker *worker) +{ + connect(worker, SIGNAL(disconnected()), this, SLOT(disconnected())); + mWorkers.append(worker); + worker->addReceiver(this); +} + +void ExamplePage::disconnected() +{ + ConnectionWorker *worker = qobject_cast<ConnectionWorker *>(sender()); + worker->deleteLater(); + mWorkers.removeAll(worker); +} +//! [3] + +QIcon ExamplePage::icon() const +{ + return QIcon(); +} diff --git a/doc/example/plugin/examplepage.h b/doc/example/plugin/examplepage.h new file mode 100644 index 0000000..47a5739 --- /dev/null +++ b/doc/example/plugin/examplepage.h @@ -0,0 +1,76 @@ +/************************************************************************** +** +** This file is part of Qt Simulator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** No Commercial Usage +** +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +**************************************************************************/ + +#ifndef EXAMPLEPAGE_H +#define EXAMPLEPAGE_H + +#include <remotecontrolwidget/toolbox.h> + +class QLineEdit; + +namespace Simulator { + class Connection; + class ConnectionWorker; +} + +//! [0] +class ExamplePage : public ToolBoxPage +{ + Q_OBJECT + +public: + explicit ExamplePage(QWidget *parent = 0); + virtual ~ExamplePage(); + + void writeSettings(QSettings &) const; + void readSettings(QSettings &); + + QIcon icon() const; + +public slots: + void textEdited(const QString &); + void showText(const QString &); + +private slots: + void newConnection(Simulator::ConnectionWorker *); + void disconnected(); + +private: + Simulator::Connection *mConnection; + QLineEdit *target; + QList<Simulator::ConnectionWorker *> mWorkers; +}; +//! [0] + +#endif // EXAMPLEPAGE_H + diff --git a/doc/simulator.qdoc b/doc/simulator.qdoc index 4256f03..e2108fe 100644 --- a/doc/simulator.qdoc +++ b/doc/simulator.qdoc @@ -77,6 +77,7 @@ \o \l{Declaring Qt Mobility APIs} \o \l{Using Bearer Management} \o \l{Testing Applications Using the Qt Mobility Service Framework} + \o \l{Adding Views} \o \l{Known Issues} \endlist */ @@ -935,7 +936,7 @@ /*! \contentspage index.html - \previouspage simulator-serviceframework.html + \previouspage simulator-plugins.html \page simulator-known-issues.html \title Known Issues @@ -1108,7 +1109,7 @@ \contentspage index.html \previouspage simulator-bearermanagement.html \page simulator-serviceframework.html - \nextpage simulator-known-issues.html + \nextpage simulator-plugins.html \title Testing Applications Using the Qt Mobility Service Framework @@ -1575,3 +1576,94 @@ Target}. */ + +/*! + \contentspage index.html + \previouspage simulator-serviceframework.html + \page simulator-plugins.html + \nextpage simulator-known-issues.html + + \title Adding Views + + You can write plugins to add views that contain your own controls to Qt + Simulator. The plugins display the controls and act as servers that accept + connections from the simulated applications. You must also write a target + library or application that receives data from the controls. + + \section1 Writing Qt Simulator Plugins + + Write a simple plugin as described in + \l{http://doc.qt.nokia.com/4.7/plugins-howto.html}{How to Create Qt Plugins}. + + The plugin class has a single function that returns all views to show in + Qt Simulator, as illustrated by the following code snippet: + + \snippet example/plugin/example-plugin.h 0 + + The following code snippet illustrates how to return a view created from the + \c ExamplePage class: + + \snippet example/plugin/example-plugin.cpp 0 + + \section1 Creating Views + + The implementation of a Qt Simulator view must contain all the visible + widgets. The following code snippet implements a view that contains an + editable \c QLineEdit widget: + + \snippet example/plugin/examplepage.h 0 + + The constructor sets up a \c QWidget that contains the contents to display. + The connection server is set up using the \c Connection class: + + \snippet example/plugin/examplepage.cpp 0 + + The following code snippet is an example of a slot that is called when the + text in \c QLineEdit changes. The slot notifies the connected clients about + the change. If multiple clients are connected, all of them have to be + notified: + + \snippet example/plugin/examplepage.cpp 1 + + Reimplement the following functions to store persistent values in Qt + Simulator configuration. Make sure you call the parent functions as early as + possible, because \c ToolBoxPage needs to save its window state: + + \snippet example/plugin/examplepage.cpp 2 + + The server uses the following two slots to manage the connected clients by + connecting and disconnecting them as necessary: + + \snippet example/plugin/examplepage.cpp 3 + + Qt Simulator displays icons that you can select to open views. To display an + icon for your view, implement the function \c {QIcon icon() const} and make + sure that it returns a valid icon with the size of 32x32 pixels. If you do + not implement the function, the name of the page is used instead. + You can set the page name using \c {void setName(const QString &)}. + The name is mainly used in the \gui Menu. + + \section1 Writing Client Applications + + The example application shows a single \c QLineEdit. + + The following class implements a standard \c QWidget: + + \snippet example/application/exampleapp.h 0 + + The only thing that is special about the constructor is that it creates a + connection to the server. The resulting \c ConnectionWorker has to be saved: + + \snippet example/application/exampleapp.cpp 2 + + The \c showText function is called remotely when the text in the control + widget changes, and the text is updated locally: + + \snippet example/application/exampleapp.cpp 0 + + When the text is edited locally, a remote call is made to update the control + widget page: + + \snippet example/application/exampleapp.cpp 1 + +*/ |