summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRainer Keller <rainer.keller@nokia.com>2011-06-14 09:49:24 +0200
committerRainer Keller <rainer.keller@nokia.com>2011-06-21 11:49:59 +0200
commitfe4604f01ce228141b35741a0b0f7427ca6452d6 (patch)
tree1df799f07a08ff69a7315ed8e78ff928ff339c74
parent092b3624a2bf162c02b9c462320561b89be5ad1f (diff)
Add documentation for plugin support
Documentation was Reviewed-by: Leena Miettinen
-rw-r--r--doc/example/application/exampleapp.cpp89
-rw-r--r--doc/example/application/exampleapp.h66
-rw-r--r--doc/example/application/exampleapp.pro3
-rw-r--r--doc/example/plugin/example-plugin.cpp45
-rw-r--r--doc/example/plugin/example-plugin.h52
-rw-r--r--doc/example/plugin/example-plugin.pro10
-rw-r--r--doc/example/plugin/examplepage.cpp124
-rw-r--r--doc/example/plugin/examplepage.h76
-rw-r--r--doc/simulator.qdoc96
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
+
+*/