The Qt Palmtop Environment, for Qt/Embedded

Overview

This package should also work fine with Qt/X11 and Qt/Windows, but it is targetted at small handheld devices such as the Compaq iPAQ, and includes some Qt/Embedded specifics such as additional input methods for virtual keyboards and handwriting recognition.

This page describes installation of QPE and development of new QPE application. There is some user-level documentation for the environment here, but you'll normally read that on your handheld device when you've got this working!

Changes since 1.1.0 release

Battery meter added, sensible wordgame defaults, fixed flipping in solitaire, fixed time setting, fixed keyboard/pickboard slowness.

Changes since 1.0 release

Much improved build system. Spreadsheet, Terminal, and Wordgame added. Datebook I/O added. Many bug fixes.

Installation

There is a pre-built binary package of the QPE built for Linux/x86, at:

    ftp://ftp.trolltech.com/qt/embedded/palmtop/qpe-1.1.0-bin-x86.tar.gz

To build the package yourself, you have a number of options, each described in detail below.

Static single-application build

This build method gives the smallest and fastest result, and reflects a type of build that an embedded device might use when the application suite is more-or-less fixed.

  1. Install the QPE Qt configurations, which are tuned to the requirements of QPE and exclude certain functionality from the library in order to minimize the size of the resulting executable:
        cp ./qt/qconfig*.h $QTDIR/src/tools
    

  2. Build Qt/Embedded statically and with the "-qconfig qpe-single" configuration which uses the files copied above. Be sure to delete any existing dynamic versions as the linker will prefer those:
        cd $QTDIR
        make clean
        ./configure -static -qconfig qpe-single
        make
    

    This creates $QTDIR/lib/libqte.a.

  3. Note that $QTDIR/bin/uic is not built by the above process. You should copy uic from Qt/X11 (uic needs the "Everything" configuration as it uses properties).

  4. Build the entire QPE package as a single application:
        cd back-here
        ./configure -static
        make clean
        make single
    

    This creates $QTDIR/lib/libqpe.a and single/qpe.

  5. Strip the executable:
        strip -R .note -R .comment single/qpe
    

  6. Set the QPEDIR environment variable to the base directory of QPE, e.g export QPEDIR=~/qpe

  7. You now have an executable "single/qpe", which includes a complete windowing system, multiple input methods, and a reasonable collection of nifty little applications.

Dynamic build

