Class CQikCategoryModel

class CQikCategoryModel : public CBase;

Description

Category model.

Categories are groups of related data. An application can filter its view to show only the items belonging to a particular category — the available categories are specific to each application. Each category has a name, by which it is known to the application user, and a handle which identifies it to the application.

An object of this class is used by the CQikAppUi to hold data about the categories (folders to end users) that an application can use to group its items. To categorise an application item, the application should associate that item with the category handle taken from this model. A category handle is a number that is unique to a category.

When changes are made to the data in this model using e.g. the Edit Categories dialogs, the application is notified about the changes through the MQikEditCategoryObserver . When a user changes category using the category menu pane, the application is notified automatically, see CQikViewBase::SetCategoryModelAsCommandsL().

QikCategoryUtils provides methods to initialise a category model from an ini file or resource file, and to externalise to an ini file.

Derivation

• CBase - Base class for all classes to be instantiated on the heap
• CQikCategoryModel - Category model

Members

Defined in CQikCategoryModel:
AddCategoryL(), AddCategoryL(), AddObserverL(), AppDefinedFlags(), CanCategoryBeDeleted(), CanCategoryBeRenamed(), CategoryHandle(), CategoryHandle(), CategoryIndex(), CategoryNameByHandle(), CategoryNameByIndex(), CategorySortedAs(), CheckModelIntegrity(), ConstructFromResourceL(), CountCategories(), DeleteCategoryL(), DeleteOnlyEmpty(), ENameAlreadyExist, ENameIsOK, ENameNoChange, ENameNotAllowed, ExternalizeL(), HandleOfAllCategory(), HandleOfUnfiledCategory(), InternalizeL(), IsCategoryDimmedInMenu(), IsCategoryHiddenInList(), NewL(), NewLC(), RemoveObserver(), RenameCategoryL(), SetCategoryDeleteable(), SetCategoryDimmedInMenu(), SetCategoryHiddenInList(), SetCategoryRenameable(), SetCategorySortedAs(), SetDeleteOnlyEmpty(), SetSorted(), Sorted(), TValidateNameResult, ValidCategoryName(), ~CQikCategoryModel()

Inherited from CBase:
Delete(), Extension_(), operator new()

See also:

• MQikEditCategoryObserver
• MQikCategoryModelObserver
• CQikAppUi
• CQikViewBase

static IMPORT_C CQikCategoryModel *NewL();

Description

Allocates and constructs a CQikCategoryModel object cleaning the cleanUp stack.

Return value

CQikCategoryModel * pointer to the created CQikCategoryModel object

See also:

• NewLC()
• CQikCategoryModel()
• ConstructFromResourceL()

static IMPORT_C CQikCategoryModel *NewLC();

Description

Allocates and constructs a CQikCategoryModel object leaving the pointer to it on the cleanup stack.

Return value

CQikCategoryModel * Pointer to the newly created CQikCategoryModel object.

See also:

• NewL()
• CQikCategoryModel()
• ConstructFromResourceL()

IMPORT_C ~CQikCategoryModel();

Description

Destructor. The destructor frees all memory owned by this object prior to its destruction.

IMPORT_C void SetSorted(TBool aSort);

Description

Sets category sorting as active. The function may also be used to disable sorting, by passing EFalse to the argument.

If category sorting is active, categories are re-sorted whenever a category is added, deleted or renamed.

If the function is called with ETrue , the function immediately sorts the categories.

Parameters

TBool aSort ETrue to activate category sorting, EFalse to disable sorting.

See also:

• Sorted()

IMPORT_C TBool Sorted() const;

Description

Tests whether the categories are currently sorted.

Return value

TBool ETrue if the categories are sorted, otherwise EFalse .

See also:

• SetSorted()

IMPORT_C void SetDeleteOnlyEmpty(TBool aDelete);

Description

Sets the delete only empty category attribute. Once set, only categories with no items may be deleted.

Parameters

TBool aDelete ETrue to ensure only empty categories can be deleted, EFalse to allow any category to be deleted.

See also:

• DeleteOnlyEmpty()

