Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

Categories

Overview

Qt Extended provides classes for managing categories, filtering on categories and selecting categories.

For most cases, QCategorySelector is all that you will need. It supports filtering and selecting behaviors. It also provides an interface to the user that lets them edit categories. For manual control of categories QCategoryManager is provided.

Category Ids

The user deals with visible category strings. Users can change the name of a user category and system categories can have their visible strings change when the system language changes. To handle this gracefully applications should use category ids. QCategoryManager provides functions to convert category ids to visible strings. QCategorySelector deals with category ids and converts to visible strings for display to the user.

User Categories

User categories are created by the user. They have a generated id and will remain the same when the system language changes. User categories can be edited and removed by the user. Since QCategorySelector provdes an interface for the user to create categories applications should not need to add user categories manually. If this is required, applications should use QCategoryManager::add().

System Categories

System categories are created by applications. They have a known id and may change their visible text when the system language changes. System categories cannot be edited or removed once added because that may lead to data inconsistencies. Applications that want to assign their own categorizations to data should create system categories using QCategoryManager::addCategory().

Here is an example of how an application would create a system category to assign to content items.

    QCategoryManager cats("Documents");
    bool ok = cats.ensureSystemCategory("com.trolltech.Camera", "Camera");
    Q_ASSERT(ok); // only fails if there's a problem with the database

    QContent newPhoto;
    newPhoto.setCategories( QStringList() << "com.trolltech.Camera" );

Because QCategoryManager::ensureSystemCategory() must always work it will overwrite any exising category with the same id. Care should be taken to ensure that the category ids used are unique. In order to prevent this function from overwriting user categories the QCategoryManager::add() function prepends "user." to the category ids it generates and the QCategoryManager::ensureSystemCategory() function fails when it is passed an id that starts with "user.". For example, the following code will fail.

    QCategoryManager cats("Documents");
    QString id = cats.add("Camera");
    bool ok = cats.ensureSystemCategory(id, "Camera");
    Q_ASSERT(ok); // fails

To handle translation of the system category you will need to take additional steps. See Translating Categories for details.

Scoping

All categories live in a scope. Scopes are defined by applications and there is also a global scope. All applications can see categories in the global scope but they cannot see categories in another scope unless they specifically request to do so. Both QCategoryManager and QCategorySelector can be created with a scope.

There are some important limitations with categories and scopes.

• A category id can exist in only 1 scope.
• Applications can see only the global scope and one other scope.

The user can create multiple categories of the same name in different scopes because each category will have a different id. However system categories have known ids so care should be taken when deciding which scope to place a system category in.

Content items can use the "Documents" scope. Several Qt Extended applications create system categories in this scope to assign to content items.

Classes