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);
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);
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
| QCategoryDialog | Allows users to select Categories with a dialog interface |
|---|
| QCategoryFilter | Allows consistent filtering of records or objects that have a set of categories assigned |
|---|
| QCategoryManager | Set of functions to create, modify, and remove categories |
|---|
| QCategorySelector | Allows users to select categories for filtering or for applying to an item |
|---|
