Revision as of 16:39, 22 December 2009 by seppo_fn (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Porting WRT widgets to Qt applications

From Nokia Developer Wiki
Jump to: navigation, search

Porting WRT widgets to Qt applications



This article provides Web developers with information about porting Web Runtime (WRT) widgets to Qt applications. The IDE used here is Qt Creator but basic principles should apply to other IDEs, such as NetBeans or Eclipse, as well.

Laying out the Foundations

(Links to articles describing the installation of the IDEs, SDKs and such.)

Creating a Qt Application with a QWebView Component

  1. Start Qt Creator IDE.
  2. Select File > New File or Project... > Projects > Qt4 Gui Application.
  3. Click OK.
  4. Give the project a name and set its location.
  5. Click Next.
  6. In the following dialog, you can select the modules that you want to include in your project. Check the QtWebKit module and click Next.
  7. In the following dialog, name your main window class as WRTWidgetWindow (the Class name field) and uncheck the Generate form box (in this project, the UI components are added by hand).
  8. Click Next.
  9. Review that the proposed changes are correct and click Finish. The project is opened and there are two source files, main.cpp and wrtwidgetwindow.cpp, which can be found in the Sources folder in the Projects view.

Now you are ready to write some code! Start by opening the main.cpp file and modify it to look like this:

#include <QtGui/QApplication>
#include "wrtwidgetwindow.h"
int main(int argc, char *argv[])
QApplication app(argc, argv);
WRTWidgetWindow window;
return app.exec();

Then, open the header file of the main window, wrtwidgetwindow.h, (in the Headers folder in the Projects view) and modify it to look like this:

#include <QtCore/QPointer>
#include <QtGui/QMainWindow>
class QWebView;
class WRTWidgetWindow : public QMainWindow
WRTWidgetWindow(QWidget *parent = 0);
void setupUI();
QWebView* createWebView();
QPointer<QWebView> webView;

The class, which was declared above, represents the main window of the application. It contains one Qt widget, QWebView (webView), which is used for showing the Web content (HTML, CSS, JavaScript) on Qt. Next, open the implementation for the class (wrtwidgetwindow.cpp) and modify it so that it looks like this:

#include "wrtwidgetwindow.h"
#include <QtGui/QFrame>
#include <QtGui/QVBoxLayout>
#include <QtWebKit/QWebView>
WRTWidgetWindow::WRTWidgetWindow(QWidget *parent)
: QMainWindow(parent)
void WRTWidgetWindow::setupUI()
QFrame* cw = new QFrame(this);
QVBoxLayout* layout = new QVBoxLayout(cw);
webView = createWebView();
QWebView* WRTWidgetWindow::createWebView()
QWebView* view = new QWebView(this);
return view;

After this, the application can be compiled and run. You can try this, even though the application doesn't do much yet; There's only an empty QWebView component on the screen.

Showing the Web Content from Qt

Let's add your existing WRT widget to the project (if you don't have one, grab one from here, for example: Web Runtime Stub). Copy the HTML, CSS, JavaScript, and resource (graphics, etc.) files into your Qt project. It is most easily done by using the file manager and copying the respective folders into your project's root directory as a whole (you have the Web content in separate folders, don't you?). The directory structure of your widget could look like this, for example:

html/   (HTML files)
style/ (CSS files)
script/ (JavaScript files)
gfx/ (graphics)

In order to use the Web content from the Qt application, you must create a resource file in your project and add the content into it. To create the resource file, select File > New File or Project... > Qt > Qt Resource file and click OK. Give the resource file a name and set its location. Click Next and make sure that the resource file is added to your project (the Add to Project checkbox and the Project drop-down list). Click Finish. The resource file is created and will be automatically added as a resource into the .pro file of the project. Open the resource file in Qt Creator's plain text editor by right-clicking on it in the Projects view and selecting Open With > Plain Text Editor. Add the Web content to the resource file like this:

<?xml version="1.0" encoding="utf-8"?>
<RCC version="1.0">
<!-- HTML files -->
<!-- CSS files -->
<!-- JavaScript files -->
<!-- Graphics -->

Now the resources are compiled into the Qt application, but they are not used for anything yet. To access the resources from within the HTML file, you must prepend the relative paths to them with "qrc:/". For example, if the main HTML file of the WRT widget contained these lines:

<link rel="stylesheet" href="style/general.css" type="text/css" />
<script type="text/javascript" src="script/common.js" charset="utf-8"></script>
<script type="text/javascript" src="script/main.js" charset="utf-8"></script>

