QtopiaServerApplication Class Reference
[QtBaseModule]

Singleton pattern

Usually each call to qtopiaWidget() returns a new server widget instance. In some cases this behaviour is not desired. If it is necessary to return a reference to an already existing instance of a server widget Qt's meta system class info should be used to mark an abstract server widget as singleton. This means that every concrete implementation of this abstract widget will follow the singleton pattern. The SingletonServerWidget string is reserved to enable this feature. If the class info tag is missing Qt Extended assumes that the class does not follow the singleton pattern.

For example:

      //qabstracthomescreen.h
      class QAbstractHomeScreen : public QWidget
      {
         QOBJECT
         Q_CLASSINFO("SingletonServerWidget", "true");
         // ...
      };

The following code segment demonstrates the difference:

      QAbstractHomeScreen* ref1 = qtopiaWidget<QAbstractHomeScreen>();
      QAbstractHomeScreen* ref2 = qtopiaWidget<QAbstractHomeScreen>();

      if ( ref1 == ref2 ) {
          ...
          //The SingletonServerWidget class info is set to true for
          //QAbstractHomeScreen (as seen in above example).
      } else {
          ...
          //The SingletonServerWidget class info is set to false
          //or not defined at all.";
      }

A tutorial on how to develop new server widgets can be found in the QAbstractServerInterface class documentation and the Device Integration guide.

Member Type Documentation

enum QtopiaServerApplication::ShutdownType

enum QtopiaServerApplication::StartupType

This enum determines how tasks are started when QtopiaServerApplication::startup() is called.

Member Function Documentation

void QtopiaServerApplication::addAggregateObject ( QObject * me, QObject * them )   [static]

Add an object them to me to create an "aggregate" task. Aggregate tasks are designed to work around the limitations in Qt's support for multiple interface inheritance by allowing multiple objects to be "stuck together" to form a single object from the task system's perspective.

For example, consider the following interfaces:

    class ApplicationTypeLauncher : public QObject {};
    QTOPIA_TASK_INTERFACE(ApplicationTypeLauncher);
    class SystemShutdownHandler : public QObject {};
    QTOPIA_TASK_INTERFACE(SystemShutdownHandler);

Using direct inheritance a single task could not implement both interfaces. Instead, a task can create one object that implements the ApplicationTypeLauncher interface and one that implements the SystemShutdownHandler interface and aggregate them together.

    class MyLauncherShutdown : public SystemShutdownHandler
    {
    public:
        MyLauncherShutdown(MyLauncherType *);
    };

    class MyLauncherType : public ApplicationTypeLauncher
    {
    public:
        MyLauncherType()
        {
            MyLauncherShutdown *s = new MyLauncherShutdown(this);
            QtopiaServerApplication::addAggregateObject(this, s);
        }
    };
    QTOPIA_TASK(MyLauncherType, MyLauncherType);
    QTOPIA_TASK_PROVIDES(MyLauncherType, ApplicationTypeLauncher);
    QTOPIA_TASK_PROVIDES(MyLauncherType, SystemShutdownHandler);

When the system attempts to cast a task to a particular interface, it first tries the task object itself, and then each of the aggregate objects for that task.

int & QtopiaServerApplication::argc ()   [static]

Returns the argc reference passed to startup().

char ** QtopiaServerApplication::argv ()   [static]

Returns the argv reference passed to startup().

void QtopiaServerApplication::excludeFromTaskCleanup ( QObject * task, bool exclude )   [static]

During the server shutdown all object based server tasks are deleted. However some tasks may not require such management as they install themselves into some form of backend functionality which may take care of the tasks life time. Setting exclude to true excludes task from the task system's memory management.

An example is the QtopiaPowerManager and its sub class which installs itself as the screensaver. The QWS server owns the screen saver object and therefore takes already care of the objects life time.

void QtopiaServerApplication::installQWSEventFilter ( QWSEventFilter * filter )

Install the filter for QWS events. Installing an event filter is equivalent to deriving from QtopiaApplication directly and overriding the QtopiaApplication::qwsEventFilter() method.

Multiple QWS event filters may be installed simultaneously. In this case, each event filter is queried sequentially in the order it was installed. If any filter filters the event, subsequent filters will not be called.

QtopiaServerApplication * QtopiaServerApplication::instance ()   [static]

Return the instantiated QtopiaServerApplication instance. An instance of the class must have been constructed prior to calling this method.

