inc/engine/finder/PlaceItem.h

   1 /*
   2  * Copyright (C) 2013 HERE Global B.V. All rights reserved.
   3  * This software, including documentation, is protected by copyright controlled by
   4  * HERE Global B.V. (“Software”). All rights are reserved. Copying, including reproducing,
   5  * storing, adapting or translating, any or all of this material requires the prior
   6  * written consent of HERE Global B.V. You may use this
   7  * Software in accordance with the terms and conditions defined in the
   8  * HERE Location Platform Services Terms and Conditions, available at
   9  * http://developer.here.com/terms-conditions-base
  10  *
  11  * As an additional permission to the above, you may distribute Software,
  12  * in object code format as part of an Application, according to, and subject to, terms and
  13  * conditions defined in the Tizen Software Development kit (“SDK”) License Agreement.
  14  * You may distribute such object code format Application under terms of your choice,
  15  * provided that the header and source files of the Software have not been modified.
  16  */
  17
  18 #ifndef PLACE_ITEM_H_
  19 #define PLACE_ITEM_H_
  20
  21 #include <vector>
  22 #include "common/HereMaps_global.h"
  23 #ifndef TIZEN_MIGRATION
  24 #include <FBase.h>
  25 #endif
  26
  27 HERE_MAPS_BEGIN_NAMESPACE
  28
  29 class GeoCoordinates;
  30 class Category;
  31 class LinkObject;
  32 class GeoBoundingBox;
  33
  34 class PlaceItem;
  35 /**
  36  * This typedef defines a vector of place items as a type.
  37  *
  38  * \ingroup finder
  39  */
  40 typedef std::vector< PlaceItem > PlaceItemList;
  41
  42 /**
  43  * This class encapsulates information about a place that has been returned as
  44  * part of a reply to a search query (an item in a search result). This
  45  * information can be used to obtain place details.
  46  *
  47  * \ingroup finder
  48  */
  49 class EXPORT_API PlaceItem
  50 {
  51 public:
  52
  53     /**
  54      * This method is the default constructor.
  55      */
  56     PlaceItem();
  57
  58     /**
  59      * This method is the copy constructor.
  60      *
  61      * @param rRhs An object whose contents are to be copied to the instance
  62      *        being created.
  63      */
  64     PlaceItem(const PlaceItem& rRhs);
  65
  66     /**
  67      * This method is the destructor.
  68      */
  69     ~PlaceItem();
  70
  71     /**
  72      * This is the assignment operator.
  73      *
  74      * @param rRhs An object whose contents are to be copied to the given
  75      *        instance.
  76      *
  77      * @return A reference to the given instance of the class after its contents
  78      *       have been updated.
  79      */
  80     PlaceItem& operator=(const PlaceItem& rRhs);
  81
  82     /**
  83      * This method retrieves the geographic coordinates of the given place.
  84      *
  85      * @return An object containing the geographic coordinates of the place.
  86      */
  87     GeoCoordinates GetPosition() const;
  88
  89     /**
  90      * This method retrieves the distance in meters between the given place and
  91      * the search context (center).
  92      *
  93      * @return A value indicating how far the given place lies from the search
  94      *        context (center).
  95      */
  96     double GetDistance() const;
  97
  98     /**
  99      * This method retrieves a value that represents the average rating of the
 100      * place by users.
 101      *
 102      * @return A value that represents the average rating of the place by users.
 103      */
 104     double GetAverageRating() const;
 105
 106     /**
 107      * This method retrieves an object representing the category to which the
 108      * given place is assigned.
 109      *
 110      * @return An object representing the category to which the given place is
 111      *        assigned.
 112      */
 113     Category GetCategory() const;
 114
 115     /**
 116      * This method retrieves a link to a resource associated with the given
 117      * place item.
 118      *
 119      * @return An object encapsulating a link to a resource.
 120      */
 121     LinkObject GetLinkObject() const;
 122
 123     /**
 124      * This method retrieves text describing the location of the place. The text
 125      * is typically derived from the address of the place, but may also contain
 126      * any other information that can help the user understand, where the place is
 127      * located.
 128      *
 129      * @return A string containing the description of the vicinity (location) of
 130      *       the place.
 131      */
 132     String GetVicinity() const;
 133
 134     /**
 135      * This method retrieves a Boolean value indicating if the given search
 136      * result is sponsored or not.
 137      *
 138      * @return <code>true</code> if the given search result is sponsored,
 139      *        otherwise <code>false</code>.
 140      */
 141     bool GetIsSponsored() const;
 142
 143     /**
 144      * This method retrieves the bounding box enclosing the given place.
 145      *
 146      * @return An object representing the bounding box (defined in terms of the
 147      *       geographical coordinates of its top-left and bottom-right corners)
 148      *       that encloses the given place.
 149      */
 150     GeoBoundingBox GetBBox() const;
 151
 152     /**
 153      * This method sets the geographic coordinates of the given place.
 154      *
 155      * @param rPosition GeoCoordinates A constant reference to a object
 156      *        containing the geographic coordinates of the place.
 157      */
 158     void SetPosition(const GeoCoordinates& rPosition);
 159
 160     /**
 161      * This method sets the distance in meters between the given place and
 162      * the search context (center).
 163      *
 164      * @param dDistance A value indicating how far the
 165      *        given place lies from the search context (center).
 166      */
 167     void SetDistance(double dDistance);
 168
 169     /**
 170      * This method sets a value that represents the average rating of the
 171      * place by users.
 172      *
 173      * @param dAverageRating A value that represents the average rating of the
 174      *        place by users.
 175      */
 176     void SetAverageRating(double dAverageRating);
 177
 178     /**
 179      * This method sets an object representing the category to which the
 180      * given place is assigned.
 181      *
 182      * @param rCategory A constant reference to an object representing the
 183      *        category to which the given place is assigned.
 184      */
 185     void SetCategory(const Category& rCategory);
 186
 187     /**
 188      * This method sets text describing the location of the place. The text
 189      * is typically derived from the address of the place, but may also contain
 190      * any other information that may help the user understand, where the place is
 191      * located.
 192      *
 193      * @param sVicinity A constant reference to a string containing the
 194      *       description of the vicinity (location) of the place.
 195      */
 196     void SetVicinity(const String& sVicinity);
 197
 198     /**
 199      * This method sets a link to a resource associated with the given
 200      * place item.
 201      *
 202      * @param rLinkObject A constant reference to an object encapsulating a link
 203      *        to a resource.
 204      */
 205     void SetLinkObject(const LinkObject& rLinkObject);
 206
 207     /**
 208      * This method sets a Boolean value indicating if the given search
 209      * result item is sponsored or not.
 210      *
 211      * @param bIsSponsored <code>true</code> if the given search result item is
 212      *        sponsored, otherwise <code>false</code>.
 213      */
 214     void SetIsSponsored(bool bIsSponsored);
 215
 216     /**
 217      * This method sets the bounding box enclosing the given place.
 218      *
 219      * @param rBbox A constant reference to an object representing the bounding
 220      *       box (defined in terms of the geographical coordinates of its
 221      *       top-left and bottom-right corners) that encloses the given place.
 222      */
 223     void SetBBox(const GeoBoundingBox& rBbox);
 224
 225 private:
 226     class PlaceItemImpl;
 227     PlaceItemImpl* m_pImpl;
 228
 229     friend class JsonParser;
 230 };
 231
 232 HERE_MAPS_END_NAMESPACE
 233
 234 #endif // PLACE_ITEM_H_