Writing your own applications

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

Special design considerations with Qtopia

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 Qtopia:

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: Handheld devices 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). Avoid "mouse over" type events.

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.

Qtopia 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 Qtopia 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 Qtopia

A new application (let's call it foo) can be incorporated into the directory structure of Qtopia with these easy steps:

Install the latest version of tmake, being sure to set $TMAKEPATH tuch that $TMAKEPATH/tmake.conf exists.
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 like the other qpr/*/*.pro files.
Add your directory to qpe/Makefile and re-run the configure script. This will create a Makefile.in and a Makefile. The Makefile.in should be distributed with you package so that others don't need tmake to install Qtopia.
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
    MimeType=video/foo
    Exec=foo
```
Unrecognized 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
Package up your application, including your pics/ and apps/ files...
```
    tar cfz foo.tar.gz qpe/pics/foo/* \
	qpe/apps/Applications/foo.desktop qpe/foo
```
and put the package on a web site for others to share!
If you want to make it easy to build binary packages of your application on the SHARP SL5000 or the Compaq iPAQ, make a control file similar to the other */*.control files - running mkipks on your control file will package up a binary that can be installed on the handheld.

Adding applications to the single-application build

To add an application to the single-application build, follow the procedure above, but with the following extras:

Put your main() in a file called main.cpp
Ensure your mainwindow class has a constructor that has the standard arguments (QWidget* parent, const char* name, WFlags ).
Add your program to the list in
```
taskbar/apps.h
```
In single/, run makepro - this adds all .h and .cpp files in single/../* to single.pro.

Re-generate the Makefile from the generated single.pro file:

	cd qpe/single
	export TMAKEPATH=~/tmake/lib/qws/linux-generic-g++
	tmake -o Makefile single.pro

Follow the single-application build instructions.

Running Qtopia applications on your device

Ensure that $QTDIR/lib/fonts/ contains fonts and the fontdir file.
Ensure that $QPEDIR/pics/ contains the pictures for the applications.
Set and export QWS_DISPLAY=Transformed:Rot270:0 if you're running on a device that requires screen rotation (eg. SL5000 or iPAQ).
The recommended locations for installing are the components are QTDIR="/usr" and QPEDIR="/opt/Qtopia".