Home · All Classes · Grouped Classes · Annotated · Functions

QContentSet Class Reference

The QContentSet class represents a filtered view of all content on a device. More...

    #include <QContentSet>

Inherits QObject.

Public Types

Public Functions

Signals

Static Public Members

Related Non-Members

Additional Inherited Members


Detailed Description

The QContentSet class represents a filtered view of all content on a device.

The content that appears in a QContentSet is defined by a applying a filtering criteria to the set with setCriteria(). Any content in the backing store that passes the filtering criteria is included in the set, if no filtering criteria is applied the set is empty. By default content in a set is sorted by name, an alternative sort order can be specified with setSortCriteria().

Asynchronous and Synchronous updates

QContentSets are synchronized with the backing store; if content is added, removed, or modified in a way affecting its inclusion in a QContentSet the QContentSet will be updated to reflect that change. A QContentSet can be made to update its content asynchronously or synchronously, the content is updated the same whether caused by external events or changing the filtering or sorting criteria.

Updates to an asynchronous content set are performed in an background thread which is started from the event loop when a change to the filtering or sorting criteria has been identified or a change notification has been received. As the update is performed pairs of contentAboutToBeRemoved()/contentRemoved() and contentAboutToBeInserted()/contentInserted() signals are emitted to indicate where changes to the content set have occurred, these signals are synchronized to the event loop of the QContentSet's thread so within an event the count() of a QContentSet will not change.

Synchronous QContentSets simply reset the contents of the set when there is a possible change in the content. Changing the filtering or sorting criteria will trigger a deferred update of the content set which occur either when control returns to the event loop or count() is called. This allows a number of changes to be accumulated before updating the set.

Generally for persisted QContentSets such those used in document selectors the asynchronous update mode should be preferred, while the synchronous mode is more suited for one off queries.

Explicit content

In addition to the filtered content a QContentSet has an internal list of explicitly maintained content. Content added to a set explicitly is included in the visible set irregardless of whether it passes the filtering criteria and does not have to be committed to the backing store. The contents of this internal list are managed with the add() and remove() methods.

Example: Iterating over a set of user audio recordings sorted by most recently modified.

    QContentSet contentSet;

    // Filter for documents with the mime type 'audio/wav' in the 'Recordings' category.
    contentSet.setCriteria( QContentFilter( Document ) );
    contentSet.addCriteria( QContentFilter::mimeType( "audio/wav" ), QContentFilter::And );
    contentSet.addCriteria( QContentFilter::category( "Recordings" ), QContentFilter::And );

    // Sort by modified date in descending order.
    contentSet.setSortCriteria( QContentSortCriteria(
            QContentSortCriteria::LastModified,
            Qt::DescendingOrder ) );

    for( int i = 0; i < contentSet.count(); i++ )
    {
        QContent content = contentSet.content( i );
        ...
    }

Tutorials

For an example of setting the filtering criteria of a QContentSet see the Content Filtering tutorial and for an example of listening for changes in a QContentSet see the Change Listener tutorial.


Member Type Documentation

enum QContentSet::Priority

This enum specifies the priority to use when scanning a directory.

ConstantValueDescription
QContentSet::LowPriority0use low priority
QContentSet::NormalPriority1use normal priority
QContentSet::HighPriority2use low priority - directory will be scanned before lower priority jobs.

enum QContentSet::UpdateMode

Indicates whether the contents of a content set should be updated synchronously or asynchronously.

ConstantValueDescription
QContentSet::Synchronous1Update the content set in the current thread of execution.
QContentSet::Asynchronous0Update the content set in a background thread.


Member Function Documentation

QContentSet::QContentSet ( QObject * parent = 0 )

Constructs a new unfiltered QContentSet with the specified parent.

The QContentSet can be populated with content from the backing store by specifying a filtering criteria with setCriteria() or addCriteria().

See also setCriteria(), addCriteria(), and setSortCriteria().

QContentSet::QContentSet ( const QContentFilter & criteria, QObject * parent = 0 )

