| Classes | Functions | DevRef | Qt API | Qtopia Documentation |

# QPEApplication Class Reference

The QPEApplication class implements various system services that are available to all Qtopia applications. More...

`#include <qpeapplication.h>`

List of all member functions.

## Public Members

- QPEApplication ( int & argc, char ** argv, Type t = GuiClient )
- ~QPEApplication ()
- enum StylusMode { LeftOnly, RightOnHold }
- enum InputMethodHint { Normal, AlwaysOff, AlwaysOn }
- enum screenSaverHint { Disable = 0, DisableLightOff = 1, DisableSuspend = 2, Enable = 100 }
- void showMainWidget ( QWidget * mw, bool nomaximize = FALSE )
- void showMainDocumentWidget ( QWidget * mw, bool nomaximize = FALSE )
- bool keepRunning () const

## Signals

- void timeChanged ()
- void clockChanged ( bool ampm )
- void volumeChanged ( bool muted )
- void appMessage ( const QCString & msg, const QByteArray & data )
- void weekChanged ( bool startOnMonday )
- void dateFormatChanged ( DateFormat )
- void flush ()
- void reload ()

## Static Public Members

- QString qpeDir ()
- QString documentDir ()
- void grabKeyboard ()
- void ungrabKeyboard ()
- void setStylusOperation ( QWidget * w, StylusMode mode )
- StylusMode stylusOperation ( QWidget * w )
- void setInputMethodHint ( QWidget * w, InputMethodHint mode )
- InputMethodHint inputMethodHint ( QWidget * w )
- void setKeepRunning ()

## Detailed Description

The QPEApplication class implements various system services that are available to all Qtopia applications.

Simply by using QPEApplication instead of QApplication, a standard Qt application becomes a Qtopia 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.

To create a document-oriented application use showMainDocumentWidget(); to create a non-document-oriented application use showMainWidget(). The keepRunning() function indicates whether the application will continue running after it's processed the last QCop message. This can be changed using setKeepRunning().

A variety of signals are emitted when certain events occur, for example, timeChanged(), clockChanged(), weekChanged(), dateFormatChanged() and volumeChanged(). If the application receives a QCop message on the application's QPE/Application/appname channel, the appMessage() signal is emitted. There are also flush() and reload() signals, which are emitted when synching begins and ends respectively - upon these signals, the application should save and reload any data files that are involved in synching.

This class also provides a set of useful static functions. The qpeDir() and documentDir() functions return the respective paths. The grabKeyboard() and ungrabKeyboard() functions are used to control whether the application takes control of the device's physical buttons (e.g. application launch keys). The stylus' mode of operation is set with setStylusOperation() and retrieved with stylusOperation(). There are also setInputMethodHint() and inputMethodHint() functions.

## Member Type Documentation

### QPEApplication::InputMethodHint

- `QPEApplication::Normal` - the application sometimes needs text input (the default).
- `QPEApplication::AlwaysOff` - the application never needs text input.
- `QPEApplication::AlwaysOn` - the application always needs text input.

See also inputMethodHint() and setInputMethodHint().

### QPEApplication::StylusMode

- `QPEApplication::LeftOnly` - the stylus only generates LeftButton events (the default).
- `QPEApplication::RightOnHold` - the stylus generates RightButton events if the user uses the press-and-hold gesture.

See also setStylusOperation() and stylusOperation().

### QPEApplication::screenSaverHint

- `QPEApplication::Disable` - the screen should never blank
- `QPEApplication::DisableLightOff` - the screen should never blank and the backlight should never switch off
- `QPEApplication::DisableSuspend` - the screen should blank when the device goes into suspend mode
- `QPEApplication::Enable` - screen blanking and switching off the backlight are both enabled

Currently, this is only used internally.

## Member Function Documentation

### QPEApplication::QPEApplication ( int & argc, char ** argv, Type t = GuiClient )

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

For applications, t should be the default, GuiClient. Only the Qtopia server passes GuiServer.

### QPEApplication::~QPEApplication ()

Destroys the QPEApplication.

### void QPEApplication::appMessage ( const QCString & msg, const QByteArray & data )`[signal]`

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

The slot to which you connect this signal uses msg and data in the following way:

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

### void QPEApplication::clockChanged ( bool ampm )`[signal]`

This signal is emitted when the user changes the clock's style. If ampm is TRUE, the user wants a 12-hour AM/PM clock, otherwise, they want a 24-hour clock.

### QString QPEApplication::documentDir ()`[static]`

Returns the user's current Document directory. There is a trailing "/".

### void QPEApplication::flush ()`[signal]`

###

### void QPEApplication::grabKeyboard ()`[static]`

Grabs the physical keyboard keys, e.g. the application's launching keys. Instead of launching applications when these keys are pressed the signals emitted are sent to this application instead. Some games programs take over the launch keys in this way to make interaction easier.

See also ungrabKeyboard().

### InputMethodHint QPEApplication::inputMethodHint ( QWidget * w )`[static]`

Returns the currently set hint to the system as to whether widget w has any use for text input methods.

See also setInputMethodHint() and InputMethodHint.

### bool QPEApplication::keepRunning () const

Returns TRUE if the application will quit after processing the current list of qcop messages; otherwise returns FALSE.

See also setKeepRunning().

### QString QPEApplication::qpeDir ()`[static]`

Returns `$QPEDIR/`.

### void QPEApplication::reload ()`[signal]`

###

### void QPEApplication::setInputMethodHint ( QWidget * w, InputMethodHint mode )`[static]`

Hints to the system that widget w has use for text input methods as specified by mode.

See also inputMethodHint() and InputMethodHint.

### void QPEApplication::setKeepRunning ()`[static]`

If an application is started via a QCop message, the application will process the QCop message and then quit. If the application calls this function while processing a QCop message, after processing its outstanding QCop messages the application will start 'properly' and show itself.

See also keepRunning().

### void QPEApplication::setStylusOperation ( QWidget * w, StylusMode mode )`[static]`

Causes widget w to receive mouse events according to the stylus mode.

See also stylusOperation() and StylusMode.

### void QPEApplication::showMainDocumentWidget ( QWidget * mw, bool nomaximize = FALSE )

Sets widget mw as the mainWidget() and shows it. For small windows, consider passing TRUE for nomaximize rather than the default FALSE.

This calls designates the application as a document-oriented application.

The mw widget must have this slot: setDocument(const QString&).

See also showMainWidget().

### void QPEApplication::showMainWidget ( QWidget * mw, bool nomaximize = FALSE )

Sets widget mw as the mainWidget() and shows it. For small windows, consider passing TRUE for nomaximize rather than the default FALSE.

See also showMainDocumentWidget().

### StylusMode QPEApplication::stylusOperation ( QWidget * w )`[static]`

Returns the current StylusMode for widget w.

See also setStylusOperation() and StylusMode.

### void QPEApplication::timeChanged ()`[signal]`

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

### void QPEApplication::ungrabKeyboard ()`[static]`

Reverses the effect of grabKeyboard(). This is called automatically on program exit.

### void QPEApplication::volumeChanged ( bool muted )`[signal]`

This signal is emitted whenever the mute state is changed. If muted is TRUE, then sound output has been muted.

### void QPEApplication::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; if startOnMonday is FALSE then the first day of the week is Sunday.

This file is part of the Qtopia , copyright © 1995-2002 Trolltech, all rights reserved.