Add a minimal example for the WebEngineAction API

It shows how to bind actions to tool buttons and how to create a custom
context menu.

Task-number: QTBUG-70253
Change-Id: Ie70e88e454a6707f430f230aff1b49b0b2303799
Reviewed-by: Jüri Valdmann <juri.valdmann@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>

7 files changed, 318 insertions, 1 deletions

diff --git a/examples/webengine/webengine.pro b/examples/webengine/webengine.pro
index b20b8f118..5ad620390 100644
--- a/examples/webengine/webengine.pro
+++ b/examples/webengine/webengine.pro
@@ -3,7 +3,8 @@ TEMPLATE=subdirs
 SUBDIRS += \
     customdialogs \
     minimal \
-    quicknanobrowser
+    quicknanobrowser \
+    webengineaction
 
 qtHaveModule(quickcontrols2) {
     SUBDIRS += \
diff --git a/examples/webengine/webengineaction/doc/images/webengineaction-example.png b/examples/webengine/webengineaction/doc/images/webengineaction-example.png
new file mode 100644
index 000000000..2e34bbf63
--- /dev/null
+++ b/examples/webengine/webengineaction/doc/images/webengineaction-example.png
diff --git a/examples/webengine/webengineaction/doc/src/webengineaction.qdoc b/examples/webengine/webengineaction/doc/src/webengineaction.qdoc
new file mode 100644
index 000000000..672f86f0f
--- /dev/null
+++ b/examples/webengine/webengineaction/doc/src/webengineaction.qdoc
@@ -0,0 +1,68 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 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 webengine/webengineaction
+    \title WebEngine Action Example
+    \ingroup webengine-examples
+    \brief A simple browser implemented using WebEngineActions.
+
+    \image webengineaction-example.png
+
+    \e {WebEngine Action Example} demonstrates how to perform actions on a web page
+    using the \l{WebEngineAction} type. It shows the minimum amount of code needed
+    to bind browser functionalities to input elements and build up a custom context
+    menu.
+
+    \include examples-run.qdocinc
+
+    \section1 Working With Web Engine Actions
+
+    An intended use of \l{WebEngineAction} is building a connection between UI
+    elements and browser commands. It can be added to menus and toolbars via
+    assigning its properties to the corresponding ones of the element.
+
+    The \l{ToolButton} relies on the properties provided by a
+    \l{WebEngineAction}. Clicking the button triggers backwards navigation on the
+    originating \l{WebEngineView} of the action.
+
+    \quotefromfile webengine/webengineaction/main.qml
+    \skipto ToolButton {
+    \printuntil }
+
+    The simplest way to create custom context menus is enumerating the required
+    \l{WebEngineAction} types in a data model and instantiating \l{MenuItem} types
+    for them, for example using a \l{Repeater}.
+
+    \quotefromfile webengine/webengineaction/main.qml
+    \skipto property Menu contextMenu: Menu {
+    \printuntil /^ {8}\}/
+
+    Assigning a \l{WebEngineAction} to multiple UI elements will keep them in sync.
+    As it can be seen in the picture above, if the browser engine disables a
+    navigation action, both corresponding menu items will be disabled.
+*/
diff --git a/examples/webengine/webengineaction/main.cpp b/examples/webengine/webengineaction/main.cpp
new file mode 100644
index 000000000..ce723a99b
--- /dev/null
+++ b/examples/webengine/webengineaction/main.cpp
@@ -0,0 +1,67 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** 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.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QGuiApplication>
+#include <QQmlApplicationEngine>
+#include <qtwebengineglobal.h>
+
+int main(int argc, char *argv[])
+{
+    QCoreApplication::setOrganizationName("QtExamples");
+    QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
+    QGuiApplication app(argc, argv);
+
+    QtWebEngine::initialize();
+
+    QQmlApplicationEngine engine;
+    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
+
+    return app.exec();
+}
diff --git a/examples/webengine/webengineaction/main.qml b/examples/webengine/webengineaction/main.qml
new file mode 100644
index 000000000..a3933ee41
--- /dev/null
+++ b/examples/webengine/webengineaction/main.qml
@@ -0,0 +1,166 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** 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.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.0
+import QtQuick.Window 2.0
+import QtWebEngine 1.7
+import QtQuick.Controls 2.4
+import QtQuick.Layouts 1.11
+
+ApplicationWindow {
+    id: window
+    visible: true
+    width: 800
+    height: 600
+    title: qsTr("WebEngineAction Example")
+
+    header: ToolBar {
+        RowLayout {
+            anchors.fill: parent
+
+            ToolButton {
+                property int itemAction: WebEngineView.Back
+                text: webEngineView.action(itemAction).text
+                enabled: webEngineView.action(itemAction).enabled
+                onClicked: webEngineView.action(itemAction).trigger()
+                icon.name: webEngineView.action(itemAction).iconName
+                display: AbstractButton.TextUnderIcon
+            }
+
+            ToolButton {
+                property int itemAction: WebEngineView.Forward
+                text: webEngineView.action(itemAction).text
+                enabled: webEngineView.action(itemAction).enabled
+                onClicked: webEngineView.action(itemAction).trigger()
+                icon.name: webEngineView.action(itemAction).iconName
+                display: AbstractButton.TextUnderIcon
+            }
+
+            ToolButton {
+                property int itemAction: webEngineView.loading ? WebEngineView.Stop : WebEngineView.Reload
+                text: webEngineView.action(itemAction).text
+                enabled: webEngineView.action(itemAction).enabled
+                onClicked: webEngineView.action(itemAction).trigger()
+                icon.name: webEngineView.action(itemAction).iconName
+                display: AbstractButton.TextUnderIcon
+            }
+
+            TextField {
+                Layout.fillWidth: true
+
+                text: webEngineView.url
+                selectByMouse: true
+                onEditingFinished: webEngineView.url = text
+            }
+
+            ToolButton {
+                id: settingsButton
+                text: "Settings"
+                icon.name: "settings-configure"
+                display: AbstractButton.TextUnderIcon
+                onClicked: settingsMenu.open()
+                checked: settingsMenu.visible
+
+                Menu {
+                    id: settingsMenu
+                    y: settingsButton.height
+
+                    MenuItem {
+                        id: customContextMenuOption
+                        checkable: true
+                        checked: true
+
+                        text: "Custom context menu"
+                    }
+                }
+            }
+        }
+    }
+
+    WebEngineView {
+        id: webEngineView
+        url: "https://qt.io"
+        anchors.fill: parent
+
+        Component.onCompleted: {
+            profile.downloadRequested.connect(function(download){
+                download.accept();
+            })
+        }
+
+        property Menu contextMenu: Menu {
+            Repeater {
+                model: [
+                    WebEngineView.Back,
+                    WebEngineView.Forward,
+                    WebEngineView.Reload,
+                    WebEngineView.SavePage,
+                    WebEngineView.Copy,
+                    WebEngineView.Paste,
+                    WebEngineView.Cut
+                ]
+                MenuItem {
+                    text: webEngineView.action(modelData).text
+                    enabled: webEngineView.action(modelData).enabled
+                    onClicked: webEngineView.action(modelData).trigger()
+                    icon.name: webEngineView.action(modelData).iconName
+                    display: MenuItem.TextBesideIcon
+                }
+            }
+        }
+
+        onContextMenuRequested: function(request) {
+            if (customContextMenuOption.checked) {
+                request.accepted = true;
+                contextMenu.popup();
+            }
+        }
+    }
+}
diff --git a/examples/webengine/webengineaction/qml.qrc b/examples/webengine/webengineaction/qml.qrc
new file mode 100644
index 000000000..5f6483ac3
--- /dev/null
+++ b/examples/webengine/webengineaction/qml.qrc
@@ -0,0 +1,5 @@
+<RCC>
+    <qresource prefix="/">
+        <file>main.qml</file>
+    </qresource>
+</RCC>
diff --git a/examples/webengine/webengineaction/webengineaction.pro b/examples/webengine/webengineaction/webengineaction.pro
new file mode 100644
index 000000000..13cc4602d
--- /dev/null
+++ b/examples/webengine/webengineaction/webengineaction.pro
@@ -0,0 +1,10 @@
+TEMPLATE = app
+
+QT += webengine
+
+SOURCES += main.cpp
+
+RESOURCES += qml.qrc
+
+target.path = $$[QT_INSTALL_EXAMPLES]/webengine/webengineaction
+INSTALLS += target