IMPORT_C TBool DeleteOnlyEmpty() const;

Description

Tests whether only empty categories may be deleted.

Return value

TBool ETrue if only categories with no items may be deleted, otherwise EFalse .

See also:

• SetDeleteOnlyEmpty()

IMPORT_C TInt CountCategories() const;

Description

Gets the number of categories in the model. This is used when iterating over all categories.

Return value

TInt The number of categories in the model.

IMPORT_C const TQikCategoryName &CategoryNameByIndex(TInt aIndex) const;

Description

Gets the name of the category at the specified index. Categories are ordered in category lists, the index indicates the position of a category in the category list

Parameters

TInt aIndex The index for which the category name is required.

Return value

const TQikCategoryName & The name of the specified category.

IMPORT_C TInt CategoryHandle(TInt aIndex) const;

Description

Gets the handle of the category at the specified index. The handle is a number that is unique to each category and is used to group data belonging to the category.

Parameters

TInt aIndex The index for which the category handle is required.

Return value

TInt The category handle.

See also:

• CategoryHandle()
• CategoryNameByHandle()
• CategoryIndex()

IMPORT_C TInt CategoryHandle(const TDesC &aCategoryName) const;

Description

Gets the handle of the category with the specified name. The handle is used to group data belonging to the category.

Parameters

const TDesC &aCategoryName The name of the category for which the handle is required.

Return value

TInt The category handle.

See also:

• CategoryHandle()
• CategoryNameByHandle()
• CategoryIndex()

IMPORT_C const TQikCategoryName &CategoryNameByHandle(TInt aHandle) const;

Description

Gets the category name using the specified handle.

Parameters

TInt aHandle The handle of the category for which the name is required. Panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle.

Return value

const TQikCategoryName & The category name.

See also:

• CategoryNameByHandle()
• CategoryHandle()
• CategoryIndex()

IMPORT_C TInt HandleOfAllCategory() const;

Description

Gets the handle of the "All" category.

All application items can be accessed using the All category.

Return value

TInt The handle of the All category, or KErrNotFound if there are no categories.

See also:

• HandleOfUnfiledCategory()

IMPORT_C TInt HandleOfUnfiledCategory() const;

Description

Gets the handle of the "Unfiled" category.

Applications items which are not explicitly assigned a category are automatically assigned the unfiled category.

Return value

TInt The handle of the unfiled category, or KErrNotFound if there are no categories.

See also:

• HandleOfAllCategory()

IMPORT_C TInt CategoryIndex(TInt aHandle) const;

Description

Gets the index of the category with the specified handle.

Parameters

TInt aHandle The category handle for which the index is to be found.

Return value

TInt The index of the specified handle, or KErrNotFound if it does not exist.

See also:

• CategoryNameByHandle()
• CategoryHandle()
• CategoryNameByHandle()

IMPORT_C TBool IsCategoryHiddenInList(TInt aIndex) const;

Description

Tests whether the specified category is hidden in the category edit list. This is always true for the 'All' and "Unfiled" categories as they cannot be removed, and so should be excluded from the category edit list.

Parameters

TInt aIndex The index of the category to test.

Return value

TBool ETrue if the category is hidden, otherwise EFalse

See also:

• SetCategoryHiddenInList()

IMPORT_C void SetCategoryHiddenInList(TInt aHandle, TBool aHidden);

Description

Sets the specified category as hidden. The function can also be used to set the category as not hidden in the list. The All and Unfiled categories are always hidden in the edit list.

Parameters

TInt aHandle The handle of the category to be set as hidden or not hidden. Panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle. TBool aHidden ETrue to hide the category, EFalse to set it as not hidden.

See also:

• IsCategoryHiddenInList()

IMPORT_C TBool CanCategoryBeRenamed(TInt aHandle) const;

Description

Tests whether the specified category can be renamed.

Parameters

TInt aHandle The handle of the category to test. Panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle.

Return value

TBool ETrue if the category can be renamed, otherwise EFalse .

See also:

• RenameCategoryL()
• SetCategoryRenameable()

IMPORT_C void SetCategoryRenameable(TInt aHandle, TBool aRenameable);

