Home · All Classes · Grouped Classes · Annotated · Functions

QContentFilter Class Reference

The QContentFilter class defines criteria for defining a sub-set of all available content. More...

    #include <QContentFilter>

Public Types

Public Functions

Static Public Members


Detailed Description

The QContentFilter class defines criteria for defining a sub-set of all available content.

Instances of QContentSet and QDocumentSelector use content filters to define their visible set of content. A basic filter is composed of a string value and an attribute of QContent specified by the FilterType enumeration, so that any content with the specified attribute matching the given value is passed.. These basic filters can be combined by using the and (&), or (|) and negation (~) operators to create complex filters which pass any content that matches the logical combination of the base filters.

If two filters that are not negated are combined with an operand common to both filters (or one or both have no operand) the filter arguments are simply merged to create a new filter with the common operand. If however there is no common operand or a filter is negated then the combined filters become sub filters of the new filter which has no arguments of its own.

File paths

Location and Directory filters filter content based on their file path, they differ in that a Directory filter will only pass content in the directory given in the argument of the filter whereas the Location filter will also pass content in any sub-directory of that directory. Directory filter arguments may include a wild card.

Filter for all content in the /Documents directory:

    QContentFilter filter( QContentFilter::Directory, "/Documents" );

Filter for all content in the sub-directories of /Documents but not in the directory itself:

    QContentFilter filter( QContentFilter::Directory, "/Documents/*" );

Filter for all content in the /Documents directory or any of it's sub-directories:

    QContentFilter filter( QContentFilter::Location, "/Documents" );

Alternatively this could be achieved by combining two directory filters:

    QContentFilter filter
            = QContentFilter( QContentFilter::Directory, "/Documents" )
            | QContentFilter( QContentFilter::Directory, "/Documents/*" );

Roles

Role filters filter content based on the QContent::role() attribute which defines the intended usage of the QContent. A role filter may be constructed using the Role filter type or from the QContent::Role enumeration. Most application content sets will only be interested in displaying user documents and so should apply a role filter on QContent::Document to all content sets.

Limiting an existing filter to only include documents with the Document role:

    QContentFilter final = existingFilter & QContentFilter( QContentFilter::Role, "Document" );

The same filter constructed from the QContent::Role enumeration:

    QContentFilter final = existingFilter & QContentFilter( QContent::Document );

Mime types

MimeType filters filters content on the QContent::type() attribute. They may be constructed using the MimeType filter type or from a QMimeType. Wild cards may be used on mime type arguments to match the major type only.

Filter for all PNG images:

    QContentFilter png( QContentFilter::MimeType, "image/png" );

The same filter using QMimeType:

    QContentFilter png( QMimeType( "image/png" ) );

Filter for all images:

    QContentFilter image( QContentFilter::MimeType, "image/*" );

Categories

Category filters filter content based on the categories they've been assigned. The argument for a category filter is the ID of the category, alternatively a category filter can be constructed from a QCategoryFilter.

Filter for content with the Business or Personal categories:

    QContentFilter categories
        = QContentFilter( QContentFilter::Category, "Business" )
        | QContentFilter( QContentFilter::Category, "Personal" );

Content that has not been assigned any categories implicitly belongs to the Unfiled category and can be filtered for using the Unfiled category ID string or a QCategoryFilter as below:

    QContentFilter unfiled( QCategoryFilter( QCategoryFilter::Unfiled ) );

DRM

DRM filters filter content based on the QContent::drmState() attribute. The only valid arguments for a DRM filter are Protected and Unprotected which filter protected and unprotected content respectively. Alternatively a DRM filter may be constructed from the QContent::DrmState enum.

Properties

Synthetic filters filter content based on their properties. The argument for a synthetic filter is composed of the property group and key concatenated with the expected value in the form [group]/[key]/[value], if the property does not belong to a group the argument should be of the form none/[key]/[value]. If the property belongs to the QContent::Property enumeration the filter may be constructed from that enumeration and the expected value.

Filter for content with the author Trolltech:

    QContentFilter author( QContentFilter::Synthetic, "none/Author/Trolltech" );

The same filter using the QContent::Property enumeration:

    QContentFilter author( QContent::Author, "Trolltech" );

Member Type Documentation

enum QContentFilter::FilterType

Identifies the QContent property that a filter argument is compared with.

ConstantValueDescription
QContentFilter::Location0The root path of the storage media or mount the content is stored on.
QContentFilter::Role1The value of QContent::role(); Application, Document or Data.
QContentFilter::MimeType2The value of QContent::type(); audio/mpeg, image/gif, etc.
QContentFilter::Directory3The directory the content is located in.
QContentFilter::Category4The ID of a category assigned to the content.
QContentFilter::DRM5The DRM state of the content.
QContentFilter::Property6The value of a content property. Arguments are of the form [group]/[key]/[value].
QContentFilter::Name8Filters on the the value of QContent::name().
QContentFilter::FileName7Filters on the file name of content excluding the path.
QContentFilter::QtopiaTypeRoleQtopiaType has been deprecated. Please use Role instead.
QContentFilter::SyntheticPropertyThe Synthetic filter type has been renamed to Property.
QContentFilter::Unknown100Invalid filter argument.

