1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the Qt Mobility Components.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 #include "qgeoareamonitor.h"

    42 

    43 #if defined(Q_OS_SYMBIAN) && defined(QT_LOCATION_S60_MONITORING)

    44 #include "qgeoareamonitor_s60_p.h"

    45 #endif

    46 

    47 /*!

    48     \class QGeoAreaMonitor

    49     \brief The QGeoAreaMonitor class enables the detection of proximity

    50     changes for a specified set of coordinates.

    51     \ingroup location

    52 

    53     A QGeoAreaMonitor emits signals when the current position is in

    54     range, or has moved out of range, of a specified circular area.

    55     The area is specified by a coordinate (the center point) and a

    56     radius (in meters).

    57 

    58     For example:

    59 

    60     \code

    61         public:

    62             MyClass::MyClass()

    63             {

    64                 QGeoAreaMonitor *monitor = QGeoAreaMonitor::createDefaultMonitor();

    65                 connect(monitor, SIGNAL(areaEntered(QGeoPositionInfo)),

    66                         this, SLOT(areaEntered(QGeoPositionInfo)));

    67                 connect(monitor, SIGNAL(areaExited(QGeoPositionInfo)),

    68                         this, SLOT(areaExited(QGeoPositionInfo)));

    69 

    70                 QGeoCoordinate bigBenLocation(51.50104, -0.124632);

    71                 monitor->setCenter(bigBenLocation);

    72                 monitor->setRadius(100);

    73             }

    74 

    75         public Q_SLOTS:

    76             void areaEntered(const QGeoPositionInfo &update)

    77             {

    78                 qDebug() << "Now within 100 meters, current position is" << update.coordinate();

    79             }

    80 

    81             void areaExited(const QGeoPositionInfo &update)

    82             {

    83                 qDebug() << "No longer within 100 meters, current position is" << update.coordinate();

    84             }

    85     \endcode

    86 */

    87 

    88 QTM_BEGIN_NAMESPACE

    89 

    90 class QGeoAreaMonitorPrivate

    91 {

    92 public:

    93     QGeoCoordinate coord;

    94     qreal radius;

    95 };

    96 

    97 

    98 /*!

    99     Creates a monitor with the given \a parent.

   100 */

   101 QGeoAreaMonitor::QGeoAreaMonitor(QObject *parent)

   102         : QObject(parent),

   103         d(new QGeoAreaMonitorPrivate)

   104 {

   105     d->radius = qreal(0.0);

   106 }

   107 

   108 /*!

   109     Destroys the monitor.

   110 */

   111 QGeoAreaMonitor::~QGeoAreaMonitor()

   112 {

   113     delete d;

   114 }

   115 

   116 /*!

   117     \property QGeoAreaMonitor::center

   118     \brief This property holds the center of the area to be monitored.

   119 

   120     When the center is set, if the radius has already been set and

   121     the current position is within the monitored area, areaEntered()

   122     is emitted immediately.

   123 

   124     By default, contains an invalid coordinate.

   125 

   126     Note: Subclass implementations must call the base implementation of

   127     setCenter() so that center() returns the correct value.

   128 */

   129 void QGeoAreaMonitor::setCenter(const QGeoCoordinate &coordinate)

   130 {

   131     d->coord = coordinate;

   132 }

   133 

   134 QGeoCoordinate QGeoAreaMonitor::center() const

   135 {

   136     return d->coord;

   137 }

   138 

   139 /*!

   140     \property QGeoAreaMonitor::radius

   141     \brief This property holds the radius of the area to be monitored, in meters.

   142 

   143     If the specified radius is less than the minimum supported radius, the

   144     radius is set to the minimum radius.

   145 

   146     When this property is set, if the center coordinate has already been set and

   147     the current position is within the monitored area, areaEntered()

   148     is emitted immediately.

   149 

   150     By default, this property is 0.

   151 

   152     Note: Subclass implementations must call the base implementation of

   153     setRadius() so that radius() returns the correct value.

   154 */

   155 void QGeoAreaMonitor::setRadius(qreal radius)

   156 {

   157     d->radius = radius;

   158 }

   159 

   160 qreal QGeoAreaMonitor::radius() const

   161 {

   162     return d->radius;

   163 }

   164 

   165 /*!

   166     Creates and returns a monitor with the given \a parent that

   167     monitors areas using resources on the underlying system.

   168 

   169     Returns 0 if the system has no support for position monitoring.

   170 */

   171 QGeoAreaMonitor *QGeoAreaMonitor::createDefaultMonitor(QObject *parent)

   172 {

   173 #if defined(Q_OS_SYMBIAN) && defined(QT_LOCATION_S60_MONITORING)

   174     QGeoAreaMonitor *ret = NULL;

   175     TRAPD(error, ret = QGeoAreaMonitorS60::NewL(parent));

   176     return ret;

   177 #else

   178     Q_UNUSED(parent);

   179 #endif

   180     return 0;

   181 }

   182 

   183 /*!

   184     \fn void QGeoAreaMonitor::areaEntered(const QGeoPositionInfo &update);

   185 

   186     Emitted when the current position has moved from a position outside the

   187     monitored area to a position within the monitored area.

   188 

   189     The \a update holds the new position.

   190 */

   191 

   192 /*!

   193     \fn void QGeoAreaMonitor::areaExited(const QGeoPositionInfo &update);

   194 

   195     Emitted when the current position has moved from a position within the

   196     monitored area to a position outside the monitored area.

   197 

   198     The \a update holds the new position.

   199 */

   200 

   201 QTM_END_NAMESPACE