QObject * QtopiaServerApplication::qtopiaTask ( const QByteArray & taskName, bool onlyRunning = false )   [static]

Return the task with name taskName. If onlyRunning is true, the task will be returned only if it has already been instantiated, otherwise it will be instantiated and returned.

void QtopiaServerApplication::removeQWSEventFilter ( QWSEventFilter * filter )

Remove all instances of filter from the list of event filters. This method should be called when an event filter is destroyed. No automatic cleanup is performed.

void QtopiaServerApplication::shutdown ( QtopiaServerApplication::ShutdownType type )   [slot]

Initiates a system shutdown of the specified type.

void QtopiaServerApplication::shutdownRequested ()   [signal]

Emitted whenever the user or an application requests that the system shutdown. A system shutdown is requested by sending a shutdown() message to the QPE/System QCop channel.

Generally a UI will be connected to the shutdownRequested() signal to ask the user what they want to do. This UI should then invoke the shutdown() method to perform the appropriate action.

ShutdownType QtopiaServerApplication::shutdownType ()   [static]

Returns the type of shutdown previously requested by calling shutdown(), or NoShutdown if no shutdown has been requested.

bool QtopiaServerApplication::startup ( int & argc, char ** argv, const QList<QByteArray> & startupGroups, QtopiaServerApplication::StartupType type = QtopiaServerApplication::ImmediateStartup )   [static]

Launches server tasks. This method is used to start the Qt Extended server and should never be called from other code. Returns true on success, false on failure.

argc and argv should be the values passed to the main() function. startupGroups contains a list of Task groups to start. type determines the behavior for launching the tasks.

QString QtopiaServerApplication::taskConfigFile ()   [static]

Returns the task system's configuration file.

QByteArray QtopiaServerApplication::taskValueSpaceObject ( const QByteArray & taskName )   [static]

Returns the path to an object in the value space that the task taskName can use to store status information. Will return a null byte array if the value space has not been initialized. This method is for task implementors only.

bool QtopiaServerApplication::taskValueSpaceSetAttribute ( const QByteArray & taskName, const QByteArray & attribute, const QVariant & value )   [static]

Sets a value space attribute for task taskName to value. This is a convenience method to simplify the usage of the value space for a task. For more complex usage, tasks should use the taskValueSpaceObject() to request a path, and manually create a QValueSpaceObject for their own use. Returns true upon success; otherwise returns false.

The value remains in the value space until the task is unloaded.

Related Non-Members

T * qtopiaTask ( bool onlyActive = false )

Return a task instance that supports the T interface. If onlyActive is true the system will only select from tasks that are already active. Otherwise, if needed, the system will instantiate tasks to satisfy the request.

QList<T *> qtopiaTasks ( bool onlyActive = false )

Returns all task instances that support the T interface. The instances are in the intended instantiation order. If onlyActive is true the system will only select from tasks that are already active. Otherwise, if needed, the system will instantiate tasks to satisfy the request.

T * qtopiaWidget ( QWidget * parent, Qt::WFlags flags )

Returns a concrete implementation of T, with the specified parent and flags. Concrete implementations are provided with the QTOPIA_REPLACE_WIDGET(), QTOPIA_REPLACE_WIDGET_WHEN() and QTOPIA_REPLACE_WIDGET_OVERRIDE() macros and selected as described in the Qt Extended Server Widgets overview.

Each call to this function returns a new instance of the requested server widget unless the server widget has been marked as singleton widget via

    Q_CLASSINFO("SingletonServerWidget", "true");

Macro Documentation

QTOPIA_DEMAND_TASK ( TaskName, Object )

Mark the Object as task TaskName. Only QObject derived types may be tasks. QTOPIA_DEMAND_TASK() differs from QTOPIA_TASK() in that tasks installed using this macro are automatically marked as "demand" tasks, unless specifically overridden in the Tasks.cfg file. That is, tasks installed like this will only be instantiated on request, not during server startup.

As the QTOPIA_DEMAND_TASK() macro defines symbols, it should appear only in the implementation file of a task, and not in the header file.

QTOPIA_REPLACE_WIDGET ( AbstractWidget, ConcreteWidget )

Mark ConcreteWidget as a replacement for AbstractWidget. While AbstractWidget does not actually have to be abstract, it is generally an interface that ConcreteWidget implements. This macro should appear as part of the definition of ConcreteWidget.

