News Archive (1999-2012) | 2013-current at LinuxGizmos | Current Tech News Portal |    About   

Article: Installing the Qt Palmtop Environment on the iPAQ

Jan 27, 2001 — by Rick Lehrbaum — from the LinuxDevices Archive — 4 views

Foreword: This article is the fourth in a series on Exploring Linux PDA Software Alternatives by Jerry Epplin that explores the history, status, alternative architectures, and future developments of Linux on PDAs and handheld devices. In this installment, Epplin takes a look at how Trolltech's Qt Palmtop Environment (later renamed to “Qtopia”) and related Linux software install and operate on a Compaq iPAQ PDA.

The Qt Palmtop Environment

Previous articles in the series introduced the options available (part 1), discussed the kernel project (part 2), and covered the Century Software Microwindows Development Environment (part 3).

The distribution uses the X window system, an appropriate choice for a high-end PDA like the iPAQ. But several companies provide GUI development environments implemented directly on the Linux framebuffer device, an approach that results in more efficient use of resources at the expense of the flexibility of X. One such development environment is the Qt Palmtop Environment (QPE) by Trolltech, the developers of the Qt GUI framework.

In this article, I will discuss what QPE is and what's unique about it, explain how to obtain and install it, and review its operation and utility as a developer's tool.

Qt, KDE, and the GPL

Most Linux users are aware of Qt, the GUI framework on which the KDE desktop environment is based. In the Linux desktop application development world, Qt competes with Gtk+, which forms the basis for the Gnome desktop environment. Until recently developers were faced with a choice between the pure open-source licensing of Gtk+, which has what many consider to be a less elegant programming model; and the somewhat more proprietary licensing of Qt, which has a clean, intuitive, object-oriented API.

The proprietary Qt license complicated the licensing of KDE, which is distributed under the GPL and LGPL — no one was quite certain whether it was strictly legal to link it with the proprietary-licensed Qt. But recent licensing changes by Trolltech have removed the licensing issues, somewhat tipping the scales toward Qt — and, by extension, toward KDE in the desktop world.

Trolltech's decision to make Qt available under the GPL simplifies the distribution of KDE, and as a result enables wider acceptance of Qt as an open-source GUI framework. This license move also extends to Qt/Embedded, Trolltech's version of Qt targeted toward low-footprint applications; and to QPE itself.

So at this point everything needed for QPE is fully open-source, which completes Trolltech's transition from frowned-upon black sheep of the open-source family to member in good standing. (Note: see my column entitled A developer's perspective on the GPLing of Qt for further discussion of Qt's licensing evolution and strategy.)

Qt's excellent documentation, and where to get it

Besides having good licensing terms, Trolltech's products are all extremely well documented. It would be hard to find a better documented open-source API than Qt. An excellent online API reference, manuals, and tutorials are available at And because of its popularity with desktop GUI developers there are many third-party books on Qt available (including one in the popular “SAMS Teach Yourself” series).

Qt/Embedded and QPE are also relatively well documented, considering that they are quite newly developed software tools. This factor alone is likely to have great appeal to many potential PDA and embedded system application developers who don't happen to share in the hard-core “RTSCTFOHTUI” (i.e. read-the-source-code-to-figure-out-how-to-use-it) mentality.

In short, Trolltech seems to understand that most professional developers prefer to focus on their application needs, rather than on the environment. And they have provided the documentation to meet this need.

Obtaining and installing QPE

As mentioned, Trolltech's QPE documentation is quite good. Installing the prebuilt binaries is trivial . . .

  • Download them from Trolltech's website, here;

  • Then, simply start with the standard distribution (see part 2 of this series), and substitute the /usr block from QPE.

The result is a very pleasing user interface, with a reasonable complement of handheld applications — an address book, calculator, spreadsheet program, todo list manager, MP3 player, and some games.

Building QPE from its sources

Building the distribution from scratch is also not difficult, but some notes are in order. Two options are available, the “static, single application build” and the “dynamic build”. The static build results in a smaller binary, but does not allow for adding applications after the build — this is appropriate for devices with fixed functionality. The “dynamic build” allows for loading new programs into the system, which is of course appropriate for typical PDA uses.

The procedure for building and installing either of these builds is straightforward. Begin by downloading Qt/Embedded and QPE from here. Then untar them and follow the directions in the qpe/README.html file.

