Combine QPdfDestination and QPdfSearchResult into QPdfLink

Inheritance was a decent way to model this, conceptually. A hyperlink
is modeled like the HTML kind: a region covering the source material
that the user will click on, and a destination where we will jump when
they click it; whereas a search result has the same information plus the
text before and after the search text, so that we can show some context
in a ListView with search results.

By going this way, we need to document which fields we use which way
under which conditions. But, we have a rule that value types cannot use
inheritance, just in case the user would ever try to use them
polymorphically (in spite of the other rule that we never pass value
types by pointer, and thus there is no actual polymorphism), or just
in case the destructor of the base class would not be called when
a subclass value goes out of scope.

Anyway, perhaps an upside is that this resembles a link in Xanadu, or in
a fully-normalized database schema: an object that fully describes both
ends of a connection, and thus is able to traverse either direction, in
theory. (Although we don't really use it that way. The link-following
behavior in a PDF viewer tends to be one-way, as in a web browser.)

When using QAbstractItemModel (as in QPdfSearchModel and QPdfLinkModel),
the cells in the "database" are accessed separately via the data()
function, so there is no need for a transport object to hold a whole
"row". That's OK for item views; but we need this link object for the
purpose of less-clumsy C++ API, as a return value from a few functions.
For example when implementing a viewer in QML, we use Repeater to
instantiate Items for each hyperlink (decorations and a TapHandler),
and Repeater uses the QAIM interface. But when implementing a
widget-based viewer, it's better to call a hit-testing function like
QPdfLinkModel::linkAt(pos) to find out whether a link exists at a
particular mouse location; and that function can return a QPdfLink.
In this case, the link will not contain contextBefore and contextAfter,
because the viewer doesn't need them, and it's difficult to find this
text in the PDF model. But QPdfSearchModel::resultsOnPage() and
reultAtIndex() return link objects that do contain the context strings.

We don't expect users to have made much use of these classes in C++
so far, because we prioritized QML API (which this change does not
affect), and did not yet document how to use QPdfSearchModel and
QPdfLinkModel in widget-based viewers.

Fixes: QTBUG-98886
Change-Id: Ie68f9b893a342d145abac0b143e9254827c70bd7
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

2 files changed, 3 insertions, 3 deletions

diff --git a/src/pdfquick/qquickpdfnavigationstack.cpp b/src/pdfquick/qquickpdfnavigationstack.cpp
index 3992322e9..3e0f18576 100644
--- a/src/pdfquick/qquickpdfnavigationstack.cpp
+++ b/src/pdfquick/qquickpdfnavigationstack.cpp
@@ -193,7 +193,7 @@ void QQuickPdfNavigationStack::push(int page, QPointF location, qreal zoom, bool
     if (!m_changing) {
         if (m_currentHistoryIndex >= 0 && forwardAvailableWas)
             m_pageHistory.remove(m_currentHistoryIndex + 1, m_pageHistory.count() - m_currentHistoryIndex - 1);
-        m_pageHistory.append(QExplicitlySharedDataPointer<QPdfDestinationPrivate>(new QPdfDestinationPrivate(page, location, zoom)));
+        m_pageHistory.append(QExplicitlySharedDataPointer<QPdfLinkPrivate>(new QPdfLinkPrivate(page, location, zoom)));
         m_currentHistoryIndex = m_pageHistory.count() - 1;
     }
     emit currentZoomChanged();
diff --git a/src/pdfquick/qquickpdfnavigationstack_p.h b/src/pdfquick/qquickpdfnavigationstack_p.h
index 7c69c3c66..2c8b591e9 100644
--- a/src/pdfquick/qquickpdfnavigationstack_p.h
+++ b/src/pdfquick/qquickpdfnavigationstack_p.h
@@ -53,7 +53,7 @@
 
 #include <QtPdfQuick/private/qtpdfquickglobal_p.h>
 #include <QtPdfQuick/private/qquickpdfdocument_p.h>
-#include <QtPdf/private/qpdfdestination_p.h>
+#include <QtPdf/private/qpdflink_p.h>
 
 #include <QQmlEngine>
 
@@ -95,7 +95,7 @@ Q_SIGNALS:
     void jumped(int page, QPointF location, qreal zoom);
 
 private:
-    QList<QExplicitlySharedDataPointer<QPdfDestinationPrivate>> m_pageHistory;
+    QList<QExplicitlySharedDataPointer<QPdfLinkPrivate>> m_pageHistory;
     int m_currentHistoryIndex = 0;
     bool m_changing = false;