Description

Sets the specified category so that it is either possible, or not possible to rename it. This function clears the EQikCategoryCantBeRenamed flag.

Parameters

TInt aHandle The handle of the category to be set so that it is either possible, or not possible to rename it. Panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle. TBool aRenameable ETrue to set the category as renameable, EFalse to set it as not renameable.

See also:

• RenameCategoryL()
• CanCategoryBeRenamed()

IMPORT_C TBool CanCategoryBeDeleted(TInt aHandle) const;

Description

Tests whether a specified category can be deleted.

Parameters

TInt aHandle The handle of the category to test. Panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle.

Return value

TBool ETrue if the category can be deleted, otherwise EFalse .

See also:

• DeleteCategoryL()
• SetCategoryDeleteable()

IMPORT_C void SetCategoryDeleteable(TInt aHandle, TBool aDeleteable);

Description

Sets the specified category so that it is either possible, or not possible, to delete it.

This function clears the EQikCategoryCantBeDeleted flag if aDeleteable is EFalse .

This function sets the EQikCategoryCantBeDeleted flag if aDeleteable is ETrue .

Parameters

TInt aHandle The handle of the category to set as possible, or not possible, to be deleted. Panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle. TBool aDeleteable ETrue to set the category as deleteable, EFalse to set it as not deleteable.

See also:

• DeleteCategoryL()
• CanCategoryBeDeleted()

IMPORT_C TBool IsCategoryDimmedInMenu(TInt aHandle) const;

Description

Tests whether the specified category is dimmed when displayed in the category menu pane.

Parameters

TInt aHandle The handle of the category to test. Panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle.

Return value

TBool ETrue if the category is dimmed, otherwise EFalse .

See also:

• SetCategoryDimmedInMenu()

IMPORT_C void SetCategoryDimmedInMenu(TInt aHandle, TBool aDimmed);

Description

Sets the specified category as dimmed, or undimmed, in the menu.

Parameters

TInt aHandle The handle of the category to be dimmed or un-dimmed. Panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle. TBool aDimmed ETrue to dim the category, EFalse to un-dim.

See also:

• IsCategoryDimmedInMenu()

IMPORT_C TInt16 CategorySortedAs(TInt aHandle);

Description

Gets the sorting value of the specified category. To turn sorting off, use the SetSorted() method.

Categories are ordered in category lists using the sorting value. Categories with lower values appear before categories with higher values. Categories with the same sorting value are sorted in descending alphabetical order.

If category sorting is active, categories are re-sorted whenever a category is added, deleted or renamed.

The default sorting value is zero. If more than one category has the same value then they are sorted in descending alphabetical order.

This function panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle.

Parameters

TInt aHandle The handle of the category for which the sorting value is required.

Return value

TInt16 The sorting value of the category. Can be negative.

IMPORT_C void SetCategorySortedAs(TInt aHandle, TInt16 aSortedAs);

Description

Sets the sorting value of the specified category. To turn sorting off, use the SetSorted() method.

Categories are ordered in category lists using the sorting value. Categories with lower values appear before categories with higher values. Categories with the same sorting value are sorted in descending alphabetical order.

The default sorting value is zero. If all categories have the default value then they are sorted in descending alphabetical order.

Parameters

TInt aHandle The handle of the category for which the sorting value is to be set. Panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle. TInt16 aSortedAs The new sorting value of the category.

IMPORT_C TInt32 &AppDefinedFlags(TInt aHandle);

Description

Sets and gets an application specific value of a category. The value can be any 32-bit flag, index, or other value that the application needs to associate with the category.

Parameters

TInt aHandle The handle of the category for which a reference to the application defined data value is returned.

Return value

TInt32 & A reference to the application defined 32-bit data of the category.

IMPORT_C TValidateNameResult ValidCategoryName(const TDesC &aName, const TDesC *aOldName=0) const;

Description

Validates a category name.

Evaluates aName and determines if it valid. The default implementation allows any category name, provided it is not already used or it is not allowed (e.g. "All" and “Unfiled”).

The category name aName is tested to ensure that:

• The string is not empty.

• The name does not already exist as either a hidden, or unhidden, category name.

• The new name is not the same as the old name, if aOldName is supplied.

Parameters

const TDesC &aName The name to be validated. const TDesC *aOldName The old category name if renaming the category.

Return value

TValidateNameResult The result of the name validation. See TValidateNameResult enum.

IMPORT_C void ConstructFromResourceL(TResourceReader &aReader);

Description

Second phase construction from a resource.

This function completes the construction of a newly-allocated category model by reading categories from a QIK_CATEGORY resource or an INI file. Normally called indirectly, by QikCategoryUtils functions.

Parameters

TResourceReader &aReader A resource file reader.

See also:

• CCoeControl::ConstructFromResourceL()

IMPORT_C void InternalizeL(RReadStream &aStream);

Description

Internalises a category model object from a read stream. The presence of this function means that the standard templated operator>>() is available to internalise objects of this class. Normally called indirectly, by QikCategoryUtils functions.

Parameters

RReadStream &aStream Stream from which the object should be internalised.

See also:

• ExternalizeL()

IMPORT_C void ExternalizeL(RWriteStream &aStream) const;

Description

Externalises a category model to a stream. The presence of this function means that the standard templated operator<<() is available to externalise objects of this class. Normally called indirectly, by QikCategoryUtils functions.

Parameters

RWriteStream &aStream Stream to which the object should be externalised.

See also:

• InternalizeL()

IMPORT_C TInt &AddCategoryL(const TDesC &aName, TInt16 aFlags=0);

Description

Adds a category to the model and returns a unique handle.

Parameters

const TDesC &aName The new category name. TInt16 aFlags Flags for the category being added. See Category flags.

Return value

TInt & A unique handle for the new category. This reference can be used to change the handle if the application prefers a different one to that generated. This must happen immediately — the reference cannot be stored and used for changing the handle later.

See also:

• AddCategoryL()
• DeleteCategoryL()

IMPORT_C TInt &AddCategoryL(TInt aHandle, const TDesC &aName, TInt16 aFlags=0);

Description

Adds a category to the model. In this overload the handle is specified — it is up to the caller to ensure that handles are unique. CheckModelIntegrity() can be used to ensure no two categories have the same handle.

Parameters

TInt aHandle The handle for the new category. const TDesC &aName The name for the new category. TInt16 aFlags Category flags. These include EQikCategoryAll etc.

Return value

TInt & If successful this is the same as aHandle .

See also:

• AddCategoryL()
• DeleteCategoryL()
• RenameCategoryL()

IMPORT_C void DeleteCategoryL(TInt aHandle);

Description

Deletes a specified category.

Parameters

TInt aHandle The handle of the category to be deleted. Panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle.

See also:

• AddCategoryL()
• RenameCategoryL()
• SetCategoryDeleteable()
• CanCategoryBeDeleted()

IMPORT_C void RenameCategoryL(TInt aHandle, const TDesC &aNewName);

Description

Renames the specified category.

Parameters

TInt aHandle The handle of the category to be renamed. Panics with EQikPanicCategoryHandleNotFound if no category exists with the specified handle. const TDesC &aNewName The new name of the category.

See also:

• DeleteCategoryL()
• SetCategoryRenameable()
• CanCategoryBeRenamed()

IMPORT_C TBool CheckModelIntegrity() const;

Description

Tests that no categories have the same handle.

Return value

TBool ETrue if no two categories have the same handle, otherwise EFalse .

IMPORT_C void AddObserverL(MQikCategoryModelObserver *aObserver);

Description

Parameters

MQikCategoryModelObserver *aObserver

IMPORT_C void RemoveObserver(MQikCategoryModelObserver *aObserver);

Description

Parameters

MQikCategoryModelObserver *aObserver

TValidateNameResult

Description

Category name validation flags. These are returned by ValidCategoryName() to indicate whether or not a new category name is valid.

ENameIsOK The name is OK. ENameNotAllowed The name is not allowed. ENameAlreadyExist The name already exists. ENameNoChange The new name is the same as the old name.