Home · All Classes · Grouped Classes · Annotated · Functions

QDocumentSelector Class Reference

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

    #include <QDocumentSelector>

Inherits QWidget.

Public Types

Public Functions

Signals

Static Public Members

Additional Inherited Members


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:

Function/EnumUsage
setFilter()filter the list of documents using a QContentFilter.
filter()retrieve the current QContentFilter.
setSortMode()control the sorting of the list of documents.
QDocumentSelector::SortModeProvides a list of supported sort modes.
currentDocument()retrieve the currently selected/highlighted document in the list.
QDocumentSelector::Optionprovides a list of document selector configuration options.
options()retrieve the enabled document selector options.
setOptions()set the enabled document selector options.
enableOptions()enable one or more options in addition to those already enabled.
disableOptions()disable one or more document selector options.

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:

    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:

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.

ConstantValueDescription
QDocumentSelector::None0No special configuration options.
QDocumentSelector::NewDocument1The first item in the documents list is the new document item
QDocumentSelector::TypeSelector2A 'Select Type' menu item is available in the context menu which allows the user to restrict the visible document types.
QDocumentSelector::NestTypes4The 'Select Type' dialog groups similar types into a single selectable filter which the specific types are children of, similar to the list below:
  • Audio
    • mp3
    • wav
  • Image
    • png
    • ...
  • ...
QDocumentSelector::ContextMenu8The QDocumentSelector has a context menu.

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().

ConstantValueDescription
QDocumentSelector::NewSelected0The user has chosen the new document option.
QDocumentSelector::DocumentSelected1The user has chosen an existing document.
QDocumentSelector::Cancelled2The user cancelled the dialog.

enum QDocumentSelector::SortMode

This enum specifies the sort order of the documents.

ConstantValueDescription
QDocumentSelector::Alphabetical0The document set is ordered alphabetically on the names of the documents.
QDocumentSelector::ReverseAlphabetical1The document set is reverse ordered alphabetically on the names of the documents.
QDocumentSelector::Chronological2The document set is ordered on the date and time the documents were last edited.
QDocumentSelector::ReverseChronological3The document set is reverse ordered on the date and time the documents were last edited.
QDocumentSelector::SortCriteria4The document set is ordered by a QContentSortCriteria specified by sortCriteria().


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().

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().


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3