/*! \page start.html \title Getting Started Qtopia - The Qt palmtop environment

Qtopia - The Qt palmtop environment

Qtopia is a windowing system for handheld devices. It offers developers the powerful Qt API, and provides users with fast and intuitive interaction.

Developing for Qtopia

The Qt API includes rich GUI functionality, and is suitable for both large and small applications.

Since Qtopia offers the complete Qt API, you can do much of your development on any of the other platforms for which Qt is available - Windows, Unix/X11, or Mac OS X. However, for optimal tailoring of your application to the smaller screen and other demands of a handheld environment, you should use the Qtopia SDK.

The Qtopia SDK allows you to develop Qtopia applications under the Linux desktop environment using the Qt Virtual Framebuffer, which completely emulates the handheld Qtopia environment. It also includes cross-compiler software so that you can compile your application to run on the target handheld device. If you do not already have the Qtopia SDK (this document is normally part of the SDK), contact info@trolltech.com, or see the Trolltech web site.

To build applications for the SHARP SL5000 or similar StrongARM-based devices, you will also need a StrongARM cross compiler. Entrants in the programming contest for this device will have received both the SDK and a cross-compiler.

The SDK includes an example program. We recommend that you compile and run this example to learn how things work, before tackling your own projects.

To compile the example program for running on the Linux desktop:

Check the environment is correct:

   export QPEDIR=/opt/Qtopia
   export QTDIR=/opt/Qtopia
   export PATH=$QTDIR/bin:$PATH
   export TMAKEPATH=/opt/Qtopia/tmake/lib/qws/linux-generic-g++
   export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH

Take a copy of the example:

   cd somewhere
   cp -r $QPEDIR/example .
   cd example

Generate a Makefile:
```
   tmake -o Makefile example.pro
```
Build the example:
```
   make
```

Install it:

   su # root privileges required to install
   cp example.desktop $QPEDIR/apps/Applications
   cp Example.png $QPEDIR/pics
   cp example $QPEDIR/bin
   exit # no need to be root anymore

To run it, first run the Qt Virtual Framebuffer:
```
   qvfb &
```
Then run the Qtopia environment:
```
   qpe
```
Your application should be available in the Applications tab visible inside the Qt Virtual Framebuffer window.
If you want to distribute your applications to others, build an RPM package, e.g.:
```
   mkipks -rpm -arch i386 example.control
```

To make your own application, use the example program as a model. Make sure that when you add files to your project, you also add them to your project file (e.g. example.pro) and rerun the tmake command to update the Makefile.

To build you application for the SHARP SL5000 rather than just running on the desktop, the process is similar:

Check the environment is correctly set for the SHARP SL5000:

   export QPEDIR=/opt/Qtopia/sharp
   export QTDIR=/opt/Qtopia/sharp
   export PATH=$QTDIR/bin:/usr/local/arm/bin:$PATH
   export TMAKEPATH=/opt/Qtopia/tmake/lib/qws/linux-sharp-g++

Rebuild the makefile ($TMAKEPATH has changed) above:
```
   make clean
   tmake -o Makefile example.pro
```
Build it:
```
   make
```

Install it (note that this is now going into the /opt/Qtopia/sharp/ directory):

   su # root privileges required to install
   cp example.desktop $QPEDIR/apps/Applications
   cp Example.png $QPEDIR/pics
   cp example $QPEDIR/bin
   exit # no need to be root anymore

To install it on a device, build an ipk package file:
```
   su # root privileges required to strip the executable
   mkipks example.control
   exit # no need to be root anymore
```
The resulting example-1.0.0.ipk can be installed on the SL5000 by using Qtopia Desktop.

Building Your Own Applications

Once you have built the example, you can proceed with writing your own applicatons. If you are not familiar with Qt, you should consult the Qt documentation by pointing your web browser at /opt/Qtopia/doc/html/index.html when you have installed the SDK, or use the online Trolltech Documentation Site. The Qt Whitepaper provides a good overview of, and introduction to, the Qt API.

When you add more files to your application, just edit the project file (e.g. example.pro) and rerun the tmake command.

The .ui files are Qt Designer user interface files. You can create and edit these using Qt Designer:

   designer example.ui

Qt Designer's online documentation includes a complete tutorial. */