18.8.10

Unofficial QtWRT tutorial 1: Hello, view modes!

Almost one month ago, we announced Qt Web Runtime, and released some snapshot for N900. Basically, QtWRT is a framework, using which you can write "native" application with standard web technology, e.g. HTML, CSS, and JavaScript. As a good starting point, you should take a look at this article.

Note that we're still working on it, and it's now just in the technology preview state ;)

1 install QtWRT
You should enable the extras-devel repository on your Rover and install the qtwrt-experimental package from there. Then, you can find in your Application Manager that Qt Web Runtime Technology Preview for N900 installed.


2 config.xml
To write your own web applications, besides the normal HTML pages, you also need a config.xml file to define e.g. the starting file, icon, features you need (i.e. access to Device APIs), as well as author's information, etc. More details and default values are defined here.

The following piece shows a minimum sample:
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns = "http://www.w3.org/ns/widgets">
</widget>


You can also define the name and icon (only PNG files supported) of the web app in config.xml:
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns = "http://www.w3.org/ns/widgets">
  <name>A sample web app</name>
  <icon src="app_icon.png" />
</widget>

The name and icon will be appeared in the Application Grid or the Desktop menu --> Add widget based on the view mode the web app supports (see below).

3 view modes
View modes define the visual presentation of web applications. The W3C spec has defined five different view modes, but we only support three of them in this snapshot:
windowed - The default view mode. You can find / launch web apps in this mode from the Application Grid. It also supports the native chromes and user-defined menus.
fullscreen - It can also be found / launched from the Application Grid. No need to say what is full screen, right ;)
minimized - It equals to the native widgets on the Home Screen.

The following piece defines the view modes in config.xml:
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns = "http://www.w3.org/ns/widgets"
    viewmodes = "someviewmode fullscreen minimized" >
</widget>

The unknown view mode "someviewmode" is ignored. It supports both "fullscreen" and "minimized" mode in this case. If no supported view mode is defined, "windowed" mode is used.

You can get the current view mode through the widget.viewMode interface in JavaScript.

Also, the transfer among different view modes is supported, with the exception from windowed / fullscreen to minimized, e.g.:
<a href="javascript:widget.viewMode='windowed'">Go to windowed mode</a>

With the following code, you can handle the view mode change event in the viewModeChanged function:
widget.onviewmodechange = viewModeChanged;
function viewModeChanged(mode)
{
  if (mode == "windowed") {
    // going to windowed mode
  } else if (mode == "minimized") {
    // going to minimized mode
  } else if (mode == "fullscreen") {
    // going to full screen mode
  }
}


4 package your application and install it
Well, I just assume you have enough knowledge to write whatever HTML page you like, and have renamed it to index.htm (the default starting file name).

Now just zip all your HTML files together with the config.xml file. Note that the config.xml file should be at the top level of the zip, and the name is case sensitive.

Then please rename it to *.wgt and copy it to your Rover. To make it like a native application, you can install it from the File Manager, and you can find your installed web applications in Application Manager!

Eh, I'm talking about some details during the installation here. You can skip this if not interested.

When you tap on the wgt file in File Manager, widgetinstaller is launched. It does some sanity checking of it, e.g. whether it's a valid zip file, if the config.xml is valid, etc., then convert it to a Debian file, and use the Application Manager to install the generated Debian file.

If you are interested in the generated Debian file, you can use the "--no-install" option of the widgetinstaller to have it copied to the current directory.

5 a sample
First, let's write the config.xml file.
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
    id="http://xizhizhu.blogspot.com/qtwrt/view-modes-sample"
    viewmodes="minimized fullscreen windowed">
  <name>View Modes Sample</name>
  <description>
    Well, it shows how the view modes work.
  </description>
  <author href="http://xizhizhu.blogspot.com/" email="xizhi.zhu@gmail.com">Xizhi Zhu</author>
  <license>In the public domain without any warranty.</license>
</widget>


