Qtopia Namespace Reference
[QtBaseModule]

Path related

These methods return the authoritative values of run-time paths used by various components of Qtopia.

In general do not use these methods. Instead use the QContent API, or the Qt Extended Resource System. Qt Extended is designed so that searching or scanning the file-system should not be necessary.

When it is necessary to determine locations on the file-system, use homePath() to find the location for user settings, documentDir() for user documents, and helpPaths() to locate all help files.

Use installPaths() to find all possible install paths, for example to locate a binary resource. Use qtopiaDir() for the default location for resources, and packagePath() as the location for third-party resources.

        QStringList paths = Qtopia::installPaths();
        foreach ( QString p, paths )
        {
            QDir qDir( p + "bin" );
            if ( qDir.exists() )
            {
                QFileInfoList binaries = qDir.entryInfoList( QDir::Executable );
                currentCount = ( p == Qtopia::packagePath() ) ? packageCounts : qtopiaCounts;
                foreach ( QFileInfo f, binaries )
                    if ( f.size() > chosenAppSize )
                        ++currentCount[LARGE];
                    else
                        ++currentCount[SMALL];
            }
        }

        info += tr( ", bigger than <font color=\"#CC0000\">%1 percent</font> of Qt Extended binaries" )
            .arg( (int)( (float)qtopiaCounts[SMALL] * 100.0 / (float)qtopiaCounts[LARGE] ));

        if ( packageCounts[SMALL] > 0 || packageCounts[LARGE] > 0 )
        {
            info += tr( ", and bigger than <font color=\"#CC0000\">%1 percent</font> of package binaries" )
                .arg( (int)( (float)packageCounts[SMALL] * 100.0 / (float)packageCounts[LARGE] ));
        }

        return info;

The installPaths() method gives the complete list of paths known to the Qt Extended run-time system. The updateDir(), qtopiaDir() and packagePath() directories are stored as the first, second and last components of this list.

The order of the paths returned by installPaths() and where the path is defined is

• System update path - Storage.conf
• Default resource location - qtopiaDir()
• Qt Extended Path environment variable
• Third-party package location - packagePath()

In fact the paths are determined by compile time configuration options.

See the documentation on building Qt Extended for the -prefix and other relevant options:

• Building and Compiling
• Guide to Configuring and Building Qt Extended

Type Documentation

enum Qtopia::ItemDataRole

Each item in the model has a set of data elements associated with it, each with its own role. The roles are used by the view to indicate to the model which type of data it needs.

Qt Extended adds the following roles:

See also Qt::ItemDataRole.

enum Qtopia::Lockflags

This enum controls what type of locking is performed on a file.

Current defined values are:

Function Documentation

void Qtopia::actionConfirmation ( const QPixmap & pixmap, const QString & text )

Displays a message dialog containing the specified pixmap and text for a short time.

void Qtopia::addAlarm ( QDateTime when, const QString & channel, const QString & message, int data = 0 )

Schedules an alarm to go off at (or soon after) time when. When the alarm goes off, the Qt Extended IPC message will be sent to channel, with data as a parameter.

If channel does not contain the / character, it will be interpreted as a QCop service name. For example, specifying Calendar as channel will direct the alarm to the configured calendar program.

Note that these alarms fire regardless of whether the application that created them is running, indeed for some hardware, even if the device is not powered on.

If this function is called with exactly the same data as a previous call the subsequent call is ignored, so there is only ever one alarm with a given set of parameters.

See also deleteAlarm().

void Qtopia::addWords ( const QStringList & wordlist )

Adds wordlist to the addedDawg(). Words that are already in the "local" list are not added. Words that are in the "deleted" list are removed from that list.

Note that the addition of words persists between program executions (they are saved in the dictionary files), so you should confirm the words with the user before adding them.

This is a slow operation. Call it once with a large list rather than multiple times with a small list.

void Qtopia::addWords ( const QString & dictname, const QStringList & wordlist )

This is an overloaded member function, provided for convenience.

Adds wordlist to the dawg() named dictname.

Note that the addition of words persists between program executions (they are saved in the dictionary files), so you should confirm the words with the user before adding them.

This is a slow operation. Call it once with a large list rather than multiple times with a small list.

const QDawg & Qtopia::addedDawg ()

Returns the changeable QDawg that contains general words for the current locale.

See also fixedDawg(), addWords(), and removeWords().

QString Qtopia::applicationFileName ( const QString & appname, const QString & filename )

Returns the application data path for the application specific data file filename and the application executable named appname.

Application specific data is stored in a separate directory per application.

The application specific directory will be created if if does not exist. It is a requirement that the user has write permissions for Qtopia::homePath().

In the case of a package installed under SXE, then typically that package will not have access to Qtopia::homePath(). Instead the package is sandboxed into an application specific directory given by Qtopia::sandboxDir(). In that case this method returns a path under the sandbox directory.

If filename contains "/", it is the caller's responsibility to ensure that those directories exist.

QString Qtopia::architecture ()

Returns the device architecture string specified by QPE_ARCHITECTURE. This is a sequence of identifiers separated by "/", from most general to most specific (eg. "IBM/PC").

If a value has not been set for QPE_ARCHITECTURE the string "Uncusomized Device" is returned.

bool Qtopia::confirmDelete ( QWidget * parent, const QString & caption, const QString & object )

Shows a dialog with a caption to confirm deletion of the described object with the user. This is a convenience function that makes confirming deletions easier. For example:

    if (Qtopia::confirmDelete(this, tr("Delete Contact"), contact->name()))
        delete contact;

If parent is 0, the dialog becomes an application-global modal dialog box. If parent is a widget, the dialog becomes modal relative to parent.

Returns true if the user agrees to deleting object; otherwise returns false.

See also QMessageBox::warning().

const QDawg & Qtopia::dawg ( const QString & name, const QString & language = QString() )

Returns the QDawg with the given name. This is an application-specific word list.

name should not contain "/". If name starts with "_", it is a read-only system word list.

language allows the specific selection of a dictionary for a particular language. This option applies to read-only system word list only and is ignored otherwise. If no language is given the dictionary of the current language is loaded.

QString Qtopia::dehyphenate ( const QString & s )

Returns the string equivalent to s, but with any soft-hyphens removed.

void Qtopia::deleteAlarm ( QDateTime when, const QString & channel, const QString & message, int data = 0 )

Deletes previously scheduled alarms which match when, channel, message, and data.

Passing null values for when, channel, or for the Qt Extended IPC message, acts as a wildcard meaning "any". Similarly, passing -1 for data indicates "any".

If there is no matching alarm, nothing happens.

See also addAlarm().

QString Qtopia::deviceId ()

Returns a unique ID for this device. The value can change, if for example, the device is reset.

QString Qtopia::documentDir ()

Returns the user's current Document directory, with a trailing "/" included.

QVariant Qtopia::findDisplayFont ( const QString & s )

Finds a font that can be used to display the string s and returns a variant with this font value. If the string cannot be displayed by any of the installed fonts, an invalid variant is returned.

If s is empty, this returns a variant with the default font.

const QDawg & Qtopia::fixedDawg ()

Returns the unchangeable QDawg that contains general words for the current locale.

See also addedDawg().

bool Qtopia::hasKey ( int key )

Returns true if key is available on the device. The buttons may be either fixed function buttons, such as Key_Menu, or user mappable buttons, such as Key_F1.

    if ( Qtopia::hasKey( Qt::Key_Flip ) ) {
        ... // add flip key function
    }

See also Qt::Key, QSoftMenuBar, and QDeviceButtonManager.

QStringList Qtopia::helpPaths ()

Returns a list of directory names where help files are found.

QString Qtopia::homePath ()

Returns the name of the directory to be used as the current users home directory.

See also QDir::homePath().

QStringList Qtopia::installPaths ()

Returns the list of base directories containing Qt Extended software and resources.

Some directories in the list, or their sub-directories, may not be writable.

Internally the second element is equal to [qt_prefix] and additional values are set by the colon-separated environment variable QTOPIA_PATH.

The Qt Extended algorithm for locating resources searches the paths in order so that for example downloaded binaries or resources cannot overwrite system resources.

Note that qtopiaDir(), the default location for resources and binaries is second on this list, and packagePath() is last.

See also qtopiaDir() and packagePath().

bool Qtopia::isDocumentFileName ( const QString & file )

Returns true if file is the file name of a document ie, it resides under the locations described in storage.conf marked with both Documents=true and possibly with an extra document path for the location.

bool Qtopia::isFileLocked ( QFile & f, int flags = -1 )

Tests locking a file. Any locks created should be released before the program exits. Returns true if locking would be successful.

f must be an open file.

flags any combination of LockShare, LockWrite.

See also Qtopia::unlockFile() and Qtopia::lockFile().

bool Qtopia::isWord ( const QString & word )

Returns whether word is in the fixedDawg() or the addedDawg(), but not in dawg("deleted").

QStringList Qtopia::languageList ()

Returns the list of language identifiers for currently selected language. The first string in the list is the identifier for user's primary choice of language. The second string in the list, if any, is more generic language, providing fall-back policy.

For example, "en_US", "en" is returned when American English is used. If there is no translation in "en_US", more generic translation "en" will be used.

See also Internationalization.

bool Qtopia::lockFile ( QFile & f, int flags = -1 )

Lock a file. Any locks created should be released before the program exits. Returns true if successful.

f must be an open file. flags any combination of LockShare, LockWrite, LockBlock.

See also Qtopia::unlockFile() and Qtopia::isFileLocked().

bool Qtopia::mousePreferred ()

Returns true if keypad navigation is disabled and the application can expect the user to be able to easily produce mouse events.

Returns false if keypad navigation is enabled and the user cannot produce mouse events, or chooses not to (eg. does not plug in a mouse).

Applications may use this to tune interactions.

Note that you should only call this function after an instance of QtopiaApplication has been created. This function will return an undefined value if called prior to this.

See also QApplication::keypadNavigationEnabled().

void Qtopia::msleep ( unsigned long msecs )

Suspends the current process for msecs milliseconds.

Note that this function should be avoided where possible as it will freeze the user interface. Use of QTimer and QObject::startTimer() allow for delayed processing without freezing the user interface at the cost of being unable to trigger accurately.

See also QThread::msleep().

QString Qtopia::ownerName ()

Returns the name of the owner of the device.

QString Qtopia::packagePath ()

Returns the base directory in which downloaded 3rd party packages, including their binaries and resources, are located.

This is returned as the last item in the installPaths() list.

The value of packagePath() is determined by the [Packages] group in the Storage.conf file.

The directory must be writable, and is used by the Software Installer for installation of downloaded software.

See also installPaths().

QString Qtopia::qtopiaDir ()

Returns the base directory in which Qt Extended system binaries and resources are located.

This is the default location for all Qt Extended configuration and other data.

This directory may not be writable.

This is the second item in the installPaths() list.

See also updateDir() and installPaths().

void Qtopia::qtopiaReloadWords ( const QString & dictname )

Reloads the QDawg named called dictname. This must be called if the underlying dawg files are changed, otherwise previous versions will be used.

Not normally used.

See also dawg().

void Qtopia::removeWords ( const QStringList & wordlist )

Removes wordlist from the addedDawg(). If the words are in the fixed dictionary, they are added to the "deleted" dictionary.

This is a slow operation. Call it once with a large list rather than multiple times with a small list.

void Qtopia::removeWords ( const QString & dictname, const QStringList & wordlist )

This is an overloaded member function, provided for convenience.

Removes wordlist from the dawg() named dictname.

This is a slow operation. Call it once with a large list rather than multiple times with a small list.

QString Qtopia::sandboxDir ()

Find the full path to the directory into which the current process is sandboxed under SXE. The current process will have full read and write permissions in this directory.