This build method gives the most extensible result, and reflects a kind of build that an embedded device might use when the application suite is extended by the end-user.

  1. Install the dynamic configuration, which is tuned to the requirements of QPE when built as a set of applications. Note how this excludes certain functionality from the library in order to minimize the size of the resulting executable:
        cp ./qt/qconfig-qpe.h $QTDIR/src/tools/qconfig-local.h
    

  2. Build Qt/Embedded dynamically and with the "-qconfig qpe-single" option which uses the files copied above:
        cd $QTDIR
        make clean
        ./configure -qconfig qpe
        make
    

    This creates $QTDIR/lib/libqte.so*. You can of course use the default "Everything" Qt configuration, which isn't in the spirit of making small applications, but is useful if you want to have the entire Qt API available.

  3. Note that $QTDIR/bin/uic is not built by the above process. You should copy uic from Qt/X11 (uic needs the "Everything" configuration as it uses properties).

  4. Build the entire QPE package:
        cd back-here
        ./configure
        make clean
        make
    

    This creates $QTDIR/lib/libqpe.so* and bin/*, including a bin/qpe that launchers applications as separate processes (rather than as built-ins which the single-application build does).

  5. Strip the executables and libraries:
        strip -R .note -R .comment bin/* $QTDIR/libqte.so* $QTDIR/libqpe.so*
    

  6. Set the QPEDIR environment variable to the base directory of QPE, e.g export QPEDIR=~/qpe

  7. You now have a collection of applications in the bin/ directory, which includes a complete windowing system, multiple input methods, and a collection of applications.

  8. To add more applications, see the section below on writing your own applications.

Note that the memory consumption with this type of build is currently excessive due to the details of ELF.

Build for iPAQ

First go to http://handhelds.org, and install Linux on your iPAQ.

There is a pre-built binary package containing everything you need to put QPE on the Linux iPAQ, at:

    ftp://ftp.trolltech.com/qt/embedded/palmtop/qpe-1.1.0-bin-ipaq.tar.gz

To build QPE from the sources:

  1. Install the ARM cross-compiler from handhelds.org. Ensure that you have the file /skiff/local/arm-linux/include/linux/h3600_ts.h, which may not be in the toolchain package you download.

  2. Build the Qt library and the QPE package by following the instructions above for either the Single-application or Dynamic builds, but add the -xplatform linux-ipaq-g++ options when you run both configure commands (you can also add the -depths 16 option when compiling Qt since 16bpp is the only depth the iPAQ supports).

  3. Copy or NFS mount the following directories onto the iPAQ, and point both $QTDIR (for etc) and $QPEDIR (for pics and docs) to the directory where you copy them. Check that the bin directory is on $PATH.

  4. Strip the executables/libraries with arm-linux-strip.

  5. If you built dynamically, copy or NFS mount $QTDIR/lib onto the iPAQ.

  6. Copy or NFS mount $QTDIR/etc/fonts/ onto the iPAQ. Qt/Embedded ships with many fonts, some quite large, so just ensure you have at least the following files:

    fontdir
    helvetica_*.qpf
    smoothtimes_{170,100}_50*.qpf
    smallsmooth_*.qpf
    micro_*.qpf
    fixed_*.qpf
    

  7. On the iPAQ, login from your desktop machine, kill X and run qpe. Add the -display Transformed:Rot270:0 if you want the "normal" iPAQ screen orientation.
  8. To setup QPE to start at boot, you'll need to make your own /usr cramdisk or use the new jffs filesystem so that you can change the files on your iPAQ directly. This is outside the scope of this document, the best place to go for iPAQ related issues is the Mailing Lists at Handhelds.org.

Building for the Cassiopeia

A build for the Cassiopeia is here:

    ftp://ftp.trolltech.com/qt/embedded/palmtop/qpe-1.1.0-bin-cassiopeia.tar.gz

Writing your own applications

Developing an application to add to your QPE is just like developing any other application with the Qt API. You have all the same classes and functionality.

Special design considerations with QPE

You can develop your application using Qt/X11 or Qt/Window and just recompile it for Qt/Embedded, but you should keep in mind a number of differences in the devices that are commonly running QPE:

Smaller display
Require no more than about 240x240 pixels. Use QTabBar to organize functionality into separate groups, or just reduce the functionality - you don't need to provide every possible feature on a palm-sized version of your application. Note that the default font in Qt/Embedded is smaller than that for Qt/X11 and Qt/Windows.

Worse Keyboard
Organize functionality to be less dependent on keyboard input and more dependent on mouse input. Try using a QComboBox where you might otherwise have used a QLineEdit and thus provide a "History" list of previously typed choices.

Different Mouse
Device commonly use a stylus, which means only one mouse button, and no mouseMoveEvent() if the "mouse button" is not "pressed". You can provide "right mouse-button" functionality with the "press and hold" convention (eg. the menu in Filebrowser, flags in Minesweep).

As with any application development with Qt/Embedded, the Qt Virtual Framebuffer tool in $QTDIR/src/tools/qvfb is a very useful development aide, since you can control the display size and run with the exact fonts.

As with any development with Qt, the Qt Designer tool in $QTDIR/tools/designer helps you organize functionality visually so you can more easily create a small yet logical and functional GUI.

QPE is less file-oriented than a typical Unix workstation: the user probably doesn't want to worry about file and directories, just the names of the document they have written that are appropriate for the application they are running.

To support this more document-centric model, the QPE library classes provide a basic document selector and file manager. See the FileSelector and FileManager classes defined in library/fileselector.h and library/filemanager.h. These mechanism are very simplistic currently, and they'll develop as the system improves.

File structure for new applications in QPE

A new application (let's call it foo) can be incorporated into the directory structure of QPE with these easy steps:
  1. Install the latest version of tmake.

  2. Create a new subdirectory qpe/foo.

  3. Write your source code in qpe/foo and write a tmake project file, qpe/foo/foo.pro, file that looks something like this:
        TEMPLATE        = app
        CONFIG          = qt warn_on release
        DESTDIR         = ../bin
        HEADERS         = foo.h \
    		      fooview.h
        SOURCES         = foo.cpp \
    		      fooview.cpp \
    		      main.cpp
        INCLUDEPATH     += ../library
        DEPENDPATH      += ../library
        LIBS            += -lqpe
        INTERFACES      = fooeditor.ui
        TARGET          = foo
    
  4. Create a Makefile using tmake:
        cd qpe/foo
        export TMAKEPATH=~/tmake/lib/qws/linux-generic-g++
        tmake -o Makefile foo.pro
    

    In place of generic, use x86, ipaq, or cassiopeia.

  5. Compile your application:
        cd qpe/foo
        make
    

  6. Add a foo.desktop file somewhere in qpe/apps, such as qpe/apps/Applications/foo.desktop. This file supports a subset of the functionality of standard .desktop files found in KDE. For example:
        [Desktop Entry]
        Name=Foo Viewer
        Icon=foo_icon
        Exec=foo
    
    Additional fields are ignored, and if they are used in the future, it will be according to the standard interpretations.

  7. Create an icon for your application in pics/foo_icon.png (or .gif, .xpm, etc.).

  8. Package up your application, including your pics/ and apps/ files...
        tar cfz foo.tar.gz qpe/pics/foo_icon.png \
    	qpe/apps/Applications/foo.desktop qpe/foo
    
    and put the package on a web site for others to share!

Discussion

The forum for general Qt discussion is the Qt-Interest mailing list.

The forum for topics specific to Qt/Embedded or to the QPE is the Qt-Embedded-Interest mailing list. Subcribe to that list by sending the word subscribe to qt-embedded-interest-request@trolltech.com. Unsunbscribe by sending unsubscribe.