SimpleDataModelTextFilter

Since: The number of children.

#include <bb/extensions/cascades/SimpleDataModelTextFilter>

To link against this class, add the following line to your .pro file: LIBS += -lbbextensionscascadesfilterlistview

Class for filtering GenericDataModel classes.

This is a typical implementation of the DataModelTextFilter class to provide filtering based on different MatchingAlgorithms. It has the following features:

1. Does the filtering in its own thread meaning the UI stays responsive. 2. Does not touch the underlying DataModel 3. Can be canceled at any time 4. Can refilter an already filtered DataModel to increase performance. Whether or not it can do a quick refilter is dependent on the MatchingAlgorithm selected and the change to the filter string. 5. Matches QObject pointers, QVariantMaps, and QStrings. For QStrings property filtering is disabled.

The filtering algorithm used by SimpleDataModelTextFilter is text-based and uses the following logic to choose which DataModel items stay in the ListView.

1. Type Filtering. types is a list of itemTypes containing which item types which are to be checked against for filtering. The type is that which is returned by the DataModel's itemType() method. Only items which have the same itemType will be filtered on. Normally, items whose itemType() property do not match one in the types list are discarded. However, these items can be kept in the DataModel by setting the keepUnmatchedTypes flag. This is useful for example if you have a header type and an item type. You may filter on the item type, and keep the header items in the list. If this types list is empty type filtering is disabled. 2. Property Filtering. If set, a list of properties which are the only properties to be filtered on for the items in the DataModel. For example if you are filtering on contact's last names and each item in the DataModel has a lastName property, you can specify 'lastName' as a property to filter on. The filter will search for that property only. Using this property can greatly increase filtering performance. If not set, all properties are used during filtering.

Using SimpleDataModelTextFilter:

 FilterListView {
       DataModelTextFilter: SimpleDataModelTextFilter {
           matchingAlgorithm: MatchingAlgorithm.Wildcard
       }
       dataModel: XmlDataModel {
         source: "data/data.xml"
     }
     listItemComponents: [
         ...
     ]
 }


Overview

Inheritance

bb::cascades::DataModel
bb::extensions::cascades::DataModelTextFilter
bb::extensions::cascades::SimpleDataModelTextFilter

Public Functions Index

SimpleDataModelTextFilter (QObject *parent=0)
virtual ~SimpleDataModelTextFilter ()
virtual Q_INVOKABLE intchildCount (const QVariantList &indexPath)
virtual Q_INVOKABLE QVariantdata (const QVariantList &indexPath)
virtual Q_INVOKABLE QVariantListfilteredIndexPath (const QVariantList &indexPath)
virtual Q_INVOKABLE boolhasChildren (const QVariantList &indexPath)
virtual Q_INVOKABLE QStringitemType (const QVariantList &indexPath)
Q_INVOKABLE boolkeepUnmatchedTypes () const
Q_INVOKABLE MatchingAlgorithm::TypematchingAlgorithm () const
Q_INVOKABLE QStringListprependedResultTypes () const
Q_INVOKABLE QStringListproperties () const
Q_SLOT voidsetKeepUnmatchedTypes (bool keepUnmatchedTypes)
Q_SLOT voidsetMatchingAlgorithm (MatchingAlgorithm::Type matchingAlgorithm)
Q_SLOT voidsetPrependedResultTypes (const QStringList &prependedResultTypes)
Q_SLOT voidsetProperties (const QStringList &properties)
Q_SLOT voidsetTypes (const QStringList &types)
Q_INVOKABLE QStringListtypes () const
virtual Q_INVOKABLE QVariantListunfilteredIndexPath (const QVariantList &filteredIndexPath)
DataModel (QObject *parent=0)Inherited
DataModelTextFilter (QObject *parent=0)Inherited
DataModelTextFilter (bb::cascades::DataModel *source, const QString &filterString="", QObject *parent=0)Inherited
Q_INVOKABLE QStringfilterString () const Inherited
Q_SLOT voidsetFilterString (const QString &filterString)Inherited
Q_SLOT voidsetSource (bb::cascades::DataModel *source)Inherited
Q_INVOKABLE bb::cascades::DataModel *source ()Inherited

Protected Functions Index

virtual voidfilterStringUpdated (const QString &oldFilterString)
voidkeepUnmatchedTypesUpdated ()
voidpropertiesUpdated ()
virtual voidsourceUpdated (DataModel *oldDataModel)
voidtypesUpdated ()

Signals Index

