QtopiaApplication Class Reference
[QtBaseModule]

Detailed Description

The QtopiaApplication class implements the system services available to all Qt Extended applications.

By using QtopiaApplication instead of QApplication, a standard Qt application becomes a Qt Extended application. It automatically follows style changes, quits and raises, and in the case of document-oriented applications, changes the currently displayed document in response to the environment.

The QtopiaApplication class also controls the life cycle of a Qt Extended application. Applications are automatically started by Qt Extended when a QCop message or service request is sent to their application channel. The QCop application channel is an implicit, application specific channel of the form QPE/Application/<application name>.

Conceptually a Qt Extended application will continue running as long as it has work to do. Concretely, it will not terminate so long as;

There are subsequent QCop messages or service requests to process, The application has visible UI, or The application has running "tasks"

Visible UI is defined as top level widgets that are not QWidget::isHidden() hidden, although they may be obscured by other windows. Most UI-centric applications can rely on the visible UI rule to implicitly indicate to QtopiaApplication that there is still "work to do", and thus correctly manage their execution. As the user explores the application, new windows (or widgets in the case of an application that utilizes QStackedWidget) are created and when they back out, each window is closed until none remain and the application terminates.

Conversely, tasks are used by an application to explicitly communicate to QtopiaApplication that there is still work to do. Tasks are used by applications that need to continue to run even if they are displaying no UI. System daemons or background applications that respond to service requests but otherwise display no UI, are obvious cases, but even traditionally UI-centric applications may need to continue after the user has "closed" them to complete, for example, transmitting a file or saving state. Applications may register and unregister tasks at any time by calling the registerRunningTask() and unregisterRunningTask() methods.

There are two optimizations to the conceptual life cycle model. To improve system performance, Qt Extended supports preloaded applications and a special termination mode known as lazy application shutdown. Preloaded applications are automatically launched at system startup and remain running. The applications are never shutdown, only hidden. Applications may be marked as preloaded by adding their name to the AppLoading\PreloadApps list in the Trolltech/Launcher configuration file. For example, the following would preload the addressbook and qtmail applications.

    [AppLoading]
    PreloadApps=addressbook,qtmail

Lazy application shutdown is a similar, system-wide optimization. When enabled, applications will continue running in a hidden state even if they have no work to do until they are explicitly shutdown by the Qt Extended system server when the system becomes too loaded, or too many such applications are superfluously running. While preloaded applications allow a system configurator to improve performance of a preselected few applications, the rationale behind lazy application shutdown is to allow the system to dynamically tune itself to improve performance of the most frequently run applications. For example, if the user constantly switched between the addressbook and todo applications, these would remain in the lazy shutdown state which would improve the startup time of subsequent "launches". To enable lazy application shutdown, set the AppLoading/LazyShutdown key in the Trolltech/Launcher configuration file to true. For example,

    [AppLoading]
    LazyShutdown=true

For information on creating a new application to run within Qtopia, see Creating a New Application.

Member Type Documentation

enum QtopiaApplication::InputMethodHint