Constructs a new QContentSet with the specified parent containing all content from the backing store which matches the filtering criteria.

See also addCriteria() and setSortCriteria().

QContentSet::QContentSet ( const QContentFilter & criteria, const QStringList & sortOrder, QObject * parent = 0 )

This function is deprecated.

Constructs a new QContentSet with the specified parent containing all content from the backing store which matches the filtering criteria and is sorted by sortOrder.

Note: The use of a QStringList to specify the sort order is deprecated, use a QContentSortCriteria instead.

See also addCriteria() and setSortOrder().

QContentSet::QContentSet ( QContentFilter::FilterType tag, const QString & filter, QObject * parent = 0 )

Constructs a new QContentSet with the specified parent containing all content from the backing store which matches the tag filtering criteria filter.

See also addCriteria() and setSortCriteria().

QContentSet::QContentSet ( QContentFilter::FilterType tag, const QString & filter, const QStringList & sortOrder, QObject * parent = 0 )

This function is deprecated.

Constructs a new QContentSet with the specified parent containing all content from the backing store which matches the tag filtering criteria filter and is sorted by sortOrder.

Example: Construct a QContentSet containing wave files sorted by most recently modified.

    QContentSet contentSet(
        QContentFilter::MimeType, "audio/wav",
        "time desc" );

Note: The use of a QStringList to specify the sort order is deprecated, use a QContentSortCriteria instead.

See also addCriteria() and setSortOrder().

QContentSet::QContentSet ( const QContentSet & original, QObject * parent = 0 )

Constructs a new QContentSet with the specified parent, containing all content from original.

QContentSet::QContentSet ( UpdateMode mode, QObject * parent = 0 )

Constructs an unfiltered QContentSet with the specified parent and update mode.

The QContentSet can be populated with content from the backing store by specifying a filtering criteria with setCriteria() or addCriteria().

See also setCriteria(), addCriteria(), and setSortCriteria().

QContentSet::QContentSet ( const QContentFilter & criteria, UpdateMode mode, QObject * parent = 0 )

Constructs a QContentSet with the specified parent and update mode containing all content from the backing store which matches the filtering criteria.

See also addCriteria() and setSortCriteria().

QContentSet::QContentSet ( const QContentFilter & criteria, const QContentSortCriteria & sort, UpdateMode mode, QObject * parent = 0 )

Constructs a QContentSet with the specified parent and update mode containing all content from the backing store which matches the filtering criteria and is sorted by sort.

Example: Construct an asynchronous QContentSet containing wave files sorted by most recently modified.

    QContentSet contentSet(
        QContentFilter::mimeType( "audio/wav" )
        QContentSortCriteria( QContentSortCriteria::LastUpdated, Qt::DescendingOrder )
        QContentSet::Asynchronous );

See also addCriteria().

QContentSet::~QContentSet ()   [virtual]

Destroys the QContentSet.

void QContentSet::aboutToSort ()   [signal]

This signal is emitted when this QContentSet is about to be sorted.

void QContentSet::add ( const QContent & content )

Adds content to an explicitly maintained internal list of content. Items in this list appear in the content set irregardless of whether they match the filtering criteria.

See also remove(), contains(), and clear().

void QContentSet::addCriteria ( QContentFilter::FilterType kind, const QString & filter, QContentFilter::Operand operand )

Appends a kind filter matching the value filter to the existing filtering criteria using the given operand.

