|
Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions | |
The QDocumentSelector widget allows the user choose a document from a list of documents available on the device. More...
#include <QDocumentSelector>
Inherits QWidget.
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/Enum | Usage |
|---|---|
| setFilter() | filter the list of documents using a QContentFilter. |
| filter() | retrieve the current QContentFilter. |
| setSortMode() | control the sorting of the list of documents. |
| QDocumentSelector::SortMode | Provides a list of supported sort modes. |
| currentDocument() | retrieve the currently selected/highlighted document in the list. |
| QDocumentSelector::Option | provides 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.
Options for configuring a QDocumentSelector.
| Constant | Value | Description |
|---|---|---|
| QDocumentSelector::None | 0 | No special configuration options. |
| QDocumentSelector::NewDocument | 1 | The first item in the documents list is the new document item |
| QDocumentSelector::TypeSelector | 2 | A 'Select Type' menu item is available in the context menu which allows the user to restrict the visible document types. |
| QDocumentSelector::NestTypes | 4 | The 'Select Type' dialog groups similar types into a single selectable filter which the specific types are children of, similar to the list below:
|
| QDocumentSelector::ContextMenu | 8 | The QDocumentSelector has a context menu. |
The Options type is a typedef for QFlags<Option>. It stores an OR combination of Option values.
This enum indicates the result of displaying a document selector dialog. See select().
| Constant | Value | Description |
|---|---|---|
| QDocumentSelector::NewSelected | 0 | The user has chosen the new document option. |
| QDocumentSelector::DocumentSelected | 1 | The user has chosen an existing document. |
| QDocumentSelector::Cancelled | 2 | The user cancelled the dialog. |
This enum specifies the sort order of the documents.
| Constant | Value | Description |
|---|---|---|
| QDocumentSelector::Alphabetical | 0 | The document set is ordered alphabetically on the names of the documents. |
| QDocumentSelector::ReverseAlphabetical | 1 | The document set is reverse ordered alphabetically on the names of the documents. |
| QDocumentSelector::Chronological | 2 | The document set is ordered on the date and time the documents were last edited. |
| QDocumentSelector::ReverseChronological | 3 | The document set is reverse ordered on the date and time the documents were last edited. |
| QDocumentSelector::SortCriteria | 4 | The document set is ordered by a QContentSortCriteria specified by sortCriteria(). |
Constructs a new document selector widget with the given parent.
Destroys the selector.
Signals that the currently selected document has changed.
The current selection can be determined using newCurrent() and currentDocument().
See also newCurrent() and currentDocument().
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().
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.
Disables the given options.
See also enableOptions(), options(), and setOptions().
Signals that the user has chosen content from the document list.
See also newSelected().
Returns the content set of documents listed by the selector.
See also currentDocument().
This signal is emitted when the list of documents changes as a result of a filter change or a file system change.
Enables the document selector options, in addition to those already enabled.
See also disableOptions(), options(), and setOptions().
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().
Returns the permissions a document must have in order to be choosable by the document selector.
See also setMandatoryPermissions(), setSelectPermission(), and selectPermission().
Returns true if the new document item is currently selected.
See also setOptions().
Signals that the user chosen the new document item.
See also documentSelected().
Returns the enabled document selector options.
See also setOptions(), enableOptions(), and disableOptions().
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.
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.
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().
Returns a list of categories selected in a document selector's category filter dialog.
See also setDefaultCategories().
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.
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().
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().
Sets the enabled set of selector options.
See also enableOptions(), disableOptions(), and options().
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().
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().
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().
Returns the current document sort criteria.
See also setSortCriteria().
Returns the current document sort mode.
See also setSortMode().
| Copyright © 2009 Trolltech | Trademarks | Qt Extended 4.4.3 |