diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/mw/EPos_CPosLandmarkCategory.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/epoc32/include/mw/EPos_CPosLandmarkCategory.h Wed Mar 31 12:33:34 2010 +0100 @@ -0,0 +1,279 @@ +/* +* 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 +#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 + +