Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

Main Document Widget

Applications that view or edit a particular type or types of files are called document-oriented applications. Qt Extended 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 Qt Extended 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.isNull() ) {
            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 commas. A list may alternately be separated by semi-colons, but if this is done the list must be enclosed in double quotes otherwise a semi-colon will be interpreted as a comment character.

        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 comma separated list of icon paths, the list must contain either a single icon path or the same number of paths as MIME types on the MimeType line. If a single icon path is given it is repeated for each MIME type, otherwise the icons are paired with MIME type according to their positions in the 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 only one icon and open permission for multiple MIME types:

        MimeType=image/jpeg,image/png
        MimeTypeIcons=imageviewer/ImageViewer
        [DRM]
        MimeTypePermissions=Display

An example of an application with multiple 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

A complete listing of .desktop file entries can be found in the Desktop File Standard

Run-time registration

An application may also associate itself with a MIME type at run-time using QMimeType::addAssociation(), and remove an association with QMimeType::removeAssociation(). QMimeType may also be used to query existing associations between applications and MIME types.

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. For an example of using the QDocumentSelector widget see the Notes Application tutorial.