/*

 * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). 

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  CPosLandmarkCategory class

 *

 */

 #ifndef CPOSLANDMARKCATEGORY_H

 #define CPOSLANDMARKCATEGORY_H

 #include <e32base.h>

 #include "EPos_Landmarks.h"

 /**

 *  Landmark category.

 *

 *  A landmark database can contain a number of categories which can be

 *  assigned to the landmarks in the database. A landmark can be associated

 *  with multiple categories, e.g. a landmark can be a "Restaurant" and a "Pub".

 *  Categories also enable filtered searches, e.g. a client could search for

 *  nearby restaurants.

 *

 *  This class specifies the landmark category attributes, i.e. name, icon and

 *  a global category identifier. Global categories enable a uniform

 *  categorization across multiple databases.

 *

 *  A landmark category is created, updated or deleted by using functions in

 *  @ref CPosLmCategoryManager.

 *

 *  @lib eposlandmarks.lib

 *  @since S60 3.0

 */

 class CPosLandmarkCategory : public CBase

     {

     public:

         /**

         *  Bitmap for specifying a group of category attributes. Bit values are

         *  defined by @ref _TAttributes.

         */

         typedef TUint32 TAttributes;

         /**

         *  Specifies a category attribute, such as category name or category icon.

         */

         enum _TAttributes

             {

             ENoAttribute        = 0x0000  /**<

                 No attribute specified. */,

             ECategoryName       = 0x0001  /**<

                 The name of the landmark category. */,

             EIcon               = 0x0010  /**<

                 The icon that represents the category in a UI. */,

             EAllAttributes      = 0xFFFF  /**<

                 All category attributes. */

             };

     public:

         /**

         * Two-phased constructor.

         * @returns A new instance of this class.

         */

         IMPORT_C static CPosLandmarkCategory* NewLC();

         /**

         * Two-phased constructor.

         * @returns A new instance of this class.

         */

         IMPORT_C static CPosLandmarkCategory* NewL();

         /**

         * Two-phased copy constructor.

         *

         * @param[in] aCategory The category to copy.

         * @returns A copy of the specified category object.

         */

         IMPORT_C static CPosLandmarkCategory* NewLC(

                const CPosLandmarkCategory&  aCategory

         );

         /**

         * Two-phased copy constructor.

         *

         * @param[in] aCategory The category to copy.

         * @returns A copy of the specified category object.

         */

         IMPORT_C static CPosLandmarkCategory* NewL(

                const CPosLandmarkCategory&  aCategory

         );

         /**

         * Destructor.

         */

         virtual ~CPosLandmarkCategory();

     public:

         /**

         * Reads the ID of the category entry in the database.

         *

         * @returns The ID of the category entry in the database, or

         *   @p KPosLmNullItemId if the category has not been added to the

         *   database yet.

         */

         IMPORT_C TPosLmItemId CategoryId() const;

         /**

         * Retrieves global category ID.

         *

         * Global categories enable a uniform categorization across multiple

         * databases.

         *

         * @returns The global category ID or @p KPosLmNullGlobalCategory if the

         *   category is not global.

         */

         IMPORT_C TPosLmGlobalCategory GlobalCategory() const;

         /**

         * @internal */

         /*

         * Sets the category to be global (i.e. not only defined in one

         * database).

         *

         * Global categories enable a uniform categorization across multiple

         * databases.

         *

         * @param[in] aGlobalCategory The global category ID or

         *   @p KPosLmNullGlobalCategory if the category should not be global.

         */

         void SetGlobalCategory(

                TPosLmGlobalCategory  aGlobalCategory

         );

         /**

         * Reads the name of the landmark category.

         *

         * @param[out] aCategoryName Will contain the category name.

         * @returns @p KErrNone if successful, @p KErrNotFound if the category

         *   name is not set.

         */

         IMPORT_C TInt GetCategoryName(

                TPtrC&  aCategoryName

         ) const;

         /**

         * Sets the name of the landmark category.

         *

         * @param[in] aCategoryName The category name.

         *

         * @leave KErrArgument Client passed an empty descriptor or landmark name 

         *   is longer than @p KPosLmMaxCategoryNameLength.

         */

         IMPORT_C void SetCategoryNameL(

                const TDesC&  aCategoryName

         );

         /**

         * Associates the landmark category with an icon.

         *

         * Icons are found in icon files. To set an icon, the client

         * must specify the name of the icon file and the index of the

         * icon within the file.

         *

         * The landmark is not affected if the icon file is changed or

         * removed. It only contains a link to the icon.

         *

         * @param[in] aIconFileName The full icon file name.

         * @param[in] aIconIndex The index of the icon within the icon file.

         * @param[in] aIconMaskIndex The index of the icon mask within the

         *   icon file.

         *

         * @leave KErrArgument The icon file name is longer than @p KMaxFileName.

         *

         * @panic "Landmarks Client"-EPosLmInvalidArgument The icon index is negative or

         *   icon mask index is negative and not equal to @p KPosLmIconMaskNotUsed.

         */

         IMPORT_C void SetIconL(

                const TDesC&  aIconFileName,

                TInt  aIconIndex,

                TInt  aIconMaskIndex

         );

         /**

         * Returns the a link to the icon associated with the landmark category.

         *

         * Icons are found in icon files. It is referenced by the name of

         * the icon file and the index of the icon within the file.

         *

         * The landmark category is not affected if the icon file is

         * changed or removed. It only contains a link to the icon. This means

         * that the link could be invalid.

         *

         * @param[out] aIconFileName The full icon file name.

         * @param[out] aIconIndex The index of the icon within the icon file.

         * @param[out] aIconMaskIndex The index of the icon mask within the

         *   icon file. If no icon mask index is defined @p KPosLmIconMaskNotUsed

         *   is returned.

         *

         * @returns @p KErrNone if successful, @p KErrNotFound if the icon is

         *   not set.

         */

         IMPORT_C TInt GetIcon(

                TPtrC& aIconFileName,

                TInt& aIconIndex,

                TInt& aIconMaskIndex

         ) const;

         /**

         * Removes category attributes from the landmark category.

         *

         * @param[in] aAttributes A bitmap specifying which category attributes to

         *   remove.

         */

         IMPORT_C void RemoveCategoryAttributes(

                TAttributes aAttributes

         );

         /**

         * @internal */

         /*

         * Sets the category ID to the landmark category.

         *

         * @param[in] aId The category ID to set.

         */

         void SetCategoryIdL(

                TPosLmItemId aId

         );

     private:

         // C++ constructor

         CPosLandmarkCategory();

         void ConstructL();

         void ConstructL(const CPosLandmarkCategory& aCategory);

         // Prohibit copy constructor

         CPosLandmarkCategory(const CPosLandmarkCategory&);

         // Prohibit assigment operator

         CPosLandmarkCategory& operator= (const CPosLandmarkCategory&);

     private:

         // Category ID

         TPosLmItemId iId;

         // Global category

         TPosLmGlobalCategory iGlobalCategory;

         // Category label

         HBufC* iCategoryName;

         // Category icon filename

         HBufC* iIconFileName;

         // Category icon index

         TInt iIconIndex;

         // Category icon mask index

         TInt iIconMaskIndex;

     };

 #endif      // CPOSLANDMARKCATEGORY_H