/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example webenginewidgets/maps
    \title WebEngine Widgets Maps Example
    \ingroup webengine-widgetexamples
    \brief Demonstrates how to handle geolocation requests

    \image maps-example.png

    \e {Maps} demonstrates how to handle geolocation requests originating from
    a \l QWebEnginePage.

    The \l {https://www.w3.org/TR/geolocation-API/}{Geolocation API} is a
    JavaScript API that web applications can use to determine the user's
    physical location to show on a map, for example. As Qt WebEngine relies on
    \l {Qt Location} to power this API a viable location backend is needed for
    the target platform.

    To avoid accidentally sending location information to third parties
    geolocation requests are denied by default. This example demonstrates the
    steps an application must take in order to start accepting these requests.

    \include examples-run.qdocinc

    \section1 The Code

    The example program consists of a single class, \c MainWindow, inheriting
    from \l QMainWindow:

    \quotefromfile webenginewidgets/maps/mainwindow.h
    \skipto #include
    \printuntil /^\}/

    In the constructor we first set up the \l QWebEngineView as the central
    widget:

    \quotefromfile webenginewidgets/maps/mainwindow.cpp
    \skipto MainWindow::MainWindow
    \printuntil setCentralWidget

    We then proceed to connect a lambda function to the \l
    QWebEnginePage::featurePermissionRequested signal:

    \skipto m_view->page()
    \printuntil QWebEnginePage::Feature

    This signal is emitted whenever a web page requests to make use of a certain
    feature or device, including not only location services but also audio
    capture devices or mouse locking, for example. In this example we only
    handle requests for location services:

    \printuntil return

    Now comes the part where we actually ask the user for permission:

    \printuntil securityOrigin
    \printuntil });

    Note that the question includes the host component of the web site's URI (\c
    securityOrigin) to inform the user as to exactly which web site will be
    receiving their location data.

    We use the \l QWebEnginePage::setFeaturePermission method to communicate the
    user's answer back to the web page.

    Finally we ask the \l QWebEnginePage to load the web page that might want to
    use location services:

    \printuntil /^\}/

    \sa {html5-geolocation}{Qt WebEngine HTML5 Geolocation}, {Qt Location}
*/