voidkeepUnmatchedTypesChanged (bool keepUnmatchedTypes)
voidmatchingAlgorithmChanged (bb::extensions::cascades::MatchingAlgorithm::Type matchingAlgorithm)
Q_SIGNAL voidprependedResultTypesChanged (const QStringList &prependedResultTypes)
voidpropertiesChanged (QStringList properties)
voidtypesChanged (QStringList types)
voidfilterCanceled ()Inherited
voidfilterCompleted ()Inherited
voidfilterStarted ()Inherited
voidfilterStringChanged (const QString &filterString)Inherited
voiditemAdded (QVariantList indexPath)Inherited
voiditemMoved (QVariantList fromIndexPath, QVariantList toIndexPath)Inherited
voiditemRemoved (QVariantList indexPath)Inherited
voiditemsChanged (bb::cascades::DataModelChangeType::Type eChangeType=bb::cascades::DataModelChangeType::Init, QSharedPointer< bb::cascades::DataModel::IndexMapper > indexMapper=QSharedPointer< bb::cascades::DataModel::IndexMapper >(0))Inherited
voiditemUpdated (QVariantList indexPath)Inherited
voidsourceChanged (bb::cascades::DataModel *dataModel)Inherited

Properties

bool keepUnmatchedTypes

If performing type-filtering via the types property specify whether to keep unmatched types or not.

Normally, items whose itemType() property do not match one in the types list are discarded. However, these items can be kept in the DataModel by setting the keepUnmatchedTypes flag. For example, this is useful if you have a header type and an entry type. You may filter on the entry type, and keep the header items in the list.

If types is non-empty and a given item does not match any of the specified types, this property specifies whether or not to keep the item in the DataModel or remove it.

bb::extensions::cascades::MatchingAlgorithm::Type matchingAlgorithm

Set the matching algorithm for the filter.

QStringList prependedResultTypes

The prependedResultTypes is a list of types that will be prepended to the DataModel when the DataModel is filtered.

The ListItem objects whose ListItemComponent::type() that is equal to one of the types contained in the prependedResultTypes list will be prepended to the DataModel in the same order as they appear in the prependedResultTypes list. Note that the prependedResultTypes will be prepended only during filtering (i.e. when the filter string is not empty).

The prependedResultTypes are intended to be used by applications that want to add one or more actions at the top of the ListView when the user is filtering. For example, in the contacts application, a typical action will be "add to Contacts", which will add the filterString as a new contact.

The data() for the prependedResultTypes items is a QVariant that contains the filter string.

The following QML example shows how to prepend an action at the top of the FilterListView:

 FilterListView {
        dataModelFilter: SimpleDataModelTextFilter {
            id: numbersDataModelTextFilter
            prependedResultTypes: ["addToContactsType"]
        }
        dataModel: XmlDataModel {
            source: "data/numbers.xml"
        }
        listItemComponents: [
            ListItemComponent {
                type: "addToContactsType"
                Container {
                    StandardListItem {
                        title: "Add to Contacts"
                        description: "Add " + ListItemData + " to contacts"
                        imageSource: "asset:///images/add.png"
                    }
                    onTouch: {
                        filterString = ListItemData
                        addContact(filterString)
                    }
                }
            },
            ListItemComponent {
                type: "normalListItem"
                Container {
                    StandardListItem {
                        title: ListItemData.number
                    }
                }
            }
        ]
    }

QStringList properties

The list of properties to filter on.

If there is already a filter in progress these properties will be updated immediately which is probably not what is wanted. Properties defined here are matched against the keys of a returned QVariantMap, or any property registered to a returned QObject (ie accessible via QObject::property()).

QStringList types

The list of types to filter.

The types property is a list of item types whose properties are checked during filtering.

If the type of an item (returned by DataModel::itemType()) is contained in this list, then the item's properties are tested using the filter. The item is kept if it meets the filtering criteria. If this list is empty, then the properties of all items are tested.

QString filterStringInherited

The string to use as a filter.

Matching is done in a case-insensitive manner.

bb::cascades::DataModel sourceInherited

The source DataModel to pull items from.

Public Functions

