qtbubblelevel/release_notes.txt

Qt Bubble Level v.1.1
=====================

Qt Bubble Level is a simple Qt Quick application that uses accelerometer 
sensor information to calculate the inclination of the device and presents 
this as a traditional Bubble level. The application provides a calibration 
feature to handle any possible errors in accelerometer readings. The UI is 
made using Qt Quick and the engine gets the accelerometer data via the 
QtMobility QAccelerometer sensor.  The application is compatible with Maemo 5 
with Qt 4.7.0 and Symbian^3 devices with Qt 4.7.1 (or higher) and 
QtMobility 1.1.0 (or higher).


FILES
-------------------------------------------------------------------------------

src/main.cpp

- The main file of the application. In practise, creates a QtMobility sensor 
  and QDeclarativeView and connects a set of signals to the appropriate slots. 
  The integration of QML and Qt code is done in the main function. 
  
src/taskswitcher.cpp

- Provides a minimise feature via DBus to minimise the application.

src/accelerometerfilter.h

- Provides accelerometer data via QtMobility. 

src/settings.h

- Provides saving and reading of angle calibration in a platform-independent 
  way.

src/bubblelevel.qml

- Main QML file, implements the main layout for the graphics. Contains the
  location of task switcher and exit button. The location of the glass tube is 
  also set here. Also contains the function which is used as slot connected in 
  main.cpp.

src/button.qml

- Implements the functionality of a button with a minor press animation.

src/tube.qml

- Contains the graphics for bubble, scale, and reflection. These are drawn on
  different layers to provide the effect that the bubble is inside the glass 
  tube. The conversion of device inclination to bubble position is made here.

src/debian/

- The directory which contains files related to Debian (Maemo) packaging.

install/

- The compiled installation package is located here.


CLASSES AND ELEMENTS USED
-------------------------------------------------------------------------------

The most important Qt classes and QML elements used in the application are
listed here.

Qt classes
~~~~~~~~~~
 QDeclarativeViewer   - used to interpret QML files
 QAccelerometer       - used to get accelerometer data from the device
 QAccelerometerFilter - used to convert accelerometer data from radians to
                        degrees and to signal accelerometer data to the UI
 QSettings            - used to save and restore the correction factor from 
                        the device's memory
                        
QML elements
~~~~~~~~~~~~
 BubbleLevel - the main QML element, represents the whole UI. Contains the
               signals, functions, and one property to interact with the Qt
               model. Contains the Tube element and a hidden calibration 
               dialog positioned under the QtBubbleLevel sign.

 Tube        - represents the glass tube of the bubble level. Contains Image
               elements to draw the bubble, scale lines, and the reflection.
               
 Button      - built from Rectangle, Image, and MouseArea, handles mouse press 
               and implements a minor press animation by scaling the element 
               down on mouse press.


KNOWN ISSUES
-------------------------------------------------------------------------------

- None.
  
  
INSTALLATION INSTRUCTIONS
-------------------------------------------------------------------------------

Mobile device (Symbian^3)
~~~~~~~~~~~~~~~~~~~~~~~~~

There are two ways to install the application on the device.

0. The Qt 4.7.1 or higher libraries must be installed. See the section 
   COMPATIBILITY for more information about installing these.

1. a) Drag the qtbubblelevel.sis file to the Nokia Ovi Suite when the device 
      is connected with the USB cable.
   
   OR
   
   b) Send the application directly to the Messaging Inbox (for example,
      through Bluetooth).

2. After the installation is complete, return to the Application menu and
   select the Applications folder.
   
3. Locate the QtBubbleLevel icon and select it to launch the application.


Mobile device (Maemo)
~~~~~~~~~~~~~~~~~~~~~
0. The Qt 4.7.0 libraries must be installed. See the section COMPATIBILITY for 
   more information about the installing procedure.

1. Copy the install/qtbubblelevel_1.1.0_armel.deb file into a specific folder 
   of the device (for example, 'MyDocs').

2. Start XTerm. Type 'sudo gainroot' to get root access.

3. 'cd' to the directory into which you copied the package (for instance, 
   'cd MyDocs').

4. As root, install the package:
   dpkg -i qtbubblelevel_1.1.0_armel.deb

5. Launch the Applications menu.

6. Locate the QtBubbleLevel icon and select it to launch the application.


RUNNING THE APPLICATION
-------------------------------------------------------------------------------

Launch Qt Bubble Level on your device. The bubble in the glass tube will show 
the level of the device's x-axis relative to gravity. When the device is 
tilted to either direction 20 degrees or more, the bubble will be at the 
corresponding end of the tube.

The application can be minimised with the icon in the upper left corner, or 
closed with the X in the upper right corner.


COMPATIBILITY
-------------------------------------------------------------------------------

- Symbian^3 with Qt version 4.7.1 or higher.

  1. Download Qt for Symbian 4.7.1 (or higher) from qt.nokia.com.
  
  2. Drag qt_installer.sis on top of the device in Nokia Ovi Suite while
     the device is connected. The SIS package is found in the installation
     folder of Qt for SYmbian 4.7.1 (or higher).

- Maemo with Qt version 4.7.0 which is included in PR1.3. 

  1. Use Nokia Ovi Suite for updating the device's firmware to PR1.3

Tested on:

- Nokia N900
- Nokia N8
- Nokia E7


VERSION HISTORY
-------------------------------------------------------------------------------

1.1 Added QtMobility and Symbian^3 support. Added the calibration feature.

1.0 Initial version. Supports only Maemo, the accelerometer information is 
    read using the native Maemo interface. Published in FN Projects only.