By default, QLineEdit and QTextEdit have the Words hint unless they have a QIntValidator, in which case they have the Number hint. This is appropriate for most cases, including the input of names (new names are added to the user's dictionary by switching to text mode and entering them as usual). All other widgets default to Normal mode.

See also inputMethodHint() and setInputMethodHint().

enum QtopiaApplication::PowerConstraint

Less severe PowerConstraints always imply more severe constraints (e.g DisableLightOff implies DisableSuspend). The exact implications are determined by the integer value that each constraint is assigned to (enumeration value). A low valued constraint will always imply a high valued constraint.

PowerConstraints only take effect when the application is visible, with the exception of DisableSuspend, which takes effect regardless of the visibility state of the application.

See also setPowerConstraint().

enum QtopiaApplication::StylusMode

See also setStylusOperation() and stylusOperation().

enum QtopiaApplication::SxeAuthorizerRole

Specifies whether to create SXE Authorizer resources in this Qt Extended Application.

Member Function Documentation

QtopiaApplication::QtopiaApplication ( int & argc, char ** argv )

Constructs a QtopiaApplication just as you would construct a QApplication, passing argc and argv.

QtopiaApplication::~QtopiaApplication ()

Destroys the QtopiaApplication.

void QtopiaApplication::appMessage ( const QString & msg, const QByteArray & data )   [signal]

This signal is emitted when a message is received on the application's QPE/Application/appname Qtopia channel.

The slot to which you connect uses msg and data as follows:

    void MyWidget::receive( const QString& msg, const QByteArray& data )
    {
        QDataStream stream( data );
        if ( msg == "someMessage(int,int,int)" ) {
            int a,b,c;
            stream >> a >> b >> c;
            ...
        } else if ( msg == "otherMessage(QString)" ) {
            ...
        }
    }

void QtopiaApplication::categoriesChanged ()   [signal]

This signal is emitted whenever a category is added, removed or edited.

See also QCategoryManager.

void QtopiaApplication::clockChanged ( bool ampm )   [signal]

This signal is emitted when the clock style is changed. If ampm is true, the clock style is a 12-hour AM/PM clock, otherwise it is a 24-hour clock.

Warning: When using the QTimeString functions all strings obtained by QTimeString should be updated to reflect the changes.

See also dateFormatChanged().

void QtopiaApplication::contentChanged ( const QContentIdList & ids, QContent::ChangeType type )   [signal]

This signal is emitted whenever one or more QContent is stored, removed or edited. ids contains the list of Id's of the content that is being modified. type contains the type of change.

See also Document System.

void QtopiaApplication::dateFormatChanged ()   [signal]

This signal is emitted whenever the date format is changed.

Warning: When using QTimeString functions, all QTimeString strings should be updated to reflect the changes.

See also clockChanged().

int QtopiaApplication::exec ()

Enters the main event loop and waits until exit() is called.

See also QApplication::exec().

int QtopiaApplication::execDialog ( QDialog * dialog, bool noMaximize = false )   [static]

Shows and calls exec() on the dialog. A heuristic approach is taken to determine the size of the dialog and whether it is maximized.

The function returns a QDialog::DialogCode result.

If noMaximize is true then the dialog may not be maximized. This is usually unnecessary and it is recommended that the system be allowed to decide how the dialog is displayed by passing false for noMaximize.

See also showDialog() and QDialog::exec().

void QtopiaApplication::hideInputMethod ()   [static]

Explicitly hide the current input method.

The current input method is still indicated in the title, but no longer takes up screen space, and can no longer be interacted with.

This function only applies to input methods that have a visible input window, such as a virtual keyboard.

See also showInputMethod().

InputMethodHint QtopiaApplication::inputMethodHint ( QWidget * widget )   [static]

Returns the currently set Input Method hint for widget.

Returns QtopiaApplication::Normal if no hint has been set.

See also setInputMethodHint() and InputMethodHint.

QString QtopiaApplication::inputMethodHintParam ( QWidget * widget )   [static]

Returns the currently set hint parameter for widget with Named input method hint.

See also setInputMethodHint() and InputMethodHint.

QtopiaApplication * QtopiaApplication::instance ()   [static]

Returns a pointer to the application's QtopiaApplication instance.

bool QtopiaApplication::isMenuLike ( const QDialog * dialog )   [static]

Returns true if the dialog is set to have MenuLike behaviour when executed; otherwise returns false.

See also setMenuLike().

void QtopiaApplication::loadTranslations ( const QString & qms )   [static]

Loads the translation file specified by qms. qms can be the name of a library or application.

void QtopiaApplication::loadTranslations ( const QStringList & qms )   [static]

This is an overloaded member function, provided for convenience.

It behaves essentially like the above function.

It is the same as calling loadTranslations(QString) for each entry of qms.

QWidget * QtopiaApplication::mainWidget () const

Returns the main widget of this application.

See also setMainWidget().

void QtopiaApplication::registerRunningTask ( const QString & name, QObject * taskObj = 0 )

Register the task name as running. If taskObj is supplied, the task will be automatically unregistered when taskObj is destroyed. Tasks may be manually unregistered by calling unregisterRunningTask(). For a broader discussion of tasks, please refer to the QtopiaApplication overview documentation.

It is not possible to register two tasks with the same name simultaneously. The last registration with name will replace the previous registration.

Certain task names are reserved for use by the system and should not be used directly by application programmers. The following table describes the list of reserved task names.

void QtopiaApplication::resetContent ()   [signal]

This signal is emitted whenever a new media database is attached, or the system needs to reset QContentSet instances to refresh their list of items.

See also Document System.

void QtopiaApplication::setInputMethodHint ( QWidget * widget, InputMethodHint mode, const QString & param = QString() )   [static]

Hints to the system that widget has use for text input methods as specified by mode. If mode is Named, then param specifies the name.

See also inputMethodHint() and InputMethodHint.

void QtopiaApplication::setInputMethodHint ( QWidget * widget, const QString & named )   [static]

This is an overloaded member function, provided for convenience.

Provides a hint to the system that widget has use for the text input method specified by named. Such methods are input-method-specific and are defined by the files in [qt_prefix]/etc/im/ for each input method.

For example, the phone-keys input method includes support for the named input methods:

• email
• netmask
• url

The effect in the phone key input method is to modify the binding of phone keys to characters (such as making "@" easier to input), and to add additional words to the recognition word lists, such as: www.

Note: If the current input method doesn't understand the hint, it will be ignored.

In addition, Qt Extended supports auxiliary hints. These modify the hint without overriding it, and are appended to the hint, separated by whitespace.

For example, the phone-keys input method includes support for the following auxiliary hints:

Specific input methods may ignore these auxiliary hints, or only handle some of them. Like all hints, if the input method does not understand the hint, it will ignore it.

See also inputMethodHint() and InputMethodHint.

void QtopiaApplication::setMainWidget ( QWidget * widget, bool noMaximize = false )

Set the main widget for this application to widget. If noMaximize is true, then the widget will not be maximized.

See also mainWidget().

void QtopiaApplication::setMenuLike ( QDialog * dialog, bool menuLike )   [static]

In some cases dialogs are easier to interact with if they behave in a similar fashion to menus.

The default dialog behaviour is to include a cancel menu option in the context menu in order to reject the dialog and map Key_Back to accept the dialog.

Setting menuLike to true instructs the dialog to have MenuLike behaviour when executed.

A MenuLike dialog will map Key_Back key to reject the dialog and will not map any key to accept the dialog - the accept action must be implemented by the developer.

MenuLike dialogs typically have a single list of options, and accept the dialog when the select key is pressed on the appropriate item, or when a mouse/stylus is used to click on an item. Key focus should be accepted by only one widget.

See also isMenuLike().

void QtopiaApplication::setPowerConstraint ( PowerConstraint constraint )   [static]

This method temporarily overrides the current global power manager with the PowerConstraint constraint, allowing applications to control power saving functions during their execution.

Calling this function will access Qt Extended power management via the QtopiaPowerManagerService.

See also PowerConstraint.

void QtopiaApplication::setStylusOperation ( QWidget * widget, StylusMode mode )   [static]

Allows widget to receive mouse events according to the stylus mode.

Setting the stylus mode to RightOnHold causes right mouse button events to be generated when the stylus is held pressed for 500ms. The default mode is LeftOnly.

See also stylusOperation() and StylusMode.

void QtopiaApplication::setSxeAuthorizerRole ( SxeAuthorizerRole role )

Sets this applications QtopiaApplication::SxeAuthorizerRole to role. In general this should not be required for all but a few applications such as the mediaserver, and other applications which must authorize requests using SXE; since the default value of SxeAuthorizerClientOnly will be correct.

The qpe server (actually any app for which type() is GuiServer) will default to SxeAuthorizerServerOnly.

See also sxeAuthorizerRole() and QtopiaApplication::SxeAuthorizerRole.

void QtopiaApplication::showDialog ( QDialog * dialog, bool noMaximize = false )   [static]

Shows dialog. A heuristic approach is taken to determine the size of the dialog and whether it is maximized.

If noMaximize is true then the dialog may not be maximized. This is usually unnecessary and it is recommended that the system be allowed to decide how the dialog is displayed by passing false for noMaximize.

See also execDialog().

void QtopiaApplication::showInputMethod ()   [static]

Explicitly show the current input method.

Input methods are indicated in the title by a small icon. If the input method is activated (shown) and it has a visible input window (such as a virtual keyboard) then it takes up some proportion of the bottom of the screen, to allow the user to interact.

See also hideInputMethod().

void QtopiaApplication::showMainDocumentWidget ()

Show the main widget for this application and ask it to load the document specified on the command-line.

This call assumes that the application is a document-oriented application. The main widget must implement a setDocument(const QString &filename) slot in order to receive the filename of the document to load.

See also showMainWidget().

void QtopiaApplication::showMainDocumentWidget ( QWidget * widget, bool noMaximize = false )

This is an overloaded member function, provided for convenience.

Sets widget widget as the mainWidget() and shows it.

If noMaximize is true then the main widget may not be maximized. This is usually unnecessary and it is recommended that the system is allowed to decide how the widget is displayed by passing false for noMaximize.

This call assumes that the application is a document-oriented application. The main widget must implement a setDocument(const QString &filename) slot in order to receive the filename of the document to load.

See also showMainWidget().

void QtopiaApplication::showMainWidget ()

Show the main widget for this application.

See also showMainDocumentWidget().

void QtopiaApplication::showMainWidget ( QWidget * widget, bool noMaximize = false )

This is an overloaded member function, provided for convenience.

Sets widget as the mainWidget() and shows it.

If noMaximize is true then the main widget may not be maximized. This is usually unnecessary and it is recommended that the system is allowed to decide how the widget is displayed by passing false for noMaximize.

See also showMainDocumentWidget().

StylusMode QtopiaApplication::stylusOperation ( QWidget * w )   [static]

Returns the current StylusMode for widget w.

See also setStylusOperation() and StylusMode.

SxeAuthorizerRole QtopiaApplication::sxeAuthorizerRole () const

Returns this applications QtopiaApplication::SxeAuthorizerRole. In general this will be SxeAuthorizerClientOnly for all but a few applications such as the qpe server, mediaserver, and other applications which must authorize requests using SXE.

See also setSxeAuthorizerRole() and QtopiaApplication::SxeAuthorizerRole.

void QtopiaApplication::timeChanged ()   [signal]

This signal is emitted when the time changes outside the normal passage of time, that is, if the time is set backwards or forwards.

If the application offers the TimeMonitor service, it will get the QCop message that causes this signal even if it is not running, thus allowing it to update any alarms or other time-related records.

void QtopiaApplication::unregisterRunningTask ( const QString & name )

Unregister the task name previously registered with registerRunningTask(). Attempting to unregister a task that has not been registered has no effect.

void QtopiaApplication::unregisterRunningTask ( QObject * taskObj )

This is an overloaded member function, provided for convenience.

Unregister the task taskObj previously registered with registerRunningTask(). Attempting to unregister a task that has not been registered has no effect.

void QtopiaApplication::volumeChanged ( bool muted )   [signal]

This function is deprecated.

Track the value space item /System/Volume instead.

This signal is emitted if the system volume changes. If muted is true, the system volume is muted, otherwise it is not.

void QtopiaApplication::weekChanged ( bool startOnMonday )   [signal]

This signal is emitted if the week start day is changed. If startOnMonday is true then the first day of the week is Monday otherwise the first day of the week is Sunday.

bool QtopiaApplication::willKeepRunning () const

Returns true if this application will keep running because there are visible widgets or registered tasks; otherwise returns false.

Macro Documentation

QTOPIA_ADD_APPLICATION ( name, classname )

This macro registers the application uniquely identified by name with the main widget classname. This macro is used to simplify switching between quicklaunch and normal launching.

In singleexec builds, this macro is used to indicate the name of the main function rather than specifying the class to instantiate.

See also Applications.

QTOPIA_APP_KEY

This macro is used by the QTOPIA_MAIN macro to allocate space for the SXE key. It's set to either QSXE_APP_KEY or QSXE_QL_APP_KEY depending on if you're building a quicklaunch plugin or a standalone app.

See also Applications and QTOPIA_SET_KEY().

QTOPIA_DIRECT_DOCUMENT_SYSTEM_CONNECTION

This macro should be set to specify that the app needs a direct connection to the document system. Note that enabling this define will mean extra security priviliges are required. If you are not using the QTOPIA_MAIN macros you should ensure that QTOPIA_SET_DOCUMENT_SYSTEM_CONNECTION() is being called or this macro will have no effect.

See also Applications and QContent::setDocumentSystemConnection().

QTOPIA_EXPORT_PLUGIN ( classname )

This macro causes a QObject-derived classname to be made available from a plugin file (eg foo.so). This macro should be used instead of Q_EXPORT_PLUGIN because it works correctly in both dynamic and singleexec builds.

Note that this function is for Qt Extended plugins. For Qt plugins you should use QTOPIA_EXPORT_QT_PLUGIN().

QTOPIA_EXPORT_QT_PLUGIN ( classname )

This macro causes a QObject-derived classname to be made available from a plugin file (eg foo.so). This macro should be used instead of Q_EXPORT_PLUGIN because it works correctly in both dynamic and singleexec builds.

Note that this function is for Qt plugins. For Qt Extended plugins you should use QTOPIA_EXPORT_PLUGIN().

QTOPIA_MAIN

This macro inserts an appropriate main function when normal launching is used.

See also Applications.

QTOPIA_SET_DOCUMENT_SYSTEM_CONNECTION ()

This macro is used by the QTOPIA_MAIN macro to set the default document system connection type. If you are implementing a main() function you should call this after constructing QtopiaApplication. Failure to call this macro is not fatal but you will be unable to influence the default connection type.

The QTOPIA_DIRECT_DOCUMENT_SYSTEM_CONNECTION macro affects the implementation of this function.

See also Applications and QContent::setDocumentSystemConnection().

QTOPIA_SET_KEY ( name )

This macro is used by the QTOPIA_MAIN macro to copy the SXE key into memory. It's set to either QSXE_SET_APP_KEY() or QSXE_SET_QL_KEY() (passing along name) depending on if you're building a quicklaunch plugin or a standalone app.

See also Applications and QTOPIA_APP_KEY.