Qt API | Qtopia API Qtopia Documentation

Qtopia - The main() function

Starting with Qtopia 1.7, it is no longer recommended that the main() function be written explicitly by the programmer. Instead two macros are provided to declare the application entry point:

QTOPIA_ADD_APPLICATION(NAME,IMPLEMENTATION)
QTOPIA_MAIN

QTOPIA_ADD_APPLICATION() generates code to instantiate the main window, where NAME is the application executable name and IMPLEMENTATION is the application window class.

QTOPIA_MAIN is either the main() implementation or the interface code necessary to make the application a quicklauncher plugin (if QTOPIA_APP_INTERFACE is defined - see below).

The main.cpp of all applications should be modeled on this example:

#include "mymainwindow.h"
#include <qtopia/qpeapplication.h>

QTOPIA_ADD_APPLICATION("myapp", MyMainWindow)
QTOPIA_MAIN

The application window should be implemented in a self-contained way: it should not perform application-level operations such as testing parameters, calling exit(), or calling quit(); all of these are handled by QPEApplication. Your application window should call close() if it needs to explicitly close, and it must be prepared for the possibility that show() will be called again after the close() but before the application window destructor. In other words, implement your application window in a way that it could be used easily from other applications. If you take this approach it will also mean that most of your program can be trivially reused on Qt/X11, Qt/Windows, Qt/Mac, and any other ports of the Qt API.

Enabling Quicklaunching

Starting with Qtopia 1.7, applications can be built as plugins that can be loaded by the quicklaucher. The quicklauncher is a stub application that is pre-loaded and can load an application plugin and change personality to the plugin application. The benefit of loading Qtopia applications in this way is that much of the functionality that the application needs is pre-loaded and pre-initialised, so the application loading time is significantly reduced. Quicklauncher-enabled applications can be run on older Qtopia platforms by first installing the quicklauncher package.

In order to build an application as a quicklauncher application plugin, main.cpp must be implemented as above. Then modify the tmake project file to build the application as a library and compile with the plugin interface code enabled by defining QTOPIA_APP_INTERFACE), for example:

TEMPLATE = lib
CONFIG  += qtopia
DEFINES += QTOPIA_APP_INTERFACE
HEADERS  = mymainwindow.h
SOURCES  = mymainwindow.cpp main.cpp
TARGET   = myapp

Application plugins must be installed in QPEDIR/plugins/application/.

When building an application as a quicklauncher application plugin it is important to be careful of symbol collisions. Because the application is compiled as a plugin to be loaded, it is possible for symbols used in the application to collide with those of the libraries.

For example, if there are two classes of the same name, one in the application and one in the library the application links to. It is possible that when such an application runs as a quicklauncher application the wrong destructor for the class will be called. This can in turn lead to memory corruption.

The script $QPEDIR/scripts/checksymbols has been provide in order to help in identifying possible symbol conflicts. Make sure QPEDIR is defined and run the script, passing the .so file created for your application as the argument. The script will list possible symbol collision between your application and the Qtopia libraries.


Copyright © 2001-2002 TrolltechTrademarks
Qtopia version 1.7.1