File indexing completed on 2024-05-12 05:22:32

 /*
     SPDX-FileCopyrightText: 2012 Jan Grulich <grulja@gmail.com>
 
     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
 */
 
 #pragma once
 
 #include "kgapimaps_export.h"
 #include "staticmapmarker.h"
 #include "staticmappath.h"
 
 #include <QSize>
 #include <QUrl>
 
 #include <KContacts/Address>
 #include <KContacts/Geo>
 
 namespace KGAPI2
 {
 
 /**
  * @brief A class to build a URL from StaticMapMarkers and StaticMapPaths to
  *        fetch a map tile.
  *
  * @author Jan Grulich <grulja@gmail.com>
  * @since 0.4
  */
 class KGAPIMAPS_EXPORT StaticMapUrl
 {
 public:
     enum LocationType { Undefined = -1, String, KABCAddress, KABCGeo };
 
     enum ImageFormat { PNG, PNG32, GIF, JPG, JPGBaseline };
 
     enum MapType { Roadmap, Satellite, Terrain, Hybrid };
 
     enum Scale { Normal = 1, TwiceBigger = 2 };
 
     /**
      * @brief Constructs an empty StaticMapUrl
      */
     explicit StaticMapUrl();
 
     /**
      * @brief Constructs a new StaticMapUrl
      *
      * @param location Location of map center in QString
      * @param size Requested size of the map image
      * @param zoom Zoom level of map
      * @param sensor Sensor specifies whether the application requesting the
      *               static map is using a sensor to determine the user's location.
      */
     StaticMapUrl(const QString &location, const QSize &size, quint32 zoom, bool sensor);
 
     /**
      * @brief Constructs a new StaticMapUrl
      *
      * @param address Location of map center in KContacts::Address
      * @param size Requested size of the map image
      * @param zoom Zoom level of map
      * @param sensor Sensor specifies whether the application requesting the
      *               static map is using a sensor to determine the user's location.
      */
     StaticMapUrl(const KContacts::Address &address, const QSize &size, quint32 zoom, bool sensor);
 
     /**
      * @brief Constructs a new StaticMapUrl
      *
      * @param geo Location of map center in KContacts::Geo
      * @param size Requested size of the map image
      * @param zoom Zoom level of map
      * @param sensor Sensor specifies whether the application requesting the static map is
      * using a sensor to determine the user's location.
      */
     StaticMapUrl(const KContacts::Geo &geo, const QSize &size, quint32 zoom, bool sensor);
 
     /**
      * @brief Copy constructor
      */
     StaticMapUrl(const StaticMapUrl &other);
 
     /**
      * @brief Destructor
      */
     virtual ~StaticMapUrl();
 
     /**
      * @brief Returns in which format the location is stored.
      */
     [[nodiscard]] LocationType locationType() const;
 
     /**
      * @brief Returns map image format
      */
     [[nodiscard]] ImageFormat format() const;
 
     /**
      * @brief Sets map image format (default is PNG)
      *
      * @param format
      */
     void setFormat(const ImageFormat format);
 
     /**
      * @brief Returns whether map url is valid
      */
     bool isValid() const;
 
     /**
      * @brief Returns map center in QString
      *
      * Returns empty QString if location is not defined in QString
      */
     [[nodiscard]] QString locationString() const;
 
     /**
      * @brief Defines center of the map
      *
      * @param location Location (required when no markers are present) of
      *                 center of the map in QString
      */
     void setLocation(const QString &location);
 
     /**
      * @brief Returns map center in KContacts::Address
      *
      * Returns empty KContacts::Address if location is not defined in KContacts::Address
      */
     [[nodiscard]] KContacts::Address locationAddress() const;
 
     /**
      * @brief Defines center of the map
      *
      * @param address Location (required when no markers are present) of center
      *                of the map in KContacts::Address
      */
     void setLocation(const KContacts::Address &address);
 
     /**
      * @brief Returns map center in KContacts::Geo
      *
      * Returns invalid KContacts::Geo if location is not defined in KContacts::Geo
      */
     [[nodiscard]] KContacts::Geo locationGeo() const;
 
     /**
      * @brief Defines center of the map
      *
      * @param geo Location (required when no markers are present) of center
      *            of the map in KContacts::Geo
      */
     void setLocation(const KContacts::Geo &geo);
 
     /**
      * @brief Returns type of map
      */
     [[nodiscard]] MapType mapType() const;
 
     /**
      * @brief Sets type of map (roadmap by default)
      *
      * @param type
      */
     void setMapType(const MapType type);
 
     /**
      * @brief Returns list of markers
      *
      * Returns empty QList if no marker were added
      */
     [[nodiscard]] QList<StaticMapMarker> markers() const;
 
     /**
      * @brief Adds marker to map
      *
      * @param marker
      */
     void setMarker(const StaticMapMarker &marker);
 
     /**
      * @brief Adds markers to map
      *
      * @param markers
      */
     void setMarkers(const QList<StaticMapMarker> &markers);
 
     /**
      * @brief  Returns list paths
      *
      * Returns empty QList if no path were added
      */
     [[nodiscard]] QList<StaticMapPath> paths() const;
 
     /**
      * @brief Adds path to map
      *
      * @param path
      */
     void setPath(const StaticMapPath &path);
 
     /**
      * @brief Adds paths to map
      *
      * @param paths
      */
     void setPaths(const QList<StaticMapPath> &paths);
 
     /**
      * @brief Returns size of map tile
      */
     [[nodiscard]] QSize size() const;
 
     /**
      * @brief Sets size of requested map tile.
      *
      * @param size Maximum size is 640x640
      */
     void setSize(const QSize &size);
 
     /**
      * @brief Returns scale of map
      */
     [[nodiscard]] Scale scale() const;
 
     /**
      * @brief Sets scale of map (default is 1)
      *
      * @param scale
      */
     void setScale(const Scale scale);
 
     /**
      * @brief Returns whether the application uses a sensor to determine user's
      *        location.
      */
     [[nodiscard]] bool sensorUsed() const;
 
     /**
      * @brief Sets whether the application uses a sensor to determine the user's
      *        location.
      *
      * @param sensor
      */
     void setSensorUsed(const bool sensor);
 
     /**
      * @brief Returns visible area in QString
      *
      * Returns empty QString if visible area is not defined in QString
      */
     [[nodiscard]] QString visibleLocationString() const;
 
     /**
      * @brief Sets visible location.
      *
      * You can use this instead of using center and zoom parameters.
      *
      * Specifies location that should remain visible on the map, though
      * no markers or other indicators will be displayed. Use this parameter to
      * ensure that certain features or map location are shown on the static map.
      *
      * @param location
      */
     void setVisibleLocation(const QString &location);
 
     /**
      * @brief Returns visible area in KContacts::Address
      *
      * Returns empty KContacts::Address if visible area is not defined in KContacts::Address
      */
     [[nodiscard]] KContacts::Address visibleLocationAddress() const;
 
     /**
      * @brief Sets visible location.
      *
      * You can use this instead of using center and zoom parameters.
      *
      * Visible specifies location that should remain visible on the map, though
      * no markers or other indicators will be displayed. Use this parameter to
      * ensure that certain features or map location are shown on the static map.
      *
      * @param address
      */
     void setVisibleLocation(const KContacts::Address &address);
 
     /**
      * @brief Returns visible area in KContacts::Geo
      *
      * Returns empty KContacts::Geo if visible area is not defined in KContacts::Geo
      */
     [[nodiscard]] KContacts::Geo visibleLocationGeo() const;
 
     /**
      * @brief Sets visible location.
      *
      * You can use this instead of using center and zoom parameters.
      *
      * Visible specifies location that should remain visible on the map, though
      * no markers or other indicators will be displayed. Use this parameter to
      * ensure that certain features or map location are shown on the static map.
      *
      * @param geo
      */
     void setVisibleLocation(const KContacts::Geo &geo);
 
     /**
      * @brief Returns type of visible location
      */
     [[nodiscard]] LocationType visibleLocationType() const;
 
     /**
      * @brief Returns zoom level of map
      *
      * Returns -1 if zoom level is not defined
      */
     [[nodiscard]] qint8 zoomLevel() const;
 
     /**
      * @brief Sets zoom level of the map
      *
      * @param zoom Zoom parameter can be in range 0 to 21 where 21 is maximum
      *             zoom level.
      */
     void setZoomLevel(const quint32 zoom);
 
     /**
      * @brief Returns constructed url from all defined parameters
      */
     [[nodiscard]] QUrl url() const;
 
     /**
      * @brief Assignment operator
      */
     StaticMapUrl &operator=(const StaticMapUrl &other);
 
 private:
     class Private;
     Private *const d;
     friend class Private;
 };
 
 } // namespace KGAPI2