then the main HTML file in the Qt application would contain these lines:

<link rel="stylesheet" href="qrc:/style/general.css" type="text/css" />
<script type="text/javascript" src="qrc:/script/common.js" charset="utf-8"></script>
<script type="text/javascript" src="qrc:/script/main.js" charset="utf-8"></script>

Change all the paths in the HTML files (this doesn't concern the CSS files, they work like before) like instructed above and make this final change before you can try out your widget: Open the wrtwidgetwindow.cpp file again and load the main HTML file into the QWebView component with the following code:

QWebView* WRTWidgetWindow::createWebView()
QWebView* view = new QWebView(this);
return view;

Voilà! Go ahead and clean and build your Qt application now (Build > Rebuild Project). Along with other files, the resources are compiled into the application. Then, run the application (Build > Run or Ctrl+R). The HTML file that you loaded above appears into the QWebKit component.

Porting Considerations

It was assumed above that the HTML file of the widget is relatively simple (such as the one in the WRT Stub application). More often than not, this is not the case. This chapter presents several issues to concern when porting WRT widgets to Qt applications.

Web Runtime API

In addition to the standard JavaScript objects, there are extension APIs in WRT that allow widgets to access system properties, for example. For the list of these objects, see Web Runtime API reference in Web Developer's Library. Because these objects are WRT-specific, they won't be understood by Qt. For example, the code that hides the softkeys looks like this:


It must be removed from the Qt application in order to execute the JavaScript, and another way to accomplish the same result must be implemented, if needed. For example, to hide the softkeys you can show the application in fullscreen:

WRTWidgetWindow widget;

S60 Platform Services

WRT provides several JavaScript service APIs for accessing S60 Platform Services. As the name suggests, these APIs are S60-specific (and WRT-specific), so they won't be understood by Qt. Currently, it is not possible to achieve similar results through Qt's own APIs, even though Qt Mobility APIs are being developed and will eventually offer the same kind of functionality. Also the Qt hybrid application framework that Nokia is developing will provide that kind of functionality. Until then, however, you may have to implement a wrapper in Qt yourself to access the underlying platform features.

Dynamic Scalability

Handling orientation changes dynamically is important when designing usable mobile applications. The technique presented in the snippets "CS001498 Detecting orientation changes in WRT" and "CS001499 Reacting to the changes in screen size in WRT" works fine on Qt, because JavaScript event onresize can be used also from within QWebKit component to take care of the scalability. The only thing that you may want to take into account is to set the resolution to a fixed value on platforms that don't support orientation changes (for example, desktop Windows and Linux). Here is the code that accomplishes this:

WRTWidgetWindow widget;
#if defined Q_OS_SYMBIAN || defined Q_WS_HILDON
// On Symbian and Maemo, show the widget in full screen
#elif defined Q_OS_WIN32 || defined Q_OS_LINUX
// On desktop Windows and Linux, show the widget in WVGA resolution
widget.setFixedSize(800, 480);

Calling Qt Code from JavaScript

At some point, there may be a need to call Qt code from JavaScript. One such case is closing the application. JavaScript code "window.close()", which would normally close the window, cannot be used to close a window in Qt. For that, you will need to write some Qt code and call it from JavaScript. Here's the Qt function which exits the application:

#include <QtGui/QApplication>
void WRTWidgetWindow::close()

In order to call that function from JavaScript, you will need to make the Qt class available to "the JavaScript side" (or more technically said, from within the QWebFrame's JavaScript context). Add the following function to the class:

#include <QtWebKit/QWebFrame>
void WRTWidgetWindow::addJavaScriptObject()
// Make the WRTWidgetWindow available from within the QWebFrame's
// JavaScript context (as variable "clientApp")

The above function should be called when the QWebView component is created:

QWebView* WRTWidgetWindow::createWebView()
QWebView* view = new QWebView(this);
// Call the addJavaScriptObject slot when the javaScriptWindowObjectCleared
// signal is emitted, i.e. before the loading of the new window object
// starts
connect(view->page()->mainFrame(), SIGNAL(javaScriptWindowObjectCleared()),
this, SLOT(addJavaScriptObject()));
return view;

Add also the necessary function declarations into the header file:

void close();
private slots:
void addJavaScriptObject();

After those steps, you can write a JavaScript function which calls the WRTWidgetWindow's close() function .

// Exits the application
function exit() {

Lastly, call the JavaScript function. From HTML, for example:

<input id="btnExit" type="button" onclick="exit();" value="Exit" />

For more information, refer to the following code snippets:

131 page views in the last 30 days.