Example: Filter for documents with the mime type image/jpeg or image/png.

    QContentSet contentSet;
    contentSet.addCriteria( QContentFilter::MimeType, "image/jpeg", QContentFilter::Or );
    contentSet.addCriteria( QContentFilter::MimeType, "image/png", QContentFilter::Or );
    contentSet.addCriteria( QContentFilter::Role", "Document", QContentFilter::And );

void QContentSet::addCriteria ( const QContentFilter & filter, QContentFilter::Operand operand )

This is an overloaded member function, provided for convenience.

Appends filter to the existing filtering criteria using the given operand.

Example: Filter for documents with the mime type image/jpeg or image/png.

    QContentSet contentSet( QContentFilter( QContent::Document ) );
    contentSet.addCriteria(
        QContentFilter::mimeType( "image/jpeg" ) | QContentFilter::mimeType( "image/png" ),
        QContentFilter::And );

void QContentSet::appendFrom ( QContentSet & other )

Appends the contents of other to this QContentSet. Currently it appends them as explicit items to the current QContentSet, in the future, it will concatenate the two filter sets to create a new aggregate filter set.

void QContentSet::changed ( const QContentIdList & idList, QContent::ChangeType type )   [signal]

This signal is emitted when QContent included in the filter expression for this QContentSet are changed by another application, or by removable media being inserted or removed.

idList contains a list of the Ids of QContent items that have changed.

type specifies the type of change that is being signalled.

void QContentSet::changed ()   [signal]

This is an overloaded member function, provided for convenience.

This signal is emitted when a large number of QContent objects included in the filter expression for this QContentSet are changed by another application or by removable media being inserted or removed.

void QContentSet::clear ()

Removes the filtering criteria, and all explicitly added content from the set.

This will remove all content from the set.

See also add(), remove(), contains(), setCriteria(), addCriteria(), and clearFilter().

void QContentSet::clearFilter ()

Clears the content set's current filtering criteria. This will remove all filtered content from the set but leave content that was explicitly added.

See also filter() and addCriteria().

bool QContentSet::contains ( const QContent & content ) const

Returns true if the set contains the object content, that is:

See also add(), remove(), and clear().

QContent QContentSet::content ( int index ) const

Returns the QContent at index in a set.

void QContentSet::contentAboutToBeInserted ( int start, int end )   [signal]

This signal is emitted when content items are about to be inserted between the start and end indexes.

Content may be inserted into a set a result of the filtering criteria changing, a QContent being explicitly added to the set, a new QContent being created on the device, or attributes of a QContent changing so that it matches the filtering criteria.

See also contentInserted().

void QContentSet::contentAboutToBeRemoved ( int start, int end )   [signal]

This signal is emitted when content items between the start and end indexes are about to be removed.

Content may be removed from a set as a result of the filtering criteria changing, a QContent being explicitly removed from the set, a QContent being deleted from the device, or attributes of a QContent changing so that it no longer matches the filtering criteria.

See also contentRemoved().

void QContentSet::contentChanged ( int start, int end )   [signal]

This signal is emitted when content items between the start and end indexes have changed.

QContentId QContentSet::contentId ( int index ) const

Returns the ID of the QContent at index in a set.

void QContentSet::contentInserted ()   [signal]

This signal is emitted when the content insertion indicated by contentAboutToBeInserted() has been completed.

See also contentAboutToBeInserted().

void QContentSet::contentRemoved ()   [signal]

This signal is emitted when the content removal indicated by contentAboutToBeRemoved() has been completed.

See also contentAboutToBeRemoved().

int QContentSet::count () const

Return the number of QContent objects in this set.

int QContentSet::count ( const QContentFilter & filter )   [static]

This is an overloaded member function, provided for convenience.

Returns the number of QContents in the database that match a content filter.

QContentFilter QContentSet::filter () const

Returns the current filtering criteria of the QContentSet.

void QContentSet::findDocuments ( QContentSet * folder, const QString & mimefilter = QString() )   [static]

Finds all documents in the system's document directories which match the filter mimefilter, and appends the resulting QContent objects to folder.

QContent QContentSet::findExecutable ( const QString & exec ) const

Find a QContent object for the executable exec in the current QContentSet. Returns an empty/invalid QContent if unsuccessful.

See also QContent::InvalidId.

QContent QContentSet::findFileName ( const QString & filename ) const

Find a QContent object for the filename in the current QContentSet. Returns an empty/invalid QContent if unsuccessful.

Paths are not acceptable in filename, ie the filename must not contain any "/" characters.

Note that if more than one item with the filename exists in the QContentSet no guarantee is provided as to which one is returned.

This method is typically used with filters such that only one filename item exists in the filtered set.

See also QContent::InvalidId.

bool QContentSet::isEmpty () const

Returns true if this set is empty.

QContentIdList QContentSet::itemIds () const

Return a QContentIdList of content IDs in this set.

This is a relatively expensive operation, and generally should not be used unless it is known that only a few items will be returned.

It is also a snapshot of the currently known items in the list, which has a possibility of going out of date immediately after it is obtained.

Instead of using this method consider iterating over the set directly instead.

    for( int i = 0; i < contentSet.count(); i++ )
    {
        QContentId contentId = contentSet.contentId( i );
        ...
    }

See also QContentSetModel and items().

QContentList QContentSet::items () const

Return a QContentList of items in this set.

This is a relatively expensive operation, and generally should not be used unless it is known that only a few items will be returned.

It is also a snapshot of the currently known items in the list, which has a possibility of going out of date immediately after it is obtained.

Instead of using this method consider iterating over the set directly instead.

    for( int i = 0; i < contentSet.count(); i++ )
    {
        QContent content = contentSet.content( i );
        ...
    }

See also QContentSetModel and itemIds().

void QContentSet::remove ( const QContent & content )

Removes content from an explicitly maintained internal list of content. Items in this list appear in the content set irregardless of whether they match the filtering criteria.

See also add(), contains(), and clear().

void QContentSet::scan ( const QString & path, Priority priority = NormalPriority )   [static]

Initiates a document scan of a path and its sub-directories looking for documents that have been added, removed, or modified to bring the backing store's view of the path up to date with the file system.

Scans are performed threaded in a server process, the scan priority sets the run priority of the scanner threads. A higher priority scan will finish sooner but may reduce the device responsiveness.

void QContentSet::setCriteria ( QContentFilter::FilterType kind, const QString & filter )

Sets the filtering criteria of a QContentSet to a kind filter matching the value filter.

This will replace any existing filtering criteria.

void QContentSet::setCriteria ( const QContentFilter & filter )

This is an overloaded member function, provided for convenience.

Sets the filtering criteria of a QContentSet to filter.

This will replace any existing filtering criteria.

Example: Filter for documents with the mime type image/jpeg or image/png.

    QContentSet contentSet;
    contentSet.setCriteria( QContentFilter( QContent::Document )
            & ( QContentFilter::mimeType( "image/jpeg" )
            | QContentFilter::mimeType( "image/png" ) ) );

void QContentSet::setSortCriteria ( const QContentSortCriteria & criteria )

Sets the sort criteria used to order the set.

See also sortCriteria().

void QContentSet::setSortOrder ( const QStringList & sortOrder )

This function is deprecated.

Sets the attributes that content in this QContentSet is ordered by to sortOrder.

Valid sort attributes are:

To specify whether to sort in ascending or descending order append asc or desc preceded by a space to the end of the attribute name.

Example: Sorting a QContent by last modified date in descending order.

    contentSet.setSortOrder( QStringList << "time desc" );

This method has been deprecated, use setSortCriteria() instead.

See also sortOrder() and setSortCriteria().

QContentSortCriteria QContentSet::sortCriteria () const

Returns the sort criteria used to order the set.

See also setSortCriteria().

QStringList QContentSet::sortOrder () const

This function is deprecated.

Returns the attributes the content in this QContentSet is ordered by.

This method has been deprecated, use sortCriteria() instead.

See also setSortOrder() and sortCriteria().

void QContentSet::sorted ()   [signal]

This signal is emitted when this QContentSet has been sorted.

QStringList QContentSet::types () const

Returns the list of mime-types contained in this set.

For applications, games and settings the type is application/x-executable.

For documents the type is the document's MIME type, or application/octet-stream if the file type is unknown.

UpdateMode QContentSet::updateMode () const

Returns the update mode of the content set; either Synchronous or Asynchronous.

QContentSet & QContentSet::operator= ( const QContentSet & contentset )

Assigns the given contentset to this QContentSet and returns a reference to this QContentSet.


Related Non-Members

typedef QContentList

Synonym for QList<QContent>.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3