QImageDocumentSelector Class Reference
[QtBaseModule]

Detailed Description

The QImageDocumentSelector widget allows the selection an image from a list of image documents available on the device.

The QImageDocumentSelector widget builds a list of documents by locating all images in the device document directories. Alternatively, the list can be built with images which match a custom content filter.

Some of the commonly used functionality is:

In addition documents may be viewed in two modes:

• QImageDocumentSelector::Single - presents a thumbnail of the current image contained within the dimensions of the QImageDocumentSelector widget.
• QImageDocumentSelector::Thumbnail - presents thumbnails of the images in an icon-type scroll view allowing multiple image thumbnails to be viewed concurrently.

  The size of thumbnails is manipulated using:

  • setThumbnailSize() - sets the size of the thumbnail
  • thumbnailSize() - retrieves the size of the current thumbnail.

Images are highlighted one at a time and a articular image can be chosen vi the stylus or select key and arrow keys are used to navigate through the list of image documents.

When an image is chosen the following occurs:

• The image document selector emits a documentSelected() signal
• a QContent for the chosen document is passed with the signal.

Whenever the list of documents is changed as a result of a filter change or a file system change, QImageDocumentSelector will emit a documentsChanged() signal.

The following code allows the user to choose from all image documents available on the device using the thumbnail view mode with a custom thumbnail size:

    QImageDocumentSelector *selector = new QImageDocumentSelector( this );
    selector->setThumbnailSize( QSize( 100, 100 ) );

    connect( selector, SIGNAL(documentSelected(QContent)),
        this, SLOT(openImage(QContent)) );

QImageDocumentSelector is often the first widget seen in a document-oriented application. When used with QStackedWidget, an application allows choosing of a document using the selector before revealing the document viewer or editor.

See also QImageDocumentSelectorDialog, QDocumentSelector, and QDocumentSelectorDialog.

Member Type Documentation

enum QImageDocumentSelector::ViewMode

This enum describes the types of viewing modes.

Member Function Documentation

QImageDocumentSelector::QImageDocumentSelector ( QWidget * parent = 0 )

Construct an image document selector widget with the given parent.

QImageDocumentSelector::~QImageDocumentSelector ()

Destroys the widget.

QContent QImageDocumentSelector::currentDocument () const

Returns a QContent for the currently selected image, or an invalid QContent if there is no current selection.

See also documents().

QStringList QImageDocumentSelector::defaultCategories () const

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

See also setDefaultCategories().

void QImageDocumentSelector::documentSelected ( const QContent & image )   [signal]

This signal is emitted when the user chooses an image. A QContent for the image document is given in image.

const QContentSet & QImageDocumentSelector::documents () const

Returns the content set of image documents listed by the selector

See also currentDocument().

void QImageDocumentSelector::documentsChanged ()   [signal]

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

QContentFilter QImageDocumentSelector::filter () const

Returns the current documents filter.

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

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

QDrmRights::Permissions QImageDocumentSelector::mandatoryPermissions () const

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

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

QDrmRights::Permission QImageDocumentSelector::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 QImageDocumentSelector::setDefaultCategories ( const QStringList & categories )

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

If a supplied category does not match those available in the category filter dialog, the document selector will not filter with that category. Upon invocation this function will set the default checked categories within the category filter dialog, and filter according to the supplied categories. 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(), and setFilter().

void QImageDocumentSelector::setFilter ( const QContentFilter & filter )

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

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

void QImageDocumentSelector::setFocus ()   [slot]

Gives the keyboard input focus to this widget (or its focus proxy) if this widget or one of its parents is the active window.

void QImageDocumentSelector::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 QImageDocumentSelector::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 QImageDocumentSelector::setSortCriteria ( const QContentSortCriteria & sort )

Sets the document sort criteria.

This will set the document selector sort mode to SortCriteria.

See also sortCriteria() and setSortMode().

void QImageDocumentSelector::setSortMode ( QDocumentSelector::SortMode sortMode )

Sets the document sortMode

The default mode is QDocumentSelector::Alphabetical.

See also sortMode().

void QImageDocumentSelector::setThumbnailSize ( const QSize & size )

Sets the maximum size of a thumbnail.

The default size is QSize( 65, 65 ).

See also thumbnailSize().

void QImageDocumentSelector::setViewMode ( ViewMode mode )

Sets the viewing mode

The default mode is QImageDocumentSelector::Thumbnail.

See QImageDocumentSelector::ViewMode for a listing of supported view modes.

See also viewMode().

QContentSortCriteria QImageDocumentSelector::sortCriteria () const

Returns the current document sort criteria.

See also setSortCriteria().

QDocumentSelector::SortMode QImageDocumentSelector::sortMode () const

Returns the current document sort mode.

See also setSortMode().

QSize QImageDocumentSelector::thumbnailSize () const

Returns the current maximum size of a thumbnail.

See also setThumbnailSize().

ViewMode QImageDocumentSelector::viewMode () const

Returns the current view mode.

See QImageDocumentSelector::ViewMode for a listing of supported view modes.

See also setViewMode().