CartoonReader/Release_Notes.txt

QtWebKit: Cartoon Reader Example v1.2
=====================================

Cartoon Reader is a QtWebKit application that demonstrates software 
development using web technologies and Qt native code. This example 
demonstrates how an HTML5 CSS3 application can be built on top of QtWebKit. 
HTML5 supports the Web Database, which is used as the back end for this 
application.

This application has been tested on Symbian^3, Symbian S60 5th Edition, Maemo™ 5, and 
Windows XP.

The project is being hosted and developed at 
https://projects.forum.nokia.com/CartoonReader, where you can read additional 
documentation, look at possible newer revisions, and also contribute to the 
project.

-------------------------------------------------------------------------------

PREREQUISITES

C++ basics, SQL basics, and web development basics

-------------------------------------------------------------------------------

DESIGN CONSIDERATIONS

A hybrid approach was the starting point for this application because it 
demonstrates how you can target multiple platforms by designing the UI layer 
using web technologies such as JavaScript™, CSS3, and HTML5, and still expand 
the capabilities of JavaScript using native code.

The JavaScript code written for this example uses prototype-based object-
oriented programming. The Model-View-Control approach was taken when writing 
this application, as well as using pipes and filters.

The application was initially designed to be scalable. However, a decision was 
made to lock the view into the landscape orientation for mobile devices 
because of the form factor of most comics tested.

-------------------------------------------------------------------------------

IMPORTANT FILES & CLASSES

- CartoonReader/src/cartoonreader.cpp: 
CartoonReader class displays the UI using QWebView.

- CartoonReader/cartoonreader.qrc:  
References all the resources used in the application and includes them in the 
binary during the building. They can then be referred to with qrc:/ URLs.

- CartoonReader/html/cartoon-view.html: 
Contains the skeleton HTML as the basis for the UI. The styles and JavaScript 
are included from here.

- CartoonReader/js/FeedUpdateBroker.js: 
FeedUpdateBroker uses XMLHttpRequest to fetch the URL and then parses the 
relevant data from it.

- CartoonReader/js/cartoonreader-libs.js: 
cartoonreader-libs contains jQueryEventProxy, CartoonParser, CartoonSource, 
CartoonResultAdapter, and CartoonManagerBackend. They are all used from 
single-cartoon-view.js.

- CartoonReader/js/single-cartoon-view.js: 
Contains the single cartoon view logic.

- CartoonReader/js/cartoonmanager.js: 
Contains the cartoon manager view logic.

- CartoonReader/js/single-cartoon-first.js
Contains the logic needed for the splash animation hiding and insertion
of the other JavaScript files needed for the single cartoon view.

Important classes: 
QWebView

-------------------------------------------------------------------------------

KNOWN ISSUES

- Finger panning of the screen is currently not fully supported in Qt 4.6.2 
  or Qt 4.6.3. This is why the cartoon is put inside an iFrame element, which can 
  be scrolled on Maemo and Windows. On Symbian devices, the scrollbars need to be used.
