 |
 |
 |
 |
 |
|
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.
- 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
- 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.
- 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).
- 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.
- Strip the executable:
strip -R .note -R .comment single/qpe
-
Set the QPEDIR environment variable to the
base directory of QPE, e.g export QPEDIR=~/qpe
- 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.
- 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
- 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.
- 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).
- 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).
- Strip the executables and libraries:
strip -R .note -R .comment bin/* $QTDIR/libqte.so* $QTDIR/libqpe.so*
-
Set the QPEDIR environment variable to the
base directory of QPE, e.g export QPEDIR=~/qpe
- 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.
- 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:
- 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.
- 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).
- 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.
./bin | The applications
|
./apps | The menus
|
./pics | The icons and images
|
./docs | Some documentation of QPE
|
./etc | Pen-input and dictionary files
|
- Strip the executables/libraries with arm-linux-strip.
- If you built dynamically, copy or NFS mount $QTDIR/lib onto
the iPAQ.
- 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
- 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.
- 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:
- Install the latest version of
tmake.
- Create a new subdirectory qpe/foo.
- 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
- 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.
- Compile your application:
cd qpe/foo
make
- 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.
- Create an icon for your application in pics/foo_icon.png
(or .gif, .xpm, etc.).
- 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.