SimpleDataModelTextFilter (

Construct a SimpleDataModelTextFilter instance.

Parameters
parent

The adapter owner, or 0. Optional and will default to 0 if not specified.

virtual~SimpleDataModelTextFilter ()

Destructor.

virtual Q_INVOKABLE int childCount (

Returns the number of children of the data item specified by indexPath.

Parameters
indexPath

The index path to the data item to get child count for.

Return:

The number of children.

virtual Q_INVOKABLE QVariant data (

Returns the data item that is associated with indexPath.

This function transfers ownership for QObject objects, if the returned object doesn't have any parent.

The ListView will pass the data item as a parameter to ListItemManager::updateItem(). If item visuals are created by using ListItemComponent in QML, ListView makes the data returned from this function available in the item visuals as the context property ListItemData, and also as the property ListItem.data attached to the item visual root node.

Parameters
indexPath

The index path to the data item.

Return:

The data item associated with the indexPath. The caller must take ownership of any returned QObject objects, if the returned object doesn't already have a parent.

See also:

ListItemManager

virtual Q_INVOKABLE QVariantList filteredIndexPath (

Fetch the filtered index path for the requested true index path.

Parameters
indexPath

The index path to find the filtered index path of

Return:

The filtered index path for the requested index path An empty QVariantList is returned if indexPath does not exist in the filtered result set.

virtual Q_INVOKABLE bool hasChildren (

Indicates whether the data item specified by indexPath has children.

ListView never calls this function for its root node (but does call childCount(QVariantList) for the root node), so if this DataModel only contains one level of items (no child items), this function can always return false.

Parameters
indexPath

The index path to the data item to query for children.

Return:

true if the data item has one or more children, false otherwise.

virtual Q_INVOKABLE QString itemType (

Returns the item type for the data item at indexPath.

The item type will then be used when the ListView requests items from its ListItemManager.

If a ListItemTypeMapper has been provided to a ListView, the ListView calls ListItemTypeMapper::itemType() instead of DataModel::itemType().

Parameters
indexPath

The index path to the data item.

Return:

A string representing the user-defined type of the item. The default implementation returns an empty string.

Q_INVOKABLE bool keepUnmatchedTypes ()

Retrieve whether or not to keep unmatched types.

This only takes effect when the types property is non-empty.

Return:

True if unmatched types are to be kept in the DataModel, false otherwise

Q_INVOKABLE MatchingAlgorithm::Type matchingAlgorithm ()

Return the matching algorithm.

Return:

The currently set matching algorithm

Q_INVOKABLE QStringList prependedResultTypes ()

Returns the list of types that will be prepended to the DataModel during filtering.

See the documentation for the prependedResultTypes property for more details.

Q_INVOKABLE QStringList properties ()

Retrieve the list of properties to filter on.

Return:

A list of properties to filter on

Q_SLOT void setKeepUnmatchedTypes (
  • boolkeepUnmatchedTypes)

Specify whether to keep unmatched types in the DataModel.

Parameters
keepUnmatchedTypes

True to keep unmatched types or False otherwise

Q_SLOT void setMatchingAlgorithm (

Set the matching algorithm to matchingAlgorithm.

Parameters
matchingAlgorithm

The matching algorithm to set

Q_SLOT void setPrependedResultTypes (

Sets the list of types to prepend to the DataModel during filtering.

See the documentation for the prependedResultTypes property for more details.

Parameters
prependedResultTypes

The list of types to prepend.

Q_SLOT void setProperties (

Specify the list of properties to filter on.

If there is already a filter in progress setting these properties will restart the filter.

Parameters
properties

The list of properties to filter on

Q_SLOT void setTypes (

Specify the list of types to filter.

If there is already a filter in progress setting these types will restart the filter.

Parameters
types

The list of types to filter

Q_INVOKABLE QStringList types ()

Retrieve the list of types to filter.

Return:

A list of types to filter

virtual Q_INVOKABLE QVariantList unfilteredIndexPath (

Fetch the true index path for the requested filtered index path.

Parameters
filteredIndexPath

The filtered index path to find the index path of

Return:

The index path for the requested filtered index path An empty QVariantList is returned if filteredIndexPath does not exist.

DataModel (Inherited

Constructs a DataModel instance with the specified parent.

Parameters
parent

The data model owner, or 0. Optional and will default to 0 if not specified.

Since:

BlackBerry 10.0.0

DataModelTextFilter (Inherited

Construct a DataModelTextFilter instance.

Parameters
parent

The object's parent, or 0. Optional and will default to 0 if not specified. The parent takes responsibility for this object (ie this object is added to the parent's child list).

DataModelTextFilter (Inherited

Construct a DataModelTextFilter instance with the provided source and filterString.

Parameters
source

The DataModel to filter. If source has no parent, this DataModelTextFilter takes ownership of it and sets itself as parent to it (which means that DataModelTextFilter deletes it when DataModelTextFilter is deleted).

filterString

The string to filter on. Will default to "" if not specified

parent

The object's parent, or 0. Optional and will default to 0 if not specified. The parent takes responsibility for this object (ie this object is added to the parent's child list).

Q_INVOKABLE QString filterString ()Inherited

Retrieve the Filter string.

Return:

The Filter string

Q_SLOT void setFilterString (Inherited

Specify the Filter string.

Parameters
filterString

The string to Filter on

Q_SLOT void setSource (Inherited

Specify the Data Model.

If source has no parent, this DataModelTextFilter takes ownership of it and sets itself as parent to it (which means that DataModelTextFilter deletes it when DataModelTextFilter is deleted). Any previously set source is unaffected by this call, its parent won't change and it won't be deleted as a result of calling setSource().

Parameters
source

The DataModel to filter

Q_INVOKABLE bb::cascades::DataModel * source ()Inherited

Retrieve the Data Model.

Ownership of the returned object is not transferred.

Return:

The Data Model

Protected Functions

virtual void filterStringUpdated (

Override the parent's virtual method to stay notified of changes to the filterString.

Parameters
oldFilterString

The old filterString

void keepUnmatchedTypesUpdated ()

Called when there are changes to the keep unmatched types property.

void propertiesUpdated ()

Called when there are changes to the properties list.

virtual void sourceUpdated (
  • DataModel *oldDataModel)

Override the parent's virtual method to stay notified of changes to the source DataModel.

Parameters
oldDataModel

The old data model

void typesUpdated ()

Called when there are changes to the types list.

Signals

void keepUnmatchedTypesChanged (
  • boolkeepUnmatchedTypes)

Emitted when the value of keepUnmatchedTypes changes.

Parameters
keepUnmatchedTypes

The new value

void matchingAlgorithmChanged (

Emitted when the value of matchingAlgorithm changes.

Parameters
matchingAlgorithm

The new matching algorithm

Q_SIGNAL void prependedResultTypesChanged (

Emitted when the prependedResultTypes is changed.

Parameters
prependedResultTypes

The new list of types to prepend during filtering.

See the documentation for the prependedResultTypes property for more details.

void propertiesChanged (

Emitted when the list of properties has changed.

Parameters
properties

The new list of properties

void typesChanged (

Emitted when the list of types has changed.

Parameters
types

The new list of types

void filterCanceled ()Inherited

Emitted when the filtering has been canceled.

void filterCompleted ()Inherited

Emitted when the filtering has finished.

void filterStarted ()Inherited

Emitted when the filtering starts.

void filterStringChanged (Inherited

Emitted when the filterString has changed.

Parameters
filterString

The new filterString

void itemAdded (Inherited

Emitted when a data item has been added to this DataModel.

Parameters
indexPath

The index path to the new item.

Since:

BlackBerry 10.0.0

void itemMoved (Inherited

Emitted when a data item has been moved within the DataModel.

A moved item will retain its visual appearance and data on the server.

Parameters
fromIndexPath

The original index path of the moved item.

toIndexPath

The new index path of the moved item.

Since:

BlackBerry 10.3.0

void itemRemoved (Inherited

Emitted when a data item has been removed from this DataModel.

Parameters
indexPath

The index path to the removed item.

Since:

BlackBerry 10.0.0

void itemsChanged (Inherited

Emitted when the model has changed in a way that would be inefficient to describe with single instances of the other signals.

No other signals (DataModel::itemAdded, DataModel::itemUpdated, or DataModel::itemRemoved) are emitted if this signal is emitted when a change occurs in this DataModel.

Typical examples of when this signal is emitted: data has been sorted (so that many items have changed places), the DataModel has been cleared (all items have been removed), or a batch of items has been added.

If eChangeType is DataModelChangeType::Init, or if eChangeType is DataModelChangeType::AddRemove and indexMapper is 0, a ListView reacts to this signal by releasing all of the items in its cache.

If eChangeType is AddRemove and an IndexMapper is provided, the ListView instead calls IndexMapper::newIndexPath() for each item in its cache.

If eChangeType is DataModelChangeType::Update, a ListView reacts to this signal by calling DataModel::data() again for every item in its cache.

Parameters
eChangeType

The type of change.

indexMapper

An index mapper that contains update information.

Since:

BlackBerry 10.0.0

void itemUpdated (Inherited

Emitted when a data item in this DataModel has been updated.

Parameters
indexPath

IndexPath to the updated item.

Since:

BlackBerry 10.0.0

void sourceChanged (Inherited

Emitted when the source has changed.

Parameters
dataModel

The new source DataModel

Last modified: 2015-07-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus