Home · All Classes · Grouped Classes · Annotated · Functions

Qtopia - Main Document Widget

Applications that view or edit a particular type or types of files are called document-oriented applications. Qtopia has framework support to invoking these applications to open specific documents.

Implementation

The top-level widget of a document-oriented application must have a setDocument() slot declared:

    public slot:
        void setDocument( const QString& filename );

This slot is invoked by Qtopia with the file name of the document to open. It should be implemented to save the application's current document (if any) and to show (and possibly edit) the specified document. An example implementation is:

    void Main::setDocument( const QString& filename )
    {
        if ( !current.id() != QContent::InvalidId ) {
            if ( !current.save( data ) ) {
                // error
                return;
            }
        }

        current = QContent( filename );

        if ( !current.load( data ) ) {
            // error
        }
    }

Registering MIME types

Document-oriented applications declare the MIME types that they support by adding a line to their .desktop file specifying each supported type separated by semi-colons, if multiple types are supported the list must be enclosed in quotes:

        MimeType="type/subtype;type/subtype;..."

The subtype can be "*", indicating that this application can process all forms of the given type. Such an application is only invoked if no other more specific application is available.

Optionally an icon and a DRM permission may be specified for a MIME type when registering it. This is done by adding the MimeTypeIcons and MimeTypePermissions lines to the .desktop file.

The MimeTypeIcons line is a semi-colon separated list of icon paths, the list must contain the same number of paths as MIME types on the MimeType line. Each MIME type is paired with the icon at the equivalent index in the MimeTypeIcons list.

The MimeTypePermissions line has the same semantics as the MimeTypeIcons line but defines a DRM permission that must be verified before an application is invoked to open a document. The possible permission values are the names of the primary enumeration values in QDrmRights::Permission. The MimeTypePermissions line is part of the DRM group.

An example of an application with MIME type icons and open permissions:

        MimeType="audio/mpeg;video/mpeg;image/jpeg;image/png"
        MimeTypeIcons="mediaviewer/AudioPlayer;mediaviewer/VideoPlayer;mediaviewer/ImageViewer"
        [DRM]
        MimeTypePermissions="Play;Play;Display;Display"

Opening a document in another application

To open a document in an associated application execute the document with QContent::execute(). This will determine the appropriate application to open the document, start it, and call the setDocument() slot of its top-most widget:

        QContent document( fileName );

        document.execute();

Selecting a document within an application

The QDocumentSelector(Dialog) and QImageDocumentSelector(Dialog) widgets can be used to browse and select documents from within an application.