For example,

    // wheelbrowserscreen.h
    class WheelBrowserScreen : public QAbstractBrowserScreen
    {
        // ...
    };

    // wheelbrowserscreen.cpp
    QTOPIA_REPLACE_WIDGET(QAbstractBrowserScreen, WheelBrowserScreen);

QTOPIA_REPLACE_WIDGET_OVERRIDE ( AbstractWidget, ConcreteWidget )

Set ConcreteWidget as the static replacement for AbstractWidget.

While as efficient as possible, use of the widget replacement system instead of explicitly instantiating concrete classes does introduce some indirection costs. For shipping software where this flexibility is not necessary, QTOPIA_REPLACE_WIDGET_OVERRIDE() can be used to force the selection of a specified ConcreteWidget. This eliminates the cost of the widget replacement system for the particular AbstractWidget by bypassing the replacement system. The macro should appear inline with the AbstractWidget declaration, and must have visibility of the ConcreteWidget's declaration.

For example,

    // qabstractbrowserscreen.h
    class QAbstractBrowserScreen : public QWidget
    {
        // ...
    };

    #include "wheelbrowserscreen.h"
    QTOPIA_REPLACE_WIDGET_OVERRIDE(QAbstractBrowserScreen, WheelBrowserScreen);

Note that any server widget that uses this marco will not work with singleton server widgets. Calling qtopiaWidget() on such widgets will always return a new instance.

QTOPIA_REPLACE_WIDGET_WHEN ( AbstractWidget, ConcreteWidget, Feature )

Mark ConcreteWidget as a replacement for AbstractWidget. While AbstractWidget does not actually have to be abstract, it is generally an interface that ConcreteWidget implements. This macro should appear as part of the definition of ConcreteWidget.

Unless explicitly specified in the Trolltech/ServerWidgets file, a widget specified in this fashion if Feature is currently provided by Qtopia, as returned by the QtopiaFeatures::hasFeature() method.

For example,

    // touchscreendialer.h
    class TouchscreenDialerScreen : public QAbstractDialerScreen
    {
        // ...
    };

    // touchscreendialer.cpp
    QTOPIA_REPLACE_WIDGET_WHEN(QAbstractDialerScreen, TouchscreenDialerScreen, Touchscreen);

QTOPIA_STATIC_TASK ( TaskName, Function )

Install a functional task. A functional task is one that does not consist of an instantiable object, but is, instead, a simple function. Static tasks can obviously not provide interfaces.

TaskName should be set to the name of the task, and Function to the static function to call to run the task.

As the QTOPIA_STATIC_TASK() macro defines symbols, it should appear only in the implementation file of a task, and not in the header file.

QTOPIA_TASK ( TaskName, Object )

Mark the Object as task TaskName. Only QObject derived types may be tasks.

As the QTOPIA_TASK() macro defines symbols, it should appear only in the implementation file of a task, and not in the header file.

QTOPIA_TASK_INTERFACE ( ClassName )

Mark the specified QObject-derived ClassName as a task interface. Any class interface that is required to support the qtopiaTask<>() or qtopiaTasks<>() request mechanism must be marked as a task interface.

The QTOPIA_TASK_INTERFACE() macro must be used in a header file, immediately following the interface's declaration.

If the interface is not a QObject type, but rather a Qt Q_INTERFACE() style interface, use the QTOPIA_TASK_QINTERFACE() macro instead.

QTOPIA_TASK_PROVIDES ( TaskName, Interface )

Indicate that the task TaskName provides Interface, as previously declared by QTOPIA_TASK_INTERFACE. A task can provide more than one interface.

For a task to support the interface, it must either inherit directly from the interface or aggregate itself with an object that does during its construction. The QtopiaServerApplication::addAggregateObject() method can be used to aggregate a task with another object.

QTOPIA_TASK_QINTERFACE ( InterfaceName )

Mark the specified InterfaceName as a task interface. Any class interface that is required to support the qtopiaTask<>() or qtopiaTasks<>() request mechanism must be marked as a task interface.

The QTOPIA_TASK_!INTERFACE() macro must be used in a header file, immediately following the interface's declaration.

InterfaceName should be a Qt Q_INTERFACE style interface. If you want to use a QObject derived type as an interface, use the QTOPIA_TASK_INTERFACE() macro instead.