- QWebKit uses databases that are currently created in a folder specified by 
  the QWebSettings::setOfflineStoragePath method. This means that you must 
  not run the application in Maemo manually (with 'run-standalone.sh 
  cartoonreader') for the first time as a root, otherwise the application cannot
  be started by the regular user, since the read access is only for the 
  root user.
- With Qt Creator 2.0.1: For Symbian, the version must be of a form x.y.z so 
  that the package creation succeeds, where x, y, and z are digits.
  When building for Maemo, the debian/changelog file version numbers are set to
  0.0.1 and a debian package with a version number 0.0.1 is created.
- Sometimes the application icon does not show in the Maemo application list 
  right after the installation. Rebooting the device will make it appear.

-------------------------------------------------------------------------------

RUNNING THE EXAMPLE

Cartoon Reader has a splash screen and two views, mainly operated on the touch 
UI.

Cartoon view

 - Shows the selected cartoon of the day.
 - Lets you navigate to previous strips of the cartoon by using the < and > 
   buttons.
 - Tapping the i button provides metadata of the cartoon as well as a related 
   joke (if available).

---------

Cartoon management view

To add new cartoons:
 - Tap the 'Add cartoon' button and type a known web cartoon URL.
 - Type the URL of a document that contains cartoons in Atom or RSS 
   feed format or of a site that provides a reference to the feed.
 - The application then tries to find a feed from the HTML.
 - If a valid feed is found, the application parses the cartoon information 
   from it and adds it to your selection.

To change the default cartoon that is loaded at application startup:
 - Tap the cartoon name you wish to be the default cartoon. The green asterisk 
   indicates the default one. After you have selected the default cartoon, it 
   will be loaded. 

To remove cartoons:
 - Tap the trash bin of the cartoon you want to remove.

---------

Other controls:
 - Tapping the Exit/Back button in the upper right-hand corner exits the 
   application or returns to the Cartoon view, respectively.
 - Tapping the Task switcher button sends the application to the background 
   (implemented in Maemo only).

-------------------------------------------------------------------------------

REQUIRED CAPABILITIES

NetworkServices

-------------------------------------------------------------------------------

BUILD & INSTALLATION INSTRUCTIONS

PREPARATIONS
~~~~~~~~~~~~

1. Extract the files from CartoonReader.zip.
2. Install the Nokia Qt SDK.

The steps for building and installing the application depend on the platform.

Build & installation instructions for Maemo 5 Fremantle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The assumed Maemo version is PR1.2. 

Note that you could also make the Debian packages and run the application in the Scratchbox environment, but you would need to make changes to the
debian files (for instance, in a debian/compat file, 5 instead of 7).

Running Cartoon Reader with Qt Creator
""""""""""""""""""""""""""""""""""""""""
To run the application on a Maemo device, set up 
Qt Creator and the device as instructed in the Nokia Qt SDK's readme 
files.

1. Open cartoonreader.pro with Qt Creator.

2. Add a Maemo target into the cartoonreader project. Make sure that the
   connection is set up.

3. Build and run the the project by clicking the Run button.

Creating a full deb package
"""""""""""""""""""""""""""""

1. Launch MADDE, which is installed with the Nokia Qt SDK.

3. Run qmake in the folder where cartoonreader.pro is located:

      mad qmake

4. Create the .deb package:

      mad dpkg-buildpackage

5. cartoonreader_0.0.1_armel.deb is created in the parent folder.

Installing the deb package on the device
""""""""""""""""""""""""""""""""""""""""""

1. Copy cartoonreader_0.0.1_armel.deb to the device.

2. Open the File manager on the Maemo device.

3. Click cartoonreader_0.0.1_armel.deb, and the Application manager is started.

4. Click OK to install Cartoon Reader.

Setting up root acces on the Nokia N900 device (optional)
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

1. Open the Application manager from the Application menu > App manager.

2. Install 'rootsh' from the Application manager's menu > Search > Type rootsh 
   > Search > rootsh, and wait for the Application manager to install the 
   application.

   See more information at http://wiki.maemo.org/Root_access.

Installing the deb package on the device manually (optional)
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

You need to enable root access for the device first, if dpkg is used.

Another option would be to use MADDE to send the Debian package and install it 
from the command line. Sending only the executable file and running it is also 
possible, thus saving time in creating a package.

See http://wiki.maemo.org/MADDE/Device_runtime for more details.

1. Copy the Debian package to the device.

   Using the PC Suite mode is less complicated, because in Mass Storage mode, 
   the /home/user/MyDocs/ folder is not accessible from inside the device, 
   and thus you might need to unplug the USB cable before continuing.

2. Open X Terminal by clicking Application menu > X Terminal, and typing the 
   following commands:

     sudo gainroot
     dpkg -i /path/to/cartoonreader_0.1_armel.deb

   For instance, if the file is copied into the Nokia N900 device folder, the path is 
   /home/user/MyDocs/.

3. Start the application from the Cartoon Reader icon shown in the application 
   menu.


Build & installation instructions for Symbian platform
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Prerequisites
"""""""""""""""

To run the application on a Symbian device, set up 
Qt Creator and the device as instructed in the Nokia Qt SDK's readme files.


Running Cartoon Reader with Qt Creator
""""""""""""""""""""""""""""""""""""""""

1. Open cartoonreader.pro with Qt Creator.

2. Add a Symbian target into the cartoonreader project. Also make sure that 
   TRK is running on the device and that the TRK connection is set up. If there are 
   problems with the connection, you can install the created SIS package 
   manually.

3. Build and run the the project by clicking the Run button. A SIS package is 
   created and then installed on the device if the TRK connection is working.
   
   If the connection is not working, the SIS file can be installed manually 
   with Nokia PC Suite or Ovi Suite by double-clicking it, after which it
   is installed on the device.

   If you get a Certificate error during the installation of a self-signed
   package, check that App.Manager > Settings > Software Installation is set
   to All.

Precreated package installation
"""""""""""""""""""""""""""""""""
1. Check that you have Nokia PC Suite or Ovi Suite installed.

2. Navigate to the folder CartoonReader/install/sis/.

3. Double-click cartoonreader_S60_5_0.sis to install it.

4. Follow the instructions.

   If you get a Certificate error during the installation of a self-signed
   package, enable the installation of unsigned packages:
   Set App.Manager > Settings > Software Installation to All.

Build & running instructions for Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Prerequisites
"""""""""""""""
- Qt 4.6.2 or newer must be installed with MinGW. It is available with the Qt 
  SDK for Windows from http://get.qt.nokia.com/qtsdk/.

Running Cartoon Reader with Qt Creator
""""""""""""""""""""""""""""""""""""""""

1. Open cartoonreader.pro with Qt Creator.

2. Add a Desktop target into the cartoonreader project.

3. Build and run the the project by clicking the Run button.

Building & running Cartoon Reader manually
""""""""""""""""""""""""""""""""""""""""""""

1. Open the Qt Command Prompt from the start menu.

2. Run the following commands:

     qmake
     mingw32-make release

3. Check that cartoonreader.exe was created.

4. Run cartoonreader.exe found in the release folder of the project folder.

-------------------------------------------------------------------------------

COMPATIBILITY

Maemo
~~~~~~
Maemo 5

Qt 4.6.2

Tested on:
 - Nokia N900 device

Developed and tested using:
 - Nokia Qt SDK
 - Maemo SDK has also been used previously


Symbian
~~~~~~~~
Symbian^3
Symbian S60 5th Edition

Qt 4.6.3

Tested on:
 - Nokia N97 
 - Nokia N8 

Developed and tested using: 
 - Nokia Qt SDK

Windows
~~~~~~~~
Windows XP

Qt SDK for Windows (Qt 4.6.2)
MinGW 3.15.2

Developed and tested using: 
 - Nokia Qt SDK, with Qt 4.6.2 binaries of the Qt SDK for Windows

-------------------------------------------------------------------------------

CHANGE HISTORY

1.2	Button presses are now indicated better. Bug with the onscreen keyboard has been fixed.
1.1	Proxy support added. Textfield focusing improved for Symbian^3.
1.0	Initial version.

-------------------------------------------------------------------------------

ADDITIONAL DOCUMENTATION

https://projects.forum.nokia.com/CartoonReader