Here are some things to keep in mind. First, be sure to add /skiff/local/bin to your PATH. Then, the Qt/Embedded build needs to have the h3600_ts.h file (see part 2 of this series for a brief discussion of the iPAQ touchscreen code). You will need to get this file from the kernel source code. Since it is probably a good idea to have this code on hand anyway, I recommend downloading it and specifying the path to it when you configure Qt/Embedded. My configure command line looks like this: “./configure -static -qconfig qpe-single -xplatform linux-ipaq-g++ -depths 16 -I/home/jerry/ipaq/”. Qt/Embedded should then build without error.

Building QPE itself involves some gotchas . . .

  • First, the directions contain the cryptic statement “Note that $QTDIR/bin/uic is not built by the above process. You should copy uic from Qt/X11 …” It may not be obvious from this statement, but the upshot is that you have to download Qt for X11 from here, configure and build it, and copy bin/uic from the Qt/X11 tree to bin/uic in the Qt/Embedded tree. Incidentally, this little oh-by-the-way digression is quite an annoyance for someone (like me) working with a modem and an old Pentium computer — as Qt/X11 is a large download and takes a long time to build!

  • Secondly, QPE itself also needs h3600_ts.h, but its configure script doesn't take the '-I' flag, so you have to copy the file to $QTDIR/include/linux before building. I'm guessing this would also work for building Qt/Embedded, eliminating the need for using '-I' for that build also — but I didn't take the time to test that theory.

  • Finally, be sure to do a 'make single' to build QPE, as README.html indicates. Note: don't just run 'make', as the output of the configure script suggests. If you do, you'll embark on a detour of several hours, as I did, unless you are fortunate to have a much faster computer than mine.
Once built, the “single” build works exactly as advertised, with all applications compiled into a single executable. The “dynamic” build has most of the same issues as the “single” — make sure “uic” and h3600_ts.h are available; otherwise just follow the directions.

In summary, despite the aforementioned nits, I found building and running QPE remarkably straightforward for a relatively new product. The minor complaints are magnified by the long build times of Qt/Embedded and QPE. My advice: get everything right before you start, so you don't have to repeat any lengthy steps.

The Qt API

As already stated, Qt has an elegant API, which follows an object-oriented programming model to which few purists would find any objection. I won't attempt to summarize the API here — see the excellent online documentation or one of the crowd of good books on the subject — but Qt has at least one notable feature that bears mentioning: the concepts of “signals” and “slots”.

Applications frequently need to link the output of one widget to the input of one or more other widgets. For example, perhaps a user clicking on a button needs to cause a label to clear its text and a spin box to increment. With a typical GUI API, one would define a callback for the button, which would call API functions to explicitly modify the state of the label and spin box. This works well, but seems like a clumsy way to set up a simple linkage between the button output and the input of the label and spin box.

In the Qt framework, widgets have predefined outputs called “signals” and inputs called “slots”. When the button associated with a QButton object is pressed, it emits a pressed() signal. The QLabel class has a slot called clear(); which, when called, clears the text of the label. Similarly, the QSpinBox class has a slot called stepUp(); which, when called, is equivalent to clicking the “up” button of the spin box.

To establish the links needed among these objects, call . . .

    QObject::connect(&button, SIGNAL(pressed()), &label, SLOT(clear()));
    QObject::connect(&button, SIGNAL(pressed()), &spin_box, SLOT(stepUp()));
. . . where “button”, “label”, and “spin_box” are objects of their respective classes. No further action is necessary.

Besides being more intuitive than the more common callback method, the slots and signals method allows for greater encapsulation of class functionality — neither the source nor the destination of the signals needs to know anything about each other. So replacing, for example, the label with a combo box can be accomplished with little or no impact on the button code. The only effect is on the connect() call, and there only minimally. As a result, for a complex application with lots of widgets, the encapsulation afforded by signals and slots can noticeably improve the understandability and maintainability of your code.

A GUI environment for busy developers

The Trolltech Qt Palmtop Environment (QPE) is ideal for those who want a clean, well-documented environment in which to develop PDA applications. Unlike other environments, you don't have to be a Linux expert to use it — follow the instructions and learn the Qt API, and you will have few problems. QPE has a pleasing look and feel, and the Qt API is a pleasure to write code to.

But I find QPE's documentation to be one of its greatest assets. Most professionals with looming deadlines have neither the time nor patience for the “just-read-the-source-code” philosophy of open-source documentation — and Trolltech apparently understands this. This factor alone is may well ensure QPE's success among a large class of developers in years to come.

About the author: Jerry Epplin has written embedded software for the past fifteen years, primarily for medical devices. He can be reached at [email protected]

The following articles may also be of interest . . .

This article was originally published on and has been donated to the open source community by QuinStreet Inc. Please visit for up-to-date news and articles about Linux and open source.

Comments are closed.