QDocumentSelector Class Reference
[QtBaseModule]

Detailed Description

The QDocumentSelector widget allows the user choose a document from a list of documents available on the device.

The QDocumentSelector widget builds the list of documents by using a supplied QContent filter. If no filter is set a default filter, which searches for all documents on the device, is used.

Some of the most commonly used functionality is:

When the QDocumentSelector::NewDocument option is enabled, QDocumentSelector adds a new document item to the selection widget. When the item is chosen by the user, the newSelected() signal is emitted.

When a document is chosen, QDocumentSelector emits a documentSelected() signal and a QContent associated with document is passed with the signal.

The currently selected document can be retrieved using currentDocument().

The following code is an example of how to:

• chronologically order a list of documents
• receive notification when the user chooses to create a document
• receive notification when the user chooses a document

    QDocumentSelector *selector = new QDocumentSelector( this );
    selector->setSortMode( QDocumentSelector::Chronological );
    selector->enableOptions( QDocumentSelector::NewDocument );

    connect( selector, SIGNAL(newSelected()), this, SLOT(newDocument()) );
    connect( selector, SIGNAL(documentSelected(QContent)),
             this, SLOT(openDocument(QContent)) );

The document selector also complies with DRM requirements so that the user can only choose documents which give the permissions needed by the application. There are two sets of permissions:

• Select Permissions
• Mandatory Permissions

Both sets of permissions effectively define the intended usage for the document. For example, the QDrmRights::Print permission is required to print the document. When the documents are displayed in the list, the selector will try to acquire the permissions needed to use the document. If the document does not give a permission in the select permissions set, the selector will activate in doing so try to acquire the permissions for that document. If the selector is unsuccessful, the document is still displayed but visually "grayed" out to indicate the document cannot be selected. Mandatory permissions differ from select permissions in that the activation step is not taken, the document must immediately give the mandatory permission in order to be choosable.

In the case of a generic document selector where the permissions required by the application depends on the document type, QDrmRights::InvalidPermission can be passed to setSelectPermission(), the selector will then use the default permissions of the document.

QDocumentSelector is often the first widget seen in a document-oriented application . Used in combination with QStackedWidget, a typical application allows choosing of a document using the QDocumentSelector, before revealing the document in a viewer or editor.

For a complete example that uses QDocumentSelector, see the tutorial Using QDocumentSelector to Write a Notes Application.

See also QDocumentSelectorDialog, QImageDocumentSelector, and QImageDocumentSelectorDialog.

Member Type Documentation

enum QDocumentSelector::Option
flags QDocumentSelector::Options

Options for configuring a QDocumentSelector.

The Options type is a typedef for QFlags<Option>. It stores an OR combination of Option values.

enum QDocumentSelector::Selection

This enum indicates the result of displaying a document selector dialog. See select().

enum QDocumentSelector::SortMode

This enum specifies the sort order of the documents.

Member Function Documentation

QDocumentSelector::QDocumentSelector ( QWidget * parent = 0 )

Constructs a new document selector widget with the given parent.

QDocumentSelector::~QDocumentSelector ()

Destroys the selector.

void QDocumentSelector::currentChanged ()   [signal]

Signals that the currently selected document has changed.

The current selection can be determined using newCurrent() and currentDocument().

See also newCurrent() and currentDocument().

QContent QDocumentSelector::currentDocument () const

Returns a QContent for the currently selected document.

A null QContent is returned if there is no current selection or if the new document item is currently selected.

See also documents().

QStringList QDocumentSelector::defaultCategories () const

Returns the categories checked by default in the document selector's category filter dialog.

This function is only relevant if the QDocumentSelector::ContextMenu option has been set or enabled.

See also setDefaultCategories() and Categories.

void QDocumentSelector::disableOptions ( Options options )

Disables the given options.

See also enableOptions(), options(), and setOptions().

void QDocumentSelector::documentSelected ( const QContent & content )   [signal]

Signals that the user has chosen content from the document list.

See also newSelected().

const QContentSet & QDocumentSelector::documents () const

Returns the content set of documents listed by the selector.

See also currentDocument().

void QDocumentSelector::documentsChanged ()   [signal]

This signal is emitted when the list of documents changes as a result of a filter change or a file system change.

void QDocumentSelector::enableOptions ( Options options )

Enables the document selector options, in addition to those already enabled.

See also disableOptions(), options(), and setOptions().

QContentFilter QDocumentSelector::filter () const

Returns the current documents filter.

The filter defines the subset of content on the device the user can select from.

See also setFilter() and QContentSet::filter().

