inc/engine/common/GeoLocation.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 LOCATION_H
  19 #define LOCATION_H
  20
  21 #include "common/HereMaps_global.h"
  22
  23 HERE_MAPS_BEGIN_NAMESPACE
  24
  25 class Address;
  26 class GeoCoordinates;
  27 class GeoBoundingBox;
  28
  29 /**
  30  *  This class represents the standard set of basic location information.
  31  *
  32  *  This includes the address, coordinates and map view.
  33  *
  34  */
  35 class EXPORT_API GeoLocation
  36 {
  37 public:
  38     /**
  39      * This enumeration defines identifiers for location types.
  40      */
  41     enum LocationType
  42     {
  43         LT_Unknown = -1, ///< Indicates an unknown location type.
  44         LT_Point,        ///< Indicates that the location is a point.
  45         LT_Area,         ///< Indicates that the location is an area.
  46         LT_Line          ///< Indicates that the location is a line.
  47     };
  48
  49     /**
  50      * This method is the default constructor.
  51      */
  52     GeoLocation();
  53
  54     /**
  55      * This method is the copy constructor.
  56      *
  57      * @param rRhs A constant reference to an instance of
  58      *        <code>GeoLocation</code> whose contents are to be copied into
  59      *        the object being created.
  60      */
  61     GeoLocation(const GeoLocation& rRhs);
  62
  63     /**
  64      * This method is the destructor.
  65      */
  66     ~GeoLocation();
  67
  68     /**
  69      * This is the assignment operator.
  70      *
  71      * @param rRhs A constant reference to an instance of
  72      *        <code>GeoLocation</code> whose contents are to be copied into
  73      *        the given instance.
  74      */
  75     GeoLocation& operator=(const GeoLocation& rRhs);
  76
  77     /**
  78      * This method sets the address of the location.
  79      *
  80      * @param rAddress A constant reference to an object containing an address.
  81      */
  82     void SetAddress(const Address& rAddress);
  83
  84     /**
  85      * This method retrieves the address of the location.
  86      *
  87      * @return A constant reference to an object containing an address.
  88      */
  89     const Address& GetAddress() const;
  90
  91     /**
  92      * This method sets the label for the location.
  93      *
  94      * @param sLabel A constant reference to an object containing the value of
  95      *        the label.
  96      */
  97     void SetLabel(const String& sLabel);
  98
  99     /**
 100      * This method retrieves the label for the location.
 101      *
 102      * @return A constant reference to an object containing the value of
 103      *        the label.
 104      */
 105     const String& GetLabel() const;
 106
 107     /**
 108      * This method sets the display position of the location. The display
 109      * position contains the coordinates at which to place a marker indicating
 110      * the given location on the map.
 111      *
 112      * @param rCoord A constant reference to an object containing the geographic
 113      *        coordinates of the display position.
 114      */
 115     void SetDisplayPosition(const GeoCoordinates& rCoord);
 116
 117     /**
 118      * This method retrieves the display position of the location. The display
 119      * position contains the coordinates at which to place a marker indicating
 120      * the given location on the map.
 121      *
 122      * @return A constant reference to an object containing the geographic
 123      *        coordinates of the display position.
 124      */
 125     const GeoCoordinates& GetDisplayPosition() const;
 126
 127     /**
 128      * This method appends the navigation position. A navigation position
 129      * contains the coordinates of a potential route waypoint. It is used for
 130      * routes that pass through the given location.
 131      *
 132      * @param rCoord A constant reference to an object containing the geographic
 133      *        coordinates of the navigation position.
 134      */
 135     void AppendNavigationPosition(const GeoCoordinates& rCoord);
 136
 137     /**
 138      * This method retrieves the number of navigation positions that have been set.
 139      *
 140      * @return An integer indicating the number of navigation positions.
 141      */
 142     size_t GetNumNavigationPositions() const;
 143
 144     /**
 145      * This method retrieves the navigation position from the index specified by
 146      * the caller. A navigation position contains the coordinates of a potential
 147      * route waypoint. It is used for routes that pass through the given
 148      * location.
 149      *
 150      * @param idx A value specifying the index into an array of navigation
 151      *        positions.
 152      *
 153      * @return A constant pointer to an object containing the geographic
 154      *        coordinates of the display position.
 155      */
 156     const GeoCoordinates* GetNavigationPosition(size_t idx) const;
 157
 158     /**
 159      * This method sets the map view of the location.
 160      *
 161      * @param rBbox A constant reference to an object that defines the map view
 162      *        as a bounding box.
 163      */
 164     void SetMapView(const GeoBoundingBox& rBbox);
 165
 166     /**
 167      * This method retrieves the map view of the location.
 168      *
 169      * @return A constant reference to an object that defines the map view
 170      *        as a bounding box.
 171      */
 172     const GeoBoundingBox& GetMapView() const;
 173
 174     /**
 175      * This method sets the id of the location.
 176      *
 177      * @param sLocationId A constant reference to a string containing the
 178      *        location id.
 179      */
 180     void SetLocationId(const String& sLocationId);
 181
 182     /**
 183      * This method retrieves the id of the location.
 184      *
 185      * @return A constant reference to a string containing the
 186      *        location id.
 187      */
 188     const String& GetLocationId() const;
 189
 190     /**
 191      * This method sets the location type.
 192      *
 193      * @param aType A numeric value indicating the location type.
 194      */
 195     void SetLocationType(LocationType aType);
 196
 197     /**
 198      * This method sets the location type.
 199      *
 200      * @param sType A constant reference to string identifying the location
 201      *        type. The supported values are "area", "point", and "line".
 202      */
 203     void SetLocationType(const String& sType);
 204
 205     /**
 206      * This method retrieves the location type.
 207      *
 208      * @return A numeric value indicating the location type.
 209      */
 210     LocationType GetLocationType() const;
 211
 212 private:
 213     class GeoLocationImpl;
 214     GeoLocationImpl* m_pImpl;
 215 };
 216
 217 HERE_MAPS_END_NAMESPACE
 218
 219 #endif