Home · All Classes · Grouped Classes · Annotated · Functions

QContentFilterModel Class Reference

The QContentFilterModel class defines a model for displaying and selecting possible content filters. More...

    #include <QContentFilterModel>

Inherits QAbstractItemModel.

Public Types

Public Functions

Additional Inherited Members

Detailed Description

The QContentFilterModel class defines a model for displaying and selecting possible content filters.

A basic content filter model is simply a list of content filters of common type which match content passed by a base filter. The type of filter listed in the model is specified using the QContentFilter::FilterType enumeration with some types requiring an additional sub-type. A base filter may be applied to a content filter model to restrict the displayed filters to those which also pass content passed by the base filter.

File path lists

A content filter model constructed with the QContentFilter::Location type and no sub-type will list locations filters for the root document paths containing content which matches the base filter. If a directory is passed as a sub-type it will list any sub-directories which contain content (including content in sub-directories) matching the base filter.

The QContentFilter::Directory filter type will list directory filters for sub-directories of the directory given in the sub-type which contain content matching the base filter. Listed directories will contain matching content in the immediate directory, not a sub-directory. If no directory is given in the sub-type then no filters will be listed.

Mime type lists

A list of mime types can be obtained by constructing the content filter model with the QContentFilter::MimeType filter type. If a mime major type is given as the the sub-type then only mime-types belonging to that major type will be listed, otherwise all mime types within the scope of the base filter will be listed.

A content filter model listing all available mime types:

    QContentFilterModel *mimeTypes = new QContentFilterModel( QContentFilter::MimeType );

Or just the image mime types:

    QContentFilterModel imageTypes = new QContentFilterModel( QContentFilter::MimeType, "image" );

Category lists

Category filter may be listed using the QContentFilter::Category filter type where the sub-type specifies the scope of the category filters, if no sub-type is given categories belonging to the global scope will be listed.

A content filter model containing global categories:

    QContentFilterModel *categories = new QContentFilterModel( QContentFilter::Category );

Categories in the "Documents" scope:

    QContentFilterModel *categories = new QContentFilterModel( QContentFilter::Category, "Documents" );

Property lists

Content filter models which list content property values can be constructed using the QContentFilter::Synthetic filter type with the property group and key in the sub-type, or using the QContent::Property enumeration. The property group and key used in the sub-type should be concatenated in the form "[group]/[key]", if the property does not belong to a group the sub-type should be of the form "none/[key]".

A content filter model listing all artists:

    QContentFilterModel *artists = new QContentFilterModel( QContentFilterModel::Synthetic, "none/Artist" );

The same filter model using the QContent::Property enumeration.

    QContentFilterModel *artists = new QContentFilterModel( QContent::Artist );


Using templates more complex filter models can be created, templates extend on the filter lists by including static labels, concatenation of multiple filter lists, and nested lists.


Labels allow items to be explicitly added to a list, they may be used to select a static filter or a nested list. A label at a minimum consists of a user visible string usually combined with a a filter or a target sub-template and may include an icon. Labels are not sorted they appear in the order they are appended to a list. By default if the filter for a label does not match any known content the label will not be displayed, this can be disabled by setting the QContentFilterModel::ShowEmptyLabels template option.

A simple template using labels to select an Application or Document role filter:

    QContentFilterModel::Template role;
    role.addLabel( tr( "Applications" ), QContentFilter( QContent::Role ) );
    role.addLabel( tr( "Documents" ), QContentFilter( QContent::Document ) );

Nested templates

Templates may be nested to construct a tree model of content filters, templates are nested by specifying a target template when adding a list or label to another template. The contents of a nested template will be filtered by the filters of the its parent items and the model's base filter and the filter returned for an index in a tree model will be the filter at the index and'ed with the filters of its parents but not the model's base filter.

A content filter model using a nested template to display artists with albums by an artist as children:

    QContentFilterModel::Template album( QContent::Album );
    QContentFilterModel::Template artist( album, QContent::Artist );

    QContentFilterModel *model = new QContentFilterModel();

    model->setModelTemplate( album );

Multiple selection

