path: root/src/imports/location/qdeclarativegeomapmousearea.cpp

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the QtLocation module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** GNU Lesser General Public License Usage
** This file may be used under the terms of the GNU Lesser General Public
** License version 2.1 as published by the Free Software Foundation and
** appearing in the file LICENSE.LGPL included in the packaging of this
** file. Please review the following information to ensure the GNU Lesser
** General Public License version 2.1 requirements will be met:
** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU General
** Public License version 3.0 as published by the Free Software Foundation
** and appearing in the file LICENSE.GPL included in the packaging of this
** file. Please review the following information to ensure the GNU General
** Public License version 3.0 requirements will be met:
** http://www.gnu.org/copyleft/gpl.html.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms and
** conditions contained in a signed written agreement between you and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

#include "qdeclarativegeomapmousearea_p.h"
#include "qdeclarativegeomapitembase_p.h"
#include <QtDeclarative/qdeclarativeinfo.h>
#include <QtDeclarative/QQuickCanvas>

#include <QtDeclarative/private/qquickevents_p_p.h>

#include <QDebug>

QT_BEGIN_NAMESPACE

/*!
    \qmlclass MapMouseArea  QDeclarativeGeoMapMouseArea

    \brief The MapMouseArea item enables simple mouse handling.

    \inqmlmodule QtLocation 5
    \ingroup qml-QtLocation5-maps

   A MapMouseArea is an invisible item that is typically used in conjunction
   with a visible map object or map item in order to provide mouse handling.
   By effectively acting as a proxy, the logic for mouse handling can be
   contained within a MapMouseArea item.

   The \l enabled property is used to enable and disable mouse handling for
   the proxied item. When disabled, the mouse area becomes transparent to
   mouse events.

   The \l pressed read-only property indicates whether or not the user is
   holding down a mouse button over the mouse area. This property is often
   used in bindings between properties in a user interface.

   Information about the mouse position and button clicks are provided via
   signals for which event handler properties are defined. The most commonly
   used involved handling mouse presses and clicks: onClicked, onDoubleClicked,
   onPressed and onReleased.

   MapMouseArea does not intend to be generic mouse area that supports every
   possible usage, rather it focuses on catering for the major use-cases. Hence there
   are some implementation limitations:
    \list
        \i The mouse event is guaranteed only to be valid for the
   duration of the signal handler (e.g. onPositionChanged, onClicked). Consequently
   the mouse event itself should not be stored. The main reason for this is to
   optimize memory usage; we do not want to allocate heap memory every time the mouse
   moves.
        \i Nested mouse areas are not supported (MapMouseArea { MapMouseArea {} }
        \i Using normal QML MouseArea in MapItem or Map has no effect
        \i If mouse areas of map overlap, the declaration order is significant (not e.g. 'z' value)
        \i Only one MapMouseArea per MapItem is supported, and it always fills the whole MapItem
    \endlist

    \sa MapMouseEvent
*/

QDeclarativeGeoMapMouseArea::QDeclarativeGeoMapMouseArea(QQuickItem *parent)
    : QQuickMouseArea(parent),
      map_(0),
      componentCompleted_(false)
{
}

QDeclarativeGeoMapMouseArea::~QDeclarativeGeoMapMouseArea()
{
}

QDeclarativeCoordinate* QDeclarativeGeoMapMouseArea::mouseToCoordinate(QQuickMouseEvent* event)
{
    // figure out the map association for this mouse area and use it to resolve geocoordinate.
    // we may need to dive higher in the parent tree if associating
    // element (map item or map element) is further up the tree. TODO
    if (parentItem()) {
        QDeclarativeGeoMap* map = qobject_cast<QDeclarativeGeoMap*>(parentItem());
        if (!map) {
            QDeclarativeGeoMapItemBase* item = qobject_cast<QDeclarativeGeoMapItemBase*>(parentItem());
            if (item)
                map = item->quickMap();
        }
        if (map)
            return map->toCoordinate(map->mapFromItem(this, QPointF(event->x(), event->y())));
    }
    return new QDeclarativeCoordinate; // return invalid coordinate
}

void QDeclarativeGeoMapMouseArea::componentComplete()
{
    componentCompleted_ = true;
    QQuickMouseArea::componentComplete();
}

void QDeclarativeGeoMapMouseArea::mousePressEvent(QMouseEvent *event)
{
    // map element's flickable may use the event
    if (parentItem() && qobject_cast<QDeclarativeGeoMap*>(parentItem()))
        qobject_cast<QDeclarativeGeoMap*>(parentItem())->mouseEvent(event);
    // ignore event if it misses non-rectangular geometry (e.g. circle, route)
    bool contains = true;
    if (parentItem() && qobject_cast<QDeclarativeGeoMapItemBase*>(parentItem()))
        contains = qobject_cast<QDeclarativeGeoMapItemBase*>(parentItem())->contains(event->pos());
    if (!contains)
        event->ignore();
    else
        QQuickMouseArea::mousePressEvent(event);
}

void QDeclarativeGeoMapMouseArea::mouseReleaseEvent(QMouseEvent *event)
{
    // map element's flickable may use the event
    if (parentItem() && qobject_cast<QDeclarativeGeoMap*>(parentItem()))
        qobject_cast<QDeclarativeGeoMap*>(parentItem())->mouseEvent(event);
    QQuickMouseArea::mouseReleaseEvent(event);
}

void QDeclarativeGeoMapMouseArea::mouseDoubleClickEvent(QMouseEvent *event)
{
    QQuickMouseArea::mouseDoubleClickEvent(event);
}