This diagram shows a typical layout for the sandbox resulting from an SXE package install.

In this case the result returned by sandboxDir() would be

    /opt/Qtopia.user/packages/a5b25e67a57f14de56

If SXE is disabled, this function returns the empty string

void Qtopia::setWeekStartsOnMonday ( bool v )

Sets the day the user regards their week starting on. If v is true, then the week begins on Monday. If v is false, then the week begins on Sunday.

See also weekStartsOnMonday().

QString Qtopia::shellQuote ( const QString & s )

Returns the string s with the characters '', '"', and '$' quoted by a preceding '', and enclosed by double-quotes (").

See also stringQuote().

QString Qtopia::simplifyMultiLineSpace ( const QString & multiLine )

Returns the result of using QString::simplified() on multiLine, but with line breaks preserved.

void Qtopia::sleep ( unsigned long secs )

Suspends the current process for secs seconds.

Note that this function should be avoided where possible as it will freeze the user interface. Use of QTimer and QObject::startTimer() allow for delayed processing without freezing the user interface at the cost of being unable to trigger accurately.

See also QThread::sleep().

void Qtopia::soundAlarm ()

Sounds the audible system alarm. This is used for applications such as Calendar when it needs to inform the user of an event.

This call is equivalent to:

    QtopiaServiceRequest e( "Alert", "soundAlert" );
    e.send();

See also AlertService.

QString Qtopia::stringQuote ( const QString & s )

Returns the string s with the characters '' and '"' quoted by a preceding ''.

See also shellQuote().

QString Qtopia::tempDir ()

Returns the default system path for storing temporary files. The path is unique to the display to which the application is connected. The path has a trailing directory separator character.

The returned directory is created if it does not exist.

See also QDir::tempPath().

QString Qtopia::tempName ( const QString & fname )

Returns a file name suitable for use as a temporary file using fname as a base. Currently returns the file name with "_new" inserted prior to the extension.

No attempt is made to check that the file does not already exist.

QString Qtopia::translate ( const QString & key, const QString & c, const QString & str )

Translate str in the context c, using only the translation files defined by key. The key may be either a single name, such as "QtopiaSettings", or it may be a 'wildcard', such as "Categories-*". The key thus defines the set of translation files in which to search for a translation.

bool Qtopia::truncateFile ( QFile & f, int size )

Returns true if able to truncate file to size specified f must be an open file size must be a positive value; otherwise returns false.

bool Qtopia::unlockFile ( QFile & f )

Unlock a file. Returns true if successful.

f must be an open file previously locked.

See also Qtopia::lockFile() and Qtopia::isFileLocked().

QString Qtopia::updateDir ()

Returns the directory in which Qt Extended system updates are installed to.

Binaries and resources located in this location are used in preference to those located in the directory returned by qtopiaDir().

This is returned as the first item in the installPaths() list.

The value of updateDir() is determinted by the [Updates] group in the Storage.conf file.

The directory must be writable, and is used by the Software Installer for installation of downloaded system updates.

This is the first item in the installPaths() list, and as such is the first location searched by the Qt Extended resource system, and the algorithm for locating binaries for execution.

See also qtopiaDir() and installPaths().

void Qtopia::usleep ( unsigned long usecs )

Suspends the current process for usecs microseconds.

Note that this function should be avoided where possible as it will freeze the user interface. Use of QTimer and QObject::startTimer() allow for delayed processing without freezing the user interface at the cost of being unable to trigger accurately.

See also QThread::usleep().

QString Qtopia::version ()

Returns the Qt Extended version string, specified by QPE_VERSION. This is of the form: major .minor .patchlevel (eg. "1.2.3"), possibly followed by a space and special information (eg. "1.2.3 beta4").

bool Qtopia::weekStartsOnMonday ()

Returns true if the user regards their week as starting on Monday. Returns false if the user regards their week as starting on Sunday.

See also setWeekStartsOnMonday().

void Qtopia::writeHWClock ()

Writes the system clock to the hardware clock.