From 560f934ff534fda276faba9ce232c5f70cc166a6 Mon Sep 17 00:00:00 2001
From: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com>
Date: Thu, 1 Oct 2015 11:31:49 +0200
Subject: Doc: add docs for uncreatable WebEngineHistory type

Accessible by using the WebEngineView.navigationHistory
property.

Task-number: QTBUG-47908
Change-Id: Ib1baaa7690b0ca16ee67e76bc9ea2ece3d254f55
Reviewed-by: Peter Varga <pvarga@inf.u-szeged.hu>
Reviewed-by: Kai Koehne <kai.koehne@theqtcompany.com>
---
 src/webengine/api/qquickwebenginehistory.cpp | 80 ++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/src/webengine/api/qquickwebenginehistory.cpp b/src/webengine/api/qquickwebenginehistory.cpp
index 9a737fbbe..27081703b 100644
--- a/src/webengine/api/qquickwebenginehistory.cpp
+++ b/src/webengine/api/qquickwebenginehistory.cpp
@@ -185,6 +185,65 @@ QQuickWebEngineHistoryPrivate::~QQuickWebEngineHistoryPrivate()
 {
 }
 
+/*!
+    \qmltype WebEngineHistory
+    \instantiates QQuickWebEngineHistory
+    \inqmlmodule QtWebEngine 1.1
+    \since QtWebEngine 1.1
+
+    \brief Data models that represent the history of a web engine page.
+
+    The uncreatable WebEngineHistory type can be accessed by using the
+    \l{WebEngineView::navigationHistory}{WebEngineView.navigationHistory} property.
+
+    The WebEngineHistory type provides the following data models:
+
+    \list
+        \li \c backItems, which contains the URLs of visited pages.
+        \li \c forwardItems, which contains the URLs of the pages that were visited after visiting
+            the current page.
+        \li \c items, which contains the URLs of the back and forward items, as well as the URL of
+            the current page.
+    \endlist
+
+    The easiest way to use these models is to use them in a ListView as illustrated by the
+    following code snippet:
+
+    \code
+    ListView {
+        id: historyItemsList
+        anchors.fill: parent
+        model: webEngineView.navigationHistory.items
+        delegate:
+            Text {
+                color: "black"
+                text: model.title + " - " + model.url + " (" + model.offset + ")"
+            }
+    }
+    \endcode
+
+    The ListView shows the content of the corresponding model. The delegate is responsible for the
+    format of the list items. The appearance of each item of the list in the delegate can be defined
+    separately (it is not web engine specific).
+
+    The model roles \c title and \c url specify the title and URL of the visited page. The \c offset
+    role specifies the position of the page in respect to the current page (0). A positive number
+    indicates that the page was visited after the current page, whereas a negative number indicates
+    that the page was visited before the current page.
+
+    The data models can also be used to create a menu, as illustrated by the following code
+    snippet:
+
+    \quotefromfile quicknanobrowser/browserwindow.qml
+    \skipto ToolBar
+    \printuntil onObjectRemoved
+    \printuntil }
+    \printuntil }
+    \printuntil }
+
+    For the complete example, see \l{WebEngine Quick Nano Browser}.
+*/
+
 QQuickWebEngineHistory::QQuickWebEngineHistory(QQuickWebEngineViewPrivate *view)
     : d_ptr(new QQuickWebEngineHistoryPrivate(view))
 {
@@ -194,6 +253,13 @@ QQuickWebEngineHistory::~QQuickWebEngineHistory()
 {
 }
 
+/*!
+    \qmlproperty QQuickWebEngineHistoryListModel WebEngineHistory::items
+    \readonly
+    \since QtWebEngine 1.1
+
+    URLs of back items, forward items, and the current item in the history.
+*/
 QQuickWebEngineHistoryListModel *QQuickWebEngineHistory::items() const
 {
     Q_D(const QQuickWebEngineHistory);
@@ -202,6 +268,13 @@ QQuickWebEngineHistoryListModel *QQuickWebEngineHistory::items() const
     return d->m_navigationModel.data();
 }
 
+/*!
+    \qmlproperty QQuickWebEngineHistoryListModel WebEngineHistory::backItems
+    \readonly
+    \since QtWebEngine 1.1
+
+    URLs of visited pages.
+*/
 QQuickWebEngineHistoryListModel *QQuickWebEngineHistory::backItems() const
 {
     Q_D(const QQuickWebEngineHistory);
@@ -210,6 +283,13 @@ QQuickWebEngineHistoryListModel *QQuickWebEngineHistory::backItems() const
     return d->m_backNavigationModel.data();
 }
 
+/*!
+    \qmlproperty QQuickWebEngineHistoryListModel WebEngineHistory::forwardItems
+    \readonly
+    \since QtWebEngine 1.1
+
+    URLs of the pages that were visited after visiting the current page.
+*/
 QQuickWebEngineHistoryListModel *QQuickWebEngineHistory::forwardItems() const
 {
     Q_D(const QQuickWebEngineHistory);
-- 
cgit v1.2.3