void QDeclarativeGeoMapMouseArea::mouseMoveEvent(QMouseEvent *event)
{
    // map element's flickable may use the event
    if (parentItem() && qobject_cast<QDeclarativeGeoMap*>(parentItem()))
        qobject_cast<QDeclarativeGeoMap*>(parentItem())->mouseEvent(event);
    QQuickMouseArea::mouseMoveEvent(event);
}

/*!
    \qmlproperty real QtLocation5::MapMouseArea::mouseX
    \qmlproperty real QtLocation5::MapMouseArea::mouseY

    These properties hold the screen coordinates of the mouse cursor.

    These properties will only be valid while a button is pressed, and will remain
    valid as long as the button is held down even if the mouse is moved outside the area.

    The screen coordinates are relative to the MapMouseArea.
*/

/*!
    \qmlproperty bool QtLocation5::MapMouseArea::containsMouse
    This property holds whether the mouse is currently inside the mouse area.

    \warning This property is not updated if the area moves under the mouse: \e containsMouse will not change.
    In addition, containsMouse will only be valid when the mouse is pressed.
*/

/*!
    \qmlproperty bool QtLocation5::MapMouseArea::pressed
    This property holds whether the mouse area is currently pressed.
*/

/*!
    \qmlproperty bool QtLocation5::MapMouseArea::enabled
    This property holds whether the item accepts mouse events.

    By default, this property is true.
*/

/*!
    \qmlproperty MouseButton QtLocation5::MapMouseArea::pressedButtons
    This property holds the mouse buttons currently pressed.

    It contains a bitwise combination of:
    \list
    \o Qt.LeftButton
    \o Qt.RightButton
    \o Qt.MiddleButton
    \endlist

    \sa acceptedButtons
*/

/*!
    \qmlproperty Qt::MouseButtons QtLocation5::MapMouseArea::acceptedButtons
    This property holds the mouse buttons that the mouse area reacts to.

    The available buttons are:
    \list
    \o Qt.LeftButton
    \o Qt.RightButton
    \o Qt.MiddleButton
    \endlist

    To accept more than one button the flags can be combined with the
    "|" (or) operator:

    \code
    MapMouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton }
    \endcode

    The default value is \c Qt.LeftButton.
*/

/*!
    \qmlsignal QtLocation5::MapMouseArea::onPressed(MapMouseEvent mouse)

    This handler is called when there is a press.

    The \l {MapMouseEvent}{mouse} parameter provides information about the
    press, including the x and y position and which button was pressed.

    The \l {MapMouseEvent}{accepted} property of the MapMouseEvent parameter determines whether
    this MapMouseArea will handle the press and all future mouse events until
    release.  The default is to accept the event and not allow other
    MapMouseArea beneath this one to handle the event.  If \l {MapMouseEvent}{accepted}
    is set to false, no further events will be sent to this MapMouseArea until
    the button is next pressed.
*/

/*!
    \qmlsignal QtLocation5::MapMouseArea::onReleased(MapMouseEvent mouse)

    This handler is called when there is a release.
    The \l {MapMouseEvent}{mouse} parameter provides information about the
    click, including the x and y position of the release of the click.

    The \l {MapMouseEvent}{accepted} property of the MapMouseEvent parameter is ignored
    in this handler.
*/

/*!
    \qmlsignal QtLocation5::MapMouseArea::onClicked(MapMouseEvent mouse)

    This handler is called when there is a click. A click is defined as a
    press followed by a release, both inside the MapMouseArea (pressing,
    moving outside the MapMouseArea, and then moving back inside and
    releasing is also considered a click).

    The \l {MapMouseEvent}{mouse} parameter provides information about the
    click, including the x and y position of the release of the click.

    The \l {MapMouseEvent}{accepted} property of the MapMouseEvent parameter is ignored in
    this handler.
*/

/*!
    \qmlsignal QtLocation5::MapMouseArea::onDoubleClicked(MapMouseEvent mouse)

    This handler is called when there is a double-click (a press followed
    by a release followed by a press).

    The \l {MapMouseEvent}{mouse} parameter provides information about the
    click, including the x and y position of the release of the click.

    If the \l {MapMouseEvent}{accepted} property of the \l {MapMouseEvent}{mouse} parameter is
    set to false in the handler, the onPressed/onReleased/onClicked handlers
    will be called for the second click; otherwise they are suppressed.
    The accepted property defaults to true.
*/

/*!
    \qmlsignal QtLocation5::MapMouseArea::onEntered()

    This handler is called when the mouse enters the mouse area.

    The onEntered handler is only called while a button is
    pressed.

    \sa onExited()
*/

/*!
    \qmlsignal QtLocation5::MapMouseArea::onPositionChanged(MapMouseEvent mouse)

    This handler is called when the mouse position changes.

    The \l {MapMouseEvent}{mouse} parameter provides information about the mouse, including the x and y
    position, and any buttons currently pressed.

    The \e accepted property of the MapMouseEvent parameter is ignored in this handler.

    The onPositionChanged handler is only called while a button is pressed.
*/

/*!
    \qmlsignal QtLocation5::MapMouseArea::onPressAndHold(MapMouseEvent mouse)

    This handler is called when there is a long press (currently 800ms).
    The \l {MapMouseEvent}{mouse} parameter provides information about the press, including the x and y
    position of the press, and which button is pressed.

    The \e accepted property of the MapMouseEvent parameter is ignored in this handler.
*/

/*!
    \qmlsignal QtLocation5::MapMouseArea::onExited()

    This handler is called when the mouse exits the mouse area.

    The onExited handler is only called while a button is pressed.

    \sa onEntered()
*/

#include "moc_qdeclarativegeomapmousearea_p.cpp"

QT_END_NAMESPACE