inc/engine/routes/Maneuver.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 MANEUVER_H
  19 #define MANEUVER_H
  20
  21 #include "common/HereMaps_global.h"
  22 #include "common/GeoCoordinates.h"
  23
  24 HERE_MAPS_BEGIN_NAMESPACE
  25
  26 class Maneuver;
  27 typedef std::vector<Maneuver> ManeuverList;
  28
  29
  30 /**
  31  * This class represents a route maneuver. A route maneuver contains information
  32  * that allows for navigation instructions to be generated, which explain how
  33  * the person following a route is to proceed from one segment of the route to
  34  * another. A <code>Maneuver</code> instance contains instruction text for the
  35  * person following the route, the geographic coordinates of the waypoint to
  36  * which it applies, an indication of the direction of travel, as well
  37  * as time and distance to the next instruction.
  38  *
  39  * Maneuvers are tightly coupled to the <code>Route</code> instance for which
  40  * they are generated.
  41  *
  42  * \ingroup routes
  43  */
  44 class EXPORT_API Maneuver
  45 {
  46
  47 public:
  48     /**
  49      * This enumeration defines identifiers for route maneuver directions.
  50      */
  51     enum InstructionDirection {
  52         ID_NoDirection,          ///< Indicates that no directional instruction
  53                                  ///  is set/specified; this is the default
  54                                  ///  direction set by the default constructor.
  55         ID_DirectionForward,     ///< Indicates instruction to travel forward.
  56         ID_DirectionBearRight,   ///< Indicates instruction to bear right.
  57         ID_DirectionLightRight,  ///< Indicates instruction to turn slightly to
  58                                  ///  the right.
  59         ID_DirectionRight,       ///< Indicates instruction to turn right.
  60         ID_DirectionHardRight,   ///< Indicates instruction to turn hard to the
  61                                  ///  right.
  62         ID_DirectionUTurnRight,  ///< Indicates instruction to make a right
  63                                  ///  u-turn.
  64         ID_DirectionUTurnLeft,   ///< Indicates instruction to make a left
  65                                  ///  u-turn.
  66         ID_DirectionHardLeft,    ///< Indicates instruction to turn hard to the
  67                                  ///  left.
  68         ID_DirectionLeft,        ///< Indicates instruction to turn left.
  69         ID_DirectionLightLeft,   ///< Indicates instruction to turn slightly to
  70                                  ///  the left.
  71         ID_DirectionBearLeft     ///< Indicates instruction to bear left.
  72     };
  73
  74     /**
  75      * This method is the default constructor. It creates an invalid instance,
  76      * with direction set to ID_NoDirection.
  77      */
  78     Maneuver();
  79
  80     /**
  81      * This method is the copy constructor.
  82      *
  83      * @param rRhs A constant reference to an object whose contents are to be
  84      *        copied to the new instance of the class.
  85      */
  86     Maneuver(const Maneuver& rRhs);
  87
  88     /**
  89      * This method is the destructor.
  90      */
  91     ~Maneuver();
  92
  93     /**
  94      * This method is the assignment operator.
  95      *
  96      * @param rRhs A constant reference to an object whose contents are to be
  97      *        copied to the given instance of the class.
  98      *
  99      * @return A reference to the given instance after the assignment.
 100      */
 101     Maneuver& operator = (const Maneuver& rRhs);
 102
 103     /**
 104      * This method checks if the given maneuver object is valid. The object is
 105      * valid if at least its position property holds valid coordinates and
 106      * direction is set to a value other than <code>ID_NoDirection</code>.
 107      *
 108      * @return <code>true</code> if the given object is valid, otherwise
 109      *        <code>false</code>.
 110      */
 111     bool IsValid() const;
 112
 113     /**
 114      * This method sets the position (location) of the maneuver.
 115      *
 116      * @param rPosition A constant reference to an object containing the
 117      *        geographic coordinates of the location at which the maneuver is to
 118      *        be executed.
 119      */
 120     void SetPosition(const GeoCoordinates& rPosition);
 121
 122     /**
 123      * This method retrieves the position (location) of the maneuver.
 124      *
 125      * @return An object containing the geographic coordinates of the location
 126      *        at which the maneuver is to be executed.
 127      */
 128     GeoCoordinates GetPosition() const;
 129
 130     /**
 131      * This method sets the maneuver instruction text.
 132      *
 133      * @param sInstructionText A constant reference to a string containing the
 134      *        maneuver instruction text.
 135      */
 136     void SetInstructionText(const String& sInstructionText);
 137
 138     /**
 139      * This method retrieves the maneuver instruction text.
 140      *
 141      * @return A constant reference to a string containing the maneuver
 142      *        instruction text.
 143      */
 144     String GetInstructionText() const;
 145
 146     /**
 147      * This method sets the maneuver direction.
 148      *
 149      * @param aDirection A value indicating the maneuver direction.
 150      */
 151     void SetDirection(InstructionDirection aDirection);
 152
 153     /**
 154      * This method retrieves the maneuver direction.
 155      *
 156      * @return A value indicating the maneuver direction.
 157      */
 158     InstructionDirection GetDirection() const;
 159
 160     /**
 161      * This method sets the time to next instruction in the given maneuver.
 162      *
 163      * @param aSecs A value specifying the time to the next instruction in
 164      *        seconds.
 165      */
 166     void SetTimeToNextInstruction(int aSecs);
 167
 168     /**
 169      * This method retrieves the time to next instruction in the given maneuver.
 170      *
 171      * @return A value specifying the time to the next instruction in seconds.
 172      */
 173     int GetTimeToNextInstruction() const;
 174
 175     /**
 176      * This method sets the distance to next instruction in the given maneuver.
 177      *
 178      * @param aDistance A value specifying the distance to the next instruction
 179      *        in meters.
 180      */
 181     void SetDistanceToNextInstruction(double aDistance);
 182
 183     /**
 184      * This method retrieves the distance to next instruction in the given
 185      * maneuver.
 186      *
 187      * @return A value specifying the distance to the next instruction
 188      *        in meters.
 189      */
 190     double GetDistanceToNextInstruction() const;
 191
 192 private:
 193     class ManeuverImpl;
 194     ManeuverImpl* m_pImpl;
 195
 196     friend class ManeuverImpl;
 197 };
 198
 199 HERE_MAPS_END_NAMESPACE
 200
 201 #endif /* MANEUVER_H */