BuiltinApplicationLauncher Class Reference
[QtBaseModule]

Detailed Description

The BuiltinApplicationLauncher class supports launching simple applications that run inside the Qt Extended Server process.

The BuiltinApplicationLauncher provides a Qt Extended Server Task. Qt Extended Server Tasks are documented in full in the QtopiaServerApplication class documentation.

Note: This class is part of the Qt Extended server and cannot be used by other Qt Extended applications.

The BuiltinApplicationLauncher class provides the ApplicationTypeLauncher implementation for simple applications compiled into the Qt Extended Server - known as builtin applications.

A builtin application must consist of a single, toplevel widget. Generally builtins do not implement services, but they may. If multiple builtins implement the same service, or the Qt Extended Server and a builtin implements the same service, the behaviour is undefined.

Adding a builtin application is a simple case of linking it into the Qt Extended Server, and adding a QTOPIA_SIMPLE_BUILTIN() macro to your code. The QTOPIA_SIMPLE_BUILTIN() macro registers the builtin application with the BuiltinApplicationLauncher class. The macro takes the application name, and a simple static function that "launches" the application and returns a QWidget pointer as paramters.

Note: Builtins may not currently implement services. This functionality is planned for future versions of Qtopia.

Member Type Documentation

typedef BuiltinApplicationLauncher::BuiltinFunc

The BuiltinFunc provides a type definition that the static function used to create a builtin application must conform to. The exact specification is:

    typdef QWidget *(*BuiltinFunc)()

Member Function Documentation

BuiltinApplicationLauncher::BuiltinApplicationLauncher ()

Constructs a new BuiltinApplicationLauncher instance.

BuiltinApplicationLauncher::~BuiltinApplicationLauncher ()   [virtual]

Destroys the BuiltinExeApplicationLauncher instance.

Macro Documentation

QTOPIA_SIMPLE_BUILTIN ( ApplicationName, createFunc )

Add a new builtin application to the server. ApplicationName must be the name of the application and createFunc a static function, of type BuiltinApplicationLauncher::BuiltinFunc, that creates the applications. For example, the following code adds a simple builtin named "TestBuiltin" to the server.

    class TestBuiltinWindow : public QWidget
    {
     // ...
    };
    static QWidget *testBuiltinFunc()
    {
        static QPointer<TestBuiltinWindow> w = 0
        if (!w)
            w = new TestBuiltinWindow(0);

        return w;
    }
    QTOPIA_SIMPLE_BUILTIN(TestBuiltin, testBultinFunc);

If the builtin doesn't return a widget the system assumes that the builtin application provides a background task. Therefore any UI builtin must return the widget.

Also if the function keeps a QWidget pointer it must ensure that the pointer is valid. This is best ensured by wrapping the widget with a QPointer (see above) since the BuiltinApplicationLauncher may delete the widget when it is told to kill the builtin application.