Then the HTML file.
<html>
<header>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>View Modes</title>
  <script type="text/javascript">
    function init()
    {
      output = document.getElementById("viewmode");
      output.innerHTML = widget.viewMode;

      widget.onviewmodechange = changeViewMode;
    }

    function changeViewMode(mode)
    {
      output.innerHTML = widget.viewMode;
    }
  </script>
</header>

<body onload="init()">
  <div id="viewmode"></div><br />
  <a href="javascript:widget.viewMode='minimized'">minimized</a><br />
  <a href="javascript:widget.viewMode='windowed'">windowed</a><br />
  <a href="javascript:widget.viewMode='fullscreen'">fullscreen</a>
</body>
</html>


Now let's zip the file, send it to N900 and install it from the File Manager. You can find it installed in the Application Manager and already launched in the home screen.


You may ask, why the last line of "fullscreen" is not shown there? Well, that's due to the fixed size in the minimized mode, 312x82. Also, in the minimized mode, you can't actually interact with it, but only tap on it and open the windowed or fullscreen mode if supported. In the minimized mode, it's the same as native widgets that you can move it around, close it and add it back, as well as the transparent background by default.

Then you can tap the links to toggle between windowed and fullscreen mode. And for sure you'll find another "limitation" that you can't go back to minimized mode from the link. The only way is to close the window. Well, that's exactly what is expected.



Another thing is, in the fullscreen mode, it automatically shows the "go back to windowed" button if windowed mode is supported, otherwise the "close" button. Emm, the same as the browser, right?


Updated on 19.8.2010
Screenshots added into the posts ;)

13 comments:

  1. Some screenshots at:
    http://share.ovi.com/album/xizhizhu.QtWebRuntim

    ReplyDelete
  2. Good post. Embedding the screenshots in the own post would make it even better!

    ReplyDelete
  3. Very useful post!

    Does it support .swf or only CSS, HTML & JavaScript are supported?

    ReplyDelete
  4. @Avinash

    We're planning to support Flash in the near future, but it MIGHT work as Web Runtime is based on Qt WebKit.

    ReplyDelete
  5. Great post but you should have proper explanation how one "enable the extras-devel repository on your Rover and install the qtwrt-experimental package from there"

    ReplyDelete
  6. @Jyrki:
    Please follow the instructions at http://wiki.maemo.org/Extras-devel to enable extras-devel repository :)

    ReplyDelete
  7. Thanks a lot for this great tutorial. QtWRT is really exciting for those of us, who has roots in webdevelopment.

    I have one addition though, 'cause it caused me trouble last night.

    When you zip it, make sure that your package is not compressed. Choose "stored" or whatever under settings. I did this in winrar, an it was smooth sailing from there on.

    Until I figured it out, all I got was errors from App Manager.

    ReplyDelete
  8. @Martin: We use zlib to uncompress, which supports the zip package to be compressed. I guess the problem is that WinRAR might have some very tricky settings when it compresses the zip package.

    ReplyDelete
  9. Hmm, I guess.

    At first, I wasn't using WinRAR though. I just right-clicked and chose "send to zip" in Vista. I read about the compression settings and then used WinRAR from there on, as it provided the settings. I haven't really tried compressing it with WinRAR, so it might actually work too.

    ReplyDelete
  10. Hello Xi,

    I've copied the config.xml and html file. Followed the steps, but doesn't work. Appmanager says the installation is 0kb instead of the 2kb you have in the picture.

    Can you post a link to a down loadable example.wrt with the above files?

    ReplyDelete
  11. @Anonymous

    Seems that QtWRT can't run well in PR1.3, and we're preparing a new release for PR1.3.

    ReplyDelete
  12. Hi Xizhi,
    I've been playing with QtWRT for a little while on my N900, and am excited about potential possiblities. I am trying to port a public transport widget, and have been able to get it to partially run, but I am stuck with how to allow network access in the config.xml file. I have tried the following within :



    I have found other examples, but this was what I found on W3C website. Are you able to assist?

    ReplyDelete
  13. Sorry, looks like my example was stripped:

    < access origin="*" />

    ReplyDelete