Content filter models may be either single or multiple selection, to make a model multiple selection the QContentFilterModel::CheckList option should be set in the model template, which will allow list items to be checked. The check list option only applies to list items created from the template it was set in and not in any children, in order for all levels of a tree filter model to be able to be checked all the templates must have the check list option set. By default the checked filters are combined using the OR operand, setting the QContentFilterModel::AndCheckedFilters template option will cause the AND operand to be used instead.

If the QContentFilterModel::CheckList option is set a list of default filter arguments may be supplied when adding a list to a template, if the argument of a filter in that list matches one of the default arguments then that filter will will be checked when the list is first populated.

A default select all option may be included in a content filter model by setting either the QContentFilterModel::SelectAll or QContentFilterModel::SelectAll template options in the model template. This will include an option with the text 'All' as the first item in a list defined by a template, if SelectAll is set then the 'All' item will only be displayed if there are two or more items in the list, if ForceAll is set the 'All' item will be shown irregardless of the number of item in a list. If the 'All' item is appears in the root list of a model it will select a null filter and if in a checklist will be automatically checked if no other item is. If it is in a nested list then it will be select its parent item in single selection list or mimic its parent's check state in a multiple selection list.

A template for a checklist of mime types with a select all option:

    QContentFilterModel::Template mimes(
        QContentFilter::MimeType, QString(), QContentFilterModel::SelectAll | QContentFilterModel::CheckList );

See also QContentFilter, QContentFilterSelector, and QContentFilterDialog.

Member Type Documentation

enum QContentFilterModel::TemplateOption
flags QContentFilterModel::TemplateOptions

Provides optional features to be used when generating lists.

QContentFilterModel::NoTemplateOptions0x00Don't display any additional list items or check boxes.
QContentFilterModel::ForceAll0x02Always display a select all option at the start of a list.
QContentFilterModel::SelectAll0x01Display a select all option at the start of a list if there is more than one other item in the list.
QContentFilterModel::CheckList0x04The list is a checklist.
QContentFilterModel::AndCheckedFilters0x08When determining the selected filter filters are and'ed together. By default filters are or'ed.
QContentFilterModel::ShowEmptyLabels0x10Forces labels to be shown irregardless of whether they match any content in the database.

The TemplateOptions type is a typedef for QFlags<TemplateOption>. It stores an OR combination of TemplateOption values.

Member Function Documentation

QContentFilterModel::QContentFilterModel ( QObject * parent = 0 )

Creates a new QContentFilterModel with the given parent.

QContentFilterModel::QContentFilterModel ( QContent::Property property, TemplateOptions options = SelectAll, const QStringList & checked = QStringList(), QObject * parent = 0 )

Creates a new content filter model parented to parent which lists filters for the property property according to the given template options.

The properties listed in the checked list will be checked by default.

QContentFilterModel::QContentFilterModel ( QContentFilter::FilterType type, const QString & scope = QString(), TemplateOptions options = SelectAll, const QStringList & checked = QStringList(), QObject * parent = 0 )

Creates a new content filter model parented to parent which lists filters of type type within the given scope according to the template options.

Any filters with an argument that matches one in the checked list will be checked by default.

QContentFilterModel::~QContentFilterModel ()   [virtual]

Destroys a QContentFilterModel.

QContentFilter QContentFilterModel::baseFilter () const

Returns the base filter of the model. Only filters which return content passed by the base filter will be listed in the view.

See also setBaseFilter().

QContentFilter QContentFilterModel::checkedFilter ( const QModelIndex & parent = QModelIndex() ) const

Returns a filter built from the the checked items that are children of parent.

QContentFilter QContentFilterModel::filter ( const QModelIndex & index ) const

Returns the QContentFilter at index. The returned filter will be and'ed combination of the filter at the index and it's parents, not including the models base filter.

Template QContentFilterModel::modelTemplate () const

Returns the template which the model is constructed from.

See also setModelTemplate().

void QContentFilterModel::setBaseFilter ( const QContentFilter & filter )

Sets the base filter of the model to filter. Only filters which return content passed by the base filter will be listed in the view.

See also baseFilter().

void QContentFilterModel::setModelTemplate ( const Template & modelTemplate )

Sets the template the model is constructed from to modelTemplate.

See also modelTemplate().

Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3