1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/EPos_CPosLandmarkCategory.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,279 @@
1.4 +/*
1.5 +* Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: CPosLandmarkCategory class
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef CPOSLANDMARKCATEGORY_H
1.23 +#define CPOSLANDMARKCATEGORY_H
1.24 +
1.25 +#include <e32base.h>
1.26 +#include "EPos_Landmarks.h"
1.27 +
1.28 +
1.29 +/**
1.30 +* Landmark category.
1.31 +*
1.32 +* A landmark database can contain a number of categories which can be
1.33 +* assigned to the landmarks in the database. A landmark can be associated
1.34 +* with multiple categories, e.g. a landmark can be a "Restaurant" and a "Pub".
1.35 +* Categories also enable filtered searches, e.g. a client could search for
1.36 +* nearby restaurants.
1.37 +*
1.38 +* This class specifies the landmark category attributes, i.e. name, icon and
1.39 +* a global category identifier. Global categories enable a uniform
1.40 +* categorization across multiple databases.
1.41 +*
1.42 +* A landmark category is created, updated or deleted by using functions in
1.43 +* @ref CPosLmCategoryManager.
1.44 +*
1.45 +* @lib eposlandmarks.lib
1.46 +* @since S60 3.0
1.47 +*/
1.48 +class CPosLandmarkCategory : public CBase
1.49 + {
1.50 + public:
1.51 +
1.52 + /**
1.53 + * Bitmap for specifying a group of category attributes. Bit values are
1.54 + * defined by @ref _TAttributes.
1.55 + */
1.56 + typedef TUint32 TAttributes;
1.57 +
1.58 + /**
1.59 + * Specifies a category attribute, such as category name or category icon.
1.60 + */
1.61 + enum _TAttributes
1.62 + {
1.63 + ENoAttribute = 0x0000 /**<
1.64 + No attribute specified. */,
1.65 + ECategoryName = 0x0001 /**<
1.66 + The name of the landmark category. */,
1.67 + EIcon = 0x0010 /**<
1.68 + The icon that represents the category in a UI. */,
1.69 + EAllAttributes = 0xFFFF /**<
1.70 + All category attributes. */
1.71 + };
1.72 +
1.73 + public:
1.74 +
1.75 + /**
1.76 + * Two-phased constructor.
1.77 + * @returns A new instance of this class.
1.78 + */
1.79 + IMPORT_C static CPosLandmarkCategory* NewLC();
1.80 +
1.81 + /**
1.82 + * Two-phased constructor.
1.83 + * @returns A new instance of this class.
1.84 + */
1.85 + IMPORT_C static CPosLandmarkCategory* NewL();
1.86 +
1.87 + /**
1.88 + * Two-phased copy constructor.
1.89 + *
1.90 + * @param[in] aCategory The category to copy.
1.91 + * @returns A copy of the specified category object.
1.92 + */
1.93 + IMPORT_C static CPosLandmarkCategory* NewLC(
1.94 + const CPosLandmarkCategory& aCategory
1.95 + );
1.96 +
1.97 + /**
1.98 + * Two-phased copy constructor.
1.99 + *
1.100 + * @param[in] aCategory The category to copy.
1.101 + * @returns A copy of the specified category object.
1.102 + */
1.103 + IMPORT_C static CPosLandmarkCategory* NewL(
1.104 + const CPosLandmarkCategory& aCategory
1.105 + );
1.106 +
1.107 + /**
1.108 + * Destructor.
1.109 + */
1.110 + virtual ~CPosLandmarkCategory();
1.111 +
1.112 + public:
1.113 +
1.114 + /**
1.115 + * Reads the ID of the category entry in the database.
1.116 + *
1.117 + * @returns The ID of the category entry in the database, or
1.118 + * @p KPosLmNullItemId if the category has not been added to the
1.119 + * database yet.
1.120 + */
1.121 + IMPORT_C TPosLmItemId CategoryId() const;
1.122 +
1.123 + /**
1.124 + * Retrieves global category ID.
1.125 + *
1.126 + * Global categories enable a uniform categorization across multiple
1.127 + * databases.
1.128 + *
1.129 + * @returns The global category ID or @p KPosLmNullGlobalCategory if the
1.130 + * category is not global.
1.131 + */
1.132 + IMPORT_C TPosLmGlobalCategory GlobalCategory() const;
1.133 +
1.134 + /**
1.135 + * @internal */
1.136 + /*
1.137 + * Sets the category to be global (i.e. not only defined in one
1.138 + * database).
1.139 + *
1.140 + * Global categories enable a uniform categorization across multiple
1.141 + * databases.
1.142 + *
1.143 + * @param[in] aGlobalCategory The global category ID or
1.144 + * @p KPosLmNullGlobalCategory if the category should not be global.
1.145 + */
1.146 + void SetGlobalCategory(
1.147 + TPosLmGlobalCategory aGlobalCategory
1.148 + );
1.149 +
1.150 + /**
1.151 + * Reads the name of the landmark category.
1.152 + *
1.153 + * @param[out] aCategoryName Will contain the category name.
1.154 + * @returns @p KErrNone if successful, @p KErrNotFound if the category
1.155 + * name is not set.
1.156 + */
1.157 + IMPORT_C TInt GetCategoryName(
1.158 + TPtrC& aCategoryName
1.159 + ) const;
1.160 +
1.161 + /**
1.162 + * Sets the name of the landmark category.
1.163 + *
1.164 + * @param[in] aCategoryName The category name.
1.165 + *
1.166 + * @leave KErrArgument Client passed an empty descriptor or landmark name
1.167 + * is longer than @p KPosLmMaxCategoryNameLength.
1.168 + */
1.169 + IMPORT_C void SetCategoryNameL(
1.170 + const TDesC& aCategoryName
1.171 + );
1.172 +
1.173 + /**
1.174 + * Associates the landmark category with an icon.
1.175 + *
1.176 + * Icons are found in icon files. To set an icon, the client
1.177 + * must specify the name of the icon file and the index of the
1.178 + * icon within the file.
1.179 + *
1.180 + * The landmark is not affected if the icon file is changed or
1.181 + * removed. It only contains a link to the icon.
1.182 + *
1.183 + * @param[in] aIconFileName The full icon file name.
1.184 + * @param[in] aIconIndex The index of the icon within the icon file.
1.185 + * @param[in] aIconMaskIndex The index of the icon mask within the
1.186 + * icon file.
1.187 + *
1.188 + * @leave KErrArgument The icon file name is longer than @p KMaxFileName.
1.189 + *
1.190 + * @panic "Landmarks Client"-EPosLmInvalidArgument The icon index is negative or
1.191 + * icon mask index is negative and not equal to @p KPosLmIconMaskNotUsed.
1.192 + */
1.193 + IMPORT_C void SetIconL(
1.194 + const TDesC& aIconFileName,
1.195 + TInt aIconIndex,
1.196 + TInt aIconMaskIndex
1.197 + );
1.198 +
1.199 + /**
1.200 + * Returns the a link to the icon associated with the landmark category.
1.201 + *
1.202 + * Icons are found in icon files. It is referenced by the name of
1.203 + * the icon file and the index of the icon within the file.
1.204 + *
1.205 + * The landmark category is not affected if the icon file is
1.206 + * changed or removed. It only contains a link to the icon. This means
1.207 + * that the link could be invalid.
1.208 + *
1.209 + * @param[out] aIconFileName The full icon file name.
1.210 + * @param[out] aIconIndex The index of the icon within the icon file.
1.211 + * @param[out] aIconMaskIndex The index of the icon mask within the
1.212 + * icon file. If no icon mask index is defined @p KPosLmIconMaskNotUsed
1.213 + * is returned.
1.214 + *
1.215 + * @returns @p KErrNone if successful, @p KErrNotFound if the icon is
1.216 + * not set.
1.217 + */
1.218 + IMPORT_C TInt GetIcon(
1.219 + TPtrC& aIconFileName,
1.220 + TInt& aIconIndex,
1.221 + TInt& aIconMaskIndex
1.222 + ) const;
1.223 +
1.224 + /**
1.225 + * Removes category attributes from the landmark category.
1.226 + *
1.227 + * @param[in] aAttributes A bitmap specifying which category attributes to
1.228 + * remove.
1.229 + */
1.230 + IMPORT_C void RemoveCategoryAttributes(
1.231 + TAttributes aAttributes
1.232 + );
1.233 +
1.234 + /**
1.235 + * @internal */
1.236 + /*
1.237 + * Sets the category ID to the landmark category.
1.238 + *
1.239 + * @param[in] aId The category ID to set.
1.240 + */
1.241 + void SetCategoryIdL(
1.242 + TPosLmItemId aId
1.243 + );
1.244 +
1.245 + private:
1.246 +
1.247 + // C++ constructor
1.248 + CPosLandmarkCategory();
1.249 +
1.250 + void ConstructL();
1.251 + void ConstructL(const CPosLandmarkCategory& aCategory);
1.252 +
1.253 + // Prohibit copy constructor
1.254 + CPosLandmarkCategory(const CPosLandmarkCategory&);
1.255 +
1.256 + // Prohibit assigment operator
1.257 + CPosLandmarkCategory& operator= (const CPosLandmarkCategory&);
1.258 +
1.259 + private:
1.260 +
1.261 + // Category ID
1.262 + TPosLmItemId iId;
1.263 +
1.264 + // Global category
1.265 + TPosLmGlobalCategory iGlobalCategory;
1.266 +
1.267 + // Category label
1.268 + HBufC* iCategoryName;
1.269 +
1.270 + // Category icon filename
1.271 + HBufC* iIconFileName;
1.272 +
1.273 + // Category icon index
1.274 + TInt iIconIndex;
1.275 +
1.276 + // Category icon mask index
1.277 + TInt iIconMaskIndex;
1.278 + };
1.279 +
1.280 +#endif // CPOSLANDMARKCATEGORY_H
1.281 +
1.282 +