enum QContentFilter::Operand

Represents the operand used to combine a group of filters.

ConstantValueDescription
QContentFilter::NoOperand0The operand for an invalid filter or a filter with a single argument and no sub filters.
QContentFilter::And1The filter passes the intersection of all its arguments and sub filters.
QContentFilter::Or2The filter passes the union of all its arguments and sub filters.


Member Function Documentation

QContentFilter::QContentFilter ()

Constructs an invalid QContentFilter which will not pass any content.

QContentFilter::QContentFilter ( const QContentFilter & other )

Constructs a copy of the filter other.

QContentFilter::QContentFilter ( FilterType type, const QString & argument )

Constructs a filter with the FilterType type and the value to match argument.

QContentFilter::QContentFilter ( QContent::Property property, const QString & value )

Constructs a filter which passes content whose property property matches value.

QContentFilter::QContentFilter ( QContent::Role role )

Constructs a filter that passes content with the given content role.

QContentFilter::QContentFilter ( const QMimeType & mime )

Constructs a filter that passes content with the given mime type.

QContentFilter::QContentFilter ( const QCategoryFilter & filter )

Constructs a filter that passes content matching the given category filter.

QContentFilter::~QContentFilter ()

Destroys a QContentFilter.

QStringList QContentFilter::argumentMatches ( FilterType type, const QString & scope ) const

Returns a list of filter arguments of FilterType type that can be used to further narrow the matches returned by a QContentFilter.

The scope is used to optionally restrict matches to a sub group of arguments matching the filter. The scope of a MimeType filter is the mime major type, so for example the image scope will return arguments like image/jpeg, and image/png. For Category filters scope simply refers to the category scope, and for Synthetic filters it is the property group and key in the form [group]/[key].

QStringList QContentFilter::arguments ( FilterType type ) const

Returns the filter arguments of FilterType type, not including sub filters.

See also types() and subFilters().

QContentFilter QContentFilter::category ( const QString & categoryId )   [static]

Constructs a content filter that filters for content belonging to the category with the id categoryId.

void QContentFilter::clear ()

Clears the contents of a filter, invalidating it.

See also isValid().

QContentFilter QContentFilter::fileName ( const QString & fileName )   [static]

Constructs a content filter that filters for content with a file name value that matches fileName.

bool QContentFilter::isValid () const

Returns true if the filter is valid. A QContentFilter constructed with no arguments is invalid.

See also clear().

QContentFilter QContentFilter::mimeType ( const QString & mimeType )   [static]

Constructs a content filter that filters for content with a mime type value that matches mimeType.

QContentFilter QContentFilter::name ( const QString & name )   [static]

Constructs a content filter that filters for content with a name value that matches name.

bool QContentFilter::negated () const

Returns true if the filter has been negated.

See also operator~().

Operand QContentFilter::operand () const

Returns the operand used to combine the filter arguments and sub filters.

See also types(), arguments(), and subFilters().

QContentFilter QContentFilter::property ( const QString & group, const QString & key, const QString & value )   [static]

Constructs a content filter that filters for content with the given property group and key that matches value.

QContentFilter QContentFilter::property ( const QString & key, const QString & value )   [static]

This is an overloaded member function, provided for convenience.

Constructs a content filter that filters for content with the given property key and no group that matches value.

QList<QContentFilter> QContentFilter::subFilters () const

Returns any sub filters the the filter is composed of.

See also types() and arguments().

bool QContentFilter::test ( const QContent & content ) const

Returns true if a QContent object content passes the filter; otherwise returns false.

QList<FilterType> QContentFilter::types () const

Returns a list of filter types common to the arguments the filter is composed of, not including sub filters.

See also arguments() and subFilters().

bool QContentFilter::operator!= ( const QContentFilter & other ) const

Compares a QContentFilter to other. Returns true if they are not equal and false otherwise.

QContentFilter QContentFilter::operator& ( const QContentFilter & other ) const

Returns a new QContentFilter which will pass the intersection of this filter and other.

Combining an invalid QContentFilter and a valid one will return the valid QContentFilter.

See also And and operator&=().

QContentFilter & QContentFilter::operator&= ( const QContentFilter & other )

Restricts this QContentFilter to the intersection of it and another QContentFilter other.

If the QContentFilter is invalid, it will be assigned other.

See also And and operator&().

QContentFilter & QContentFilter::operator= ( const QContentFilter & other )

Assigns other to this QContentFilter.

bool QContentFilter::operator== ( const QContentFilter & other ) const

Compares a QContentFilter to other. Returns true if they are equal and false otherwise.

QContentFilter QContentFilter::operator| ( const QContentFilter & other ) const

Creates a new QContentFilter which will pass the union of this filter and other.

Combining an invalid QContentFilter and a valid one will return the valid QContentFilter.

See also Or and operator|=().

QContentFilter & QContentFilter::operator|= ( const QContentFilter & other )

Restricts this QContentFilter to the union of it and another QContentFilter other.

If the QContentFilter is invalid, it will be assigned other.

See also Or and operator|().

QContentFilter QContentFilter::operator~ () const

Creates a negated copy of aQContentFilter.

The new filter will pass all content not passed by the existing QContentFilter.

See also negated().


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3