QDrmRights::Permissions QDocumentSelector::mandatoryPermissions () const

Returns the permissions a document must have in order to be choosable by the document selector.

See also setMandatoryPermissions(), setSelectPermission(), and selectPermission().

bool QDocumentSelector::newCurrent () const

Returns true if the new document item is currently selected.

See also setOptions().

void QDocumentSelector::newSelected ()   [signal]

Signals that the user chosen the new document item.

See also documentSelected().

Options QDocumentSelector::options () const

Returns the enabled document selector options.

See also setOptions(), enableOptions(), and disableOptions().

Selection QDocumentSelector::select ( QWidget * parent, QContent * content, QDrmRights::Permission permission, const QString & title, const QContentFilter & filter, Options options = ContextMenu, SortMode sortMode = Alphabetical )   [static]

Displays a modal QDocumentSelectorDialog with the given parent and title. The dialog will be configured with the provided filter, options, sortMode and permission. Choosing a document will assign that document to content if it can be rendered with the given permission.

Returns the user's chosen action.

Selection QDocumentSelector::select ( QWidget * parent, QContent * content, const QString & title, const QContentFilter & filter, Options options = ContextMenu, SortMode sortMode = Alphabetical )   [static]

This is an overloaded member function, provided for convenience.

Displays a modal QDocumentSelectorDialog with the given parent and title. The dialog will be configured with the provided filter, options and sortMode. Choosing a document will assign that document to content.

Returns the user's chosen action.

QDrmRights::Permission QDocumentSelector::selectPermission () const

Returns the permissions a document should give in order to be choosable.

The permissions effectively describe the document's intended usage.

See also setSelectPermission(), mandatoryPermissions(), and setMandatoryPermissions().

QStringList QDocumentSelector::selectedCategories () const

Returns a list of categories selected in a document selector's category filter dialog.

See also setDefaultCategories().

void QDocumentSelector::setDefaultCategories ( const QStringList & categories )

Sets the categories checked by default in the document selector's category filter dialog.

The categories displayed in a document selector's category filter dialog are restricted to categories assigned to documents that would appear in the document selector with no categories checked. If a default category does not match any visible in the category filter dialog it will be ignored.

Setting a default category will filter the visible documents by that category (assuming there are documents belonging to that category) but the user is able to remove the filtering by unchecking the category in the filter dialog. To apply a filter that cannot be removed use setFilter() instead.

Note: Once the dialog has been shown once, this function no longer has any effect.

Filtering according to categories is applied after the filter defined by filter().

See also defaultCategories(), filter(), setFilter(), and Categories.

void QDocumentSelector::setFilter ( const QContentFilter & filter )

Sets the filter which defines the subset of content on the device the user can select from.

The document list is filtered when control returns to the event loop.

See also filter() and QContentSet::filter().

void QDocumentSelector::setMandatoryPermissions ( QDrmRights::Permissions permissions )

Sets the permissions a document must have in order to be choosable from the document selector.

Unlike select permissions, if a document is missing a mandatory permission it will not be activated, and the document cannot be chosen.

Because the permissions are mandatory, passing QDrmRights::InvalidPermission as a parameter does not exhibit the same behavior as in setSelectPermission().

See also mandatoryPermissions(), setSelectPermission(), and selectPermission().

void QDocumentSelector::setOptions ( Options options )

Sets the enabled set of selector options.

See also enableOptions(), disableOptions(), and options().

void QDocumentSelector::setSelectPermission ( QDrmRights::Permission permission )

Sets the permission a document should give in order to be choosable. The permissions effectively specify the intended usage for that document.

If a document does not have provide the given permission, the document selector will try to activate and thus acquire permissions for the document. If the document cannot be activated with that permission, it will not be choosable from the list and visual indication of this is given.

If the permission is QDrmRights::InvalidPermission the default permissions for the document is used.

See also selectPermission(), setMandatoryPermissions(), and mandatoryPermissions().

void QDocumentSelector::setSortCriteria ( const QContentSortCriteria & sort )

Sets the document sort criteria.

This will set the document selector sort mode to SortCriteria.

The document list is sorted when control returns to the event loop.

See also sortCriteria() and setSortMode().

void QDocumentSelector::setSortMode ( SortMode mode )

Sets the document sort mode, the default is QDocumentSelector::Alphabetical.

The document list is sorted when control returns to the event loop.

See also sortMode().

QContentSortCriteria QDocumentSelector::sortCriteria () const

Returns the current document sort criteria.

See also setSortCriteria().

SortMode QDocumentSelector::sortMode () const

Returns the current document sort mode.

See also setSortMode().