Adapt the QtHelp API according to recent QMap changes

The usage of QMap as a multi map has just been deprecated.
Adapt the QtHelp API accordingly. Introduce QHelpLink data
structure.

Fixes: QTBUG-82334
Change-Id: I8ff15710b1a433ddcb3000e5bcf58790c983e63f
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

19 files changed, 374 insertions, 89 deletions

diff --git a/src/assistant/assistant/helpenginewrapper.cpp b/src/assistant/assistant/helpenginewrapper.cpp
index d69138ff8..c927a2ef1 100644
--- a/src/assistant/assistant/helpenginewrapper.cpp
+++ b/src/assistant/assistant/helpenginewrapper.cpp
@@ -41,6 +41,7 @@
 #include <QtHelp/QHelpEngine>
 #include <QtHelp/QHelpFilterEngine>
 #include <QtHelp/QHelpIndexModel>
+#include <QtHelp/QHelpLink>
 #include <QtHelp/QHelpSearchEngine>
 
 QT_BEGIN_NAMESPACE
@@ -261,10 +262,10 @@ QByteArray HelpEngineWrapper::fileData(const QUrl &url) const
     return d->m_helpEngine->fileData(url);
 }
 
-QMap<QString, QUrl> HelpEngineWrapper::linksForIdentifier(const QString &id) const
+QList<QHelpLink> HelpEngineWrapper::documentsForIdentifier(const QString &id) const
 {
     TRACE_OBJ
-    return d->m_helpEngine->linksForIdentifier(id);
+    return d->m_helpEngine->documentsForIdentifier(id);
 }
 
 QString HelpEngineWrapper::error() const
diff --git a/src/assistant/assistant/helpenginewrapper.h b/src/assistant/assistant/helpenginewrapper.h
index 81d8ffa1f..df2ec8a73 100644
--- a/src/assistant/assistant/helpenginewrapper.h
+++ b/src/assistant/assistant/helpenginewrapper.h
@@ -47,6 +47,7 @@ class QHelpIndexWidget;
 class QHelpSearchEngine;
 class QHelpFilterEngine;
 class QHelpEngineCore;
+struct QHelpLink;
 
 enum {
     ShowHomePage = 0,
@@ -80,7 +81,7 @@ public:
     bool unregisterDocumentation(const QString &namespaceName);
     QUrl findFile(const QUrl &url) const;
     QByteArray fileData(const QUrl &url) const;
-    QMap<QString, QUrl> linksForIdentifier(const QString &id) const;
+    QList<QHelpLink> documentsForIdentifier(const QString &id) const;
     QString error() const;
 
     QHelpFilterEngine *filterEngine() const;
diff --git a/src/assistant/assistant/indexwindow.cpp b/src/assistant/assistant/indexwindow.cpp
index d8c0f8212..c0647ca6f 100644
--- a/src/assistant/assistant/indexwindow.cpp
+++ b/src/assistant/assistant/indexwindow.cpp
@@ -44,6 +44,8 @@
 #include <QtWidgets/QListWidgetItem>
 
 #include <QtHelp/QHelpIndexWidget>
+#include <QtHelp/QHelpEngineCore>
+#include <QtHelp/QHelpLink>
 
 QT_BEGIN_NAMESPACE
 
@@ -71,10 +73,12 @@ IndexWindow::IndexWindow(QWidget *parent)
             this, &IndexWindow::disableSearchLineEdit);
     connect(helpEngine.indexModel(), &QHelpIndexModel::indexCreated,
             this, &IndexWindow::enableSearchLineEdit);
-    connect(m_indexWidget, &QHelpIndexWidget::linkActivated,
-            this, &IndexWindow::linkActivated);
-    connect(m_indexWidget, &QHelpIndexWidget::linksActivated,
-            this, &IndexWindow::linksActivated);
+    connect(m_indexWidget, &QHelpIndexWidget::documentActivated,
+            this, [this](const QHelpLink &link) {
+        emit linkActivated(link.url);
+    });
+    connect(m_indexWidget, &QHelpIndexWidget::documentsActivated,
+            this, &IndexWindow::documentsActivated);
     connect(m_searchLineEdit, &QLineEdit::returnPressed,
             m_indexWidget, &QHelpIndexWidget::activateCurrentItem);
     layout->addWidget(m_indexWidget);
@@ -196,15 +200,15 @@ void IndexWindow::open(QHelpIndexWidget* indexWidget, const QModelIndex &index)
     QHelpIndexModel *model = qobject_cast<QHelpIndexModel*>(indexWidget->model());
     if (model) {
         const QString keyword = model->data(index, Qt::DisplayRole).toString();
-        const QMap<QString, QUrl> links = model->linksForKeyword(keyword);
+        const QList<QHelpLink> docs = model->helpEngine()->documentsForKeyword(keyword);
 
         QUrl url;
-        if (links.count() > 1) {
-            TopicChooser tc(this, keyword, links);
+        if (docs.count() > 1) {
+            TopicChooser tc(this, keyword, docs);
             if (tc.exec() == QDialog::Accepted)
                 url = tc.link();
-        } else if (!links.isEmpty()) {
-            url = links.first();
+        } else if (!docs.isEmpty()) {
+            url = docs.first().url;
         } else {
             return;
         }
diff --git a/src/assistant/assistant/indexwindow.h b/src/assistant/assistant/indexwindow.h
index 647d3b3b9..be82543dd 100644
--- a/src/assistant/assistant/indexwindow.h
+++ b/src/assistant/assistant/indexwindow.h
@@ -37,6 +37,7 @@ QT_BEGIN_NAMESPACE
 
 class QHelpIndexWidget;
 class QModelIndex;
+struct QHelpLink;
 
 class IndexWindow : public QWidget
 {
@@ -54,8 +55,7 @@ public:
 
 signals:
     void linkActivated(const QUrl &link);
-    void linksActivated(const QMap<QString, QUrl> &links,
-        const QString &keyword);
+    void documentsActivated(const QList<QHelpLink> &documents, const QString &keyword);
     void escapePressed();
 
 private slots:
diff --git a/src/assistant/assistant/mainwindow.cpp b/src/assistant/assistant/mainwindow.cpp
index 56312583d..5b0163fb1 100644
--- a/src/assistant/assistant/mainwindow.cpp
+++ b/src/assistant/assistant/mainwindow.cpp
@@ -681,7 +681,7 @@ void MainWindow::setupActions()
     // index window
     connect(m_indexWindow, &IndexWindow::linkActivated,
             m_centralWidget, &CentralWidget::setSource);
-    connect(m_indexWindow, &IndexWindow::linksActivated,
+    connect(m_indexWindow, &IndexWindow::documentsActivated,
             this, &MainWindow::showTopicChooser);
     connect(m_indexWindow, &IndexWindow::escapePressed,
             this, &MainWindow::activateCurrentCentralWidgetTab);
@@ -821,11 +821,11 @@ void MainWindow::gotoAddress()
     m_centralWidget->setSource(m_addressLineEdit->text());
 }
 
-void MainWindow::showTopicChooser(const QMap<QString, QUrl> &links,
+void MainWindow::showTopicChooser(const QList<QHelpLink> &documents,
                                   const QString &keyword)
 {
     TRACE_OBJ
-    TopicChooser tc(this, keyword, links);
+    TopicChooser tc(this, keyword, documents);
     if (tc.exec() == QDialog::Accepted) {
         m_centralWidget->setSource(tc.link());
     }
diff --git a/src/assistant/assistant/mainwindow.h b/src/assistant/assistant/mainwindow.h
index c5bf5837e..b9d86cfc7 100644
--- a/src/assistant/assistant/mainwindow.h
+++ b/src/assistant/assistant/mainwindow.h
@@ -46,6 +46,7 @@ class ContentWindow;
 class IndexWindow;
 class QtDocInstaller;
 class SearchWidget;
+struct QHelpLink;
 
 class MainWindow : public QMainWindow
 {
@@ -88,7 +89,7 @@ private slots:
     void showNewAddress();
     void showAboutDialog();
     void showNewAddress(const QUrl &url);
-    void showTopicChooser(const QMap<QString, QUrl> &links, const QString &keyword);
+    void showTopicChooser(const QList<QHelpLink> &documents, const QString &keyword);
     void updateApplicationFont();
     void filterDocumentation(int filterIndex);
     void setupFilterCombo();
diff --git a/src/assistant/assistant/remotecontrol.cpp b/src/assistant/assistant/remotecontrol.cpp
index 7fdbee41e..0c9cc6c14 100644
--- a/src/assistant/assistant/remotecontrol.cpp
+++ b/src/assistant/assistant/remotecontrol.cpp
@@ -44,6 +44,7 @@
 #include <QtHelp/QHelpEngine>
 #include <QtHelp/QHelpFilterEngine>
 #include <QtHelp/QHelpIndexWidget>
+#include <QtHelp/QHelpLink>
 #include <QtHelp/QHelpSearchQueryWidget>
 
 #ifdef Q_OS_WIN
@@ -199,9 +200,9 @@ void RemoteControl::handleActivateIdentifierCommand(const QString &arg)
         clearCache();
         m_activateIdentifier = arg;
     } else {
-        const QMap<QString, QUrl> links = helpEngine.linksForIdentifier(arg);
-        if (!links.isEmpty())
-            CentralWidget::instance()->setSource(links.first());
+        const auto docs = helpEngine.documentsForIdentifier(arg);
+        if (!docs.isEmpty())
+            CentralWidget::instance()->setSource(docs.first().url);
     }
 }
 
@@ -266,10 +267,10 @@ void RemoteControl::applyCache()
         m_mainWindow->setIndexString(m_activateKeyword);
         helpEngine.indexWidget()->activateCurrentItem();
     } else if (!m_activateIdentifier.isEmpty()) {
-        const QMap<QString, QUrl> links =
-            helpEngine.linksForIdentifier(m_activateIdentifier);
-        if (!links.isEmpty())
-            CentralWidget::instance()->setSource(links.first());
+        const auto docs =
+            helpEngine.documentsForIdentifier(m_activateIdentifier);
+        if (!docs.isEmpty())
+            CentralWidget::instance()->setSource(docs.first().url);
     } else if (!m_currentFilter.isEmpty()) {
         helpEngine.filterEngine()->setActiveFilter(m_currentFilter);
     }
diff --git a/src/assistant/assistant/topicchooser.cpp b/src/assistant/assistant/topicchooser.cpp
index d058646c5..ec9faddb6 100644
--- a/src/assistant/assistant/topicchooser.cpp
+++ b/src/assistant/assistant/topicchooser.cpp
@@ -35,9 +35,11 @@
 #include <QSortFilterProxyModel>
 #include <QUrl>
 
+#include <QtHelp/QHelpLink>
+
 QT_BEGIN_NAMESPACE
 
-TopicChooser::TopicChooser(QWidget *parent, const QString &keyword, const QMap<QString, QUrl> &links)
+TopicChooser::TopicChooser(QWidget *parent, const QString &keyword, const QList<QHelpLink> &docs)
     : QDialog(parent)
     , m_filterModel(new QSortFilterProxyModel(this))
 {
@@ -53,10 +55,10 @@ TopicChooser::TopicChooser(QWidget *parent, const QString &keyword, const QMap<Q
     m_filterModel->setSourceModel(model);
     m_filterModel->setFilterCaseSensitivity(Qt::CaseInsensitive);
 
-    for (auto it = links.cbegin(), end = links.cend(); it != end; ++it) {
-        m_links.append(it.value());
-        QStandardItem *item = new QStandardItem(it.key());
-        item->setToolTip(it.value().toString());
+    for (const auto &doc : docs) {
+        m_links.append(doc.url);
+        QStandardItem *item = new QStandardItem(doc.title);
+        item->setToolTip(doc.url.toString());
         model->appendRow(item);
     }
 
diff --git a/src/assistant/assistant/topicchooser.h b/src/assistant/assistant/topicchooser.h
index 730ad68a0..2406ef99f 100644
--- a/src/assistant/assistant/topicchooser.h
+++ b/src/assistant/assistant/topicchooser.h
@@ -36,13 +36,14 @@
 QT_BEGIN_NAMESPACE
 
 class QSortFilterProxyModel;
+struct QHelpLink;
 
 class TopicChooser : public QDialog
 {
     Q_OBJECT
 
 public:
-    TopicChooser(QWidget *parent, const QString &keyword, const QMap<QString, QUrl> &links);
+    TopicChooser(QWidget *parent, const QString &keyword, const QList<QHelpLink> &docs);
     ~TopicChooser() override;
 
     QUrl link() const;
diff --git a/src/assistant/help/help.pro b/src/assistant/help/help.pro
index ff7a81374..800c4a38d 100644
--- a/src/assistant/help/help.pro
+++ b/src/assistant/help/help.pro
@@ -22,6 +22,7 @@ SOURCES += \
     qhelpdbreader.cpp \
     qhelpcontentwidget.cpp \
     qhelpindexwidget.cpp \
+    qhelplink.cpp \
     qhelpcollectionhandler.cpp \
     qhelpsearchengine.cpp \
     qhelpsearchquerywidget.cpp \
@@ -46,6 +47,7 @@ HEADERS += \
     qhelpdbreader_p.h \
     qhelpcontentwidget.h \
     qhelpindexwidget.h \
+    qhelplink.h \
     qhelpcollectionhandler_p.h \
     qhelpsearchengine.h \
     qhelpsearchquerywidget.h \
diff --git a/src/assistant/help/qhelpcollectionhandler.cpp b/src/assistant/help/qhelpcollectionhandler.cpp
index 427521a9a..29178bb55 100644
--- a/src/assistant/help/qhelpcollectionhandler.cpp
+++ b/src/assistant/help/qhelpcollectionhandler.cpp
@@ -51,6 +51,8 @@
 #include <QtCore/QVector>
 #include <QtCore/QVersionNumber>
 
+#include <QtHelp/QHelpLink>
+
 #include <QtSql/QSqlError>
 #include <QtSql/QSqlDriver>
 
@@ -2375,14 +2377,38 @@ QMap<QString, QUrl> QHelpCollectionHandler::linksForKeyword(const QString &keywo
     return linksForField(QLatin1String("Name"), keyword, filterName);
 }
 
+QList<QHelpLink> QHelpCollectionHandler::documentsForIdentifier(const QString &id,
+                         const QString &filterName) const
+{
+    return documentsForField(QLatin1String("Identifier"), id, filterName);
+}
+
+QList<QHelpLink> QHelpCollectionHandler::documentsForKeyword(const QString &keyword,
+                         const QString &filterName) const
+{
+    return documentsForField(QLatin1String("Name"), keyword, filterName);
+}
+
 QMap<QString, QUrl> QHelpCollectionHandler::linksForField(const QString &fieldName,
                     const QString &fieldValue,
                     const QString &filterName) const
 {
     QMap<QString, QUrl> linkMap;
+    const auto documents = documentsForField(fieldName, fieldValue, filterName);
+    for (const auto &document : documents)
+        static_cast<QMultiMap<QString, QUrl> &>(linkMap).insert(document.title, document.url);
+
+    return linkMap;
+}
+
+QList<QHelpLink> QHelpCollectionHandler::documentsForField(const QString &fieldName,
+                                           const QString &fieldValue,
+                                           const QString &filterName) const
+{
+    QList<QHelpLink> docList;
 
     if (!isDBOpened())
-        return linkMap;
+        return docList;
 
     const QString filterlessQuery = QString::fromLatin1(
                 "SELECT "
@@ -2402,7 +2428,8 @@ QMap<QString, QUrl> QHelpCollectionHandler::linksForField(const QString &fieldNa
                 "AND IndexTable.%1 = ?").arg(fieldName);
 
     const QString filterQuery = filterlessQuery
-            + prepareFilterQuery(filterName);
+            + prepareFilterQuery(filterName)
+            + QLatin1String(" ORDER BY LOWER(FileNameTable.Title), FileNameTable.Title");
 
     m_query->prepare(filterQuery);
     m_query->bindValue(0, fieldValue);
@@ -2415,13 +2442,13 @@ QMap<QString, QUrl> QHelpCollectionHandler::linksForField(const QString &fieldNa
         if (title.isEmpty()) // generate a title + corresponding path
             title = fieldValue + QLatin1String(" : ") + m_query->value(3).toString();
 
-        static_cast<QMultiMap<QString, QUrl> &>(linkMap).insert(title, buildQUrl(
-                                             m_query->value(1).toString(),
-                                             m_query->value(2).toString(),
-                                             m_query->value(3).toString(),
-                                             m_query->value(4).toString()));
+        const QUrl url = buildQUrl(m_query->value(1).toString(),
+                                   m_query->value(2).toString(),
+                                   m_query->value(3).toString(),
+                                   m_query->value(4).toString());
+        docList.append(QHelpLink {url, title});
     }
-    return linkMap;
+    return docList;
 }
 
 QStringList QHelpCollectionHandler::namespacesForFilter(const QString &filterName) const
diff --git a/src/assistant/help/qhelpcollectionhandler_p.h b/src/assistant/help/qhelpcollectionhandler_p.h
index 5c0170d8c..83178f388 100644
--- a/src/assistant/help/qhelpcollectionhandler_p.h
+++ b/src/assistant/help/qhelpcollectionhandler_p.h
@@ -65,6 +65,7 @@ QT_BEGIN_NAMESPACE
 
 class QVersionNumber;
 class QHelpFilterData;
+struct QHelpLink;
 
 class QHelpCollectionHandler : public QObject
 {
@@ -153,6 +154,13 @@ public:
     QMap<QString, QUrl> linksForKeyword(const QString &keyword,
                                         const QStringList &filterAttributes) const;
 
+    // use documentsForIdentifier instead
+    QMap<QString, QUrl> linksForIdentifier(const QString &id,
+                                           const QString &filterName) const;
+
+    // use documentsForKeyword instead
+    QMap<QString, QUrl> linksForKeyword(const QString &keyword,
+                                        const QString &filterName) const;
     // *** Legacy block end ***
 
     QStringList filters() const;
@@ -196,10 +204,11 @@ public:
     int registerComponent(const QString &componentName, int namespaceId);
     bool registerVersion(const QString &version, int namespaceId);
 
-    QMap<QString, QUrl> linksForIdentifier(const QString &id,
-                                           const QString &filterName) const;
-    QMap<QString, QUrl> linksForKeyword(const QString &keyword,
-                                        const QString &filterName) const;
+    QList<QHelpLink> documentsForIdentifier(const QString &id,
+                                            const QString &filterName) const;
+    QList<QHelpLink> documentsForKeyword(const QString &keyword,
+                                         const QString &filterName) const;
+
     QStringList namespacesForFilter(const QString &filterName) const;
 
     void setReadOnly(bool readOnly);
@@ -217,6 +226,10 @@ private:
     QMap<QString, QUrl> linksForField(const QString &fieldName,
                                       const QString &fieldValue,
                                       const QString &filterName) const;
+    QList<QHelpLink> documentsForField(const QString &fieldName,
+                                       const QString &fieldValue,
+                                       const QString &filterName) const;
+
     bool isDBOpened() const;
     bool createTables(QSqlQuery *query);
     void closeDB();
diff --git a/src/assistant/help/qhelpengine_p.h b/src/assistant/help/qhelpengine_p.h
index 558013e77..4d2773b83 100644
--- a/src/assistant/help/qhelpengine_p.h
+++ b/src/assistant/help/qhelpengine_p.h
@@ -97,7 +97,6 @@ private slots:
     void errorReceived(const QString &msg);
 };
 
-
 class QHelpEnginePrivate : public QHelpEngineCorePrivate
 {
     Q_OBJECT
diff --git a/src/assistant/help/qhelpenginecore.cpp b/src/assistant/help/qhelpenginecore.cpp
index c9fbde232..6f1a7a840 100644
--- a/src/assistant/help/qhelpenginecore.cpp
+++ b/src/assistant/help/qhelpenginecore.cpp
@@ -48,6 +48,7 @@
 #include <QtCore/QPluginLoader>
 #include <QtCore/QFileInfo>
 #include <QtCore/QThread>
+#include <QtHelp/QHelpLink>
 #include <QtWidgets/QApplication>
 #include <QtSql/QSqlQuery>
 
@@ -110,12 +111,9 @@ void QHelpEngineCorePrivate::errorReceived(const QString &msg)
     undefined meaning unusable state.
 
     The core help engine can be used to perform different tasks.
-    By calling linksForIdentifier() the engine returns
+    By calling documentsForIdentifier() the engine returns
     URLs specifying the file locations inside the help system. The
-    actual file data can then be retrived by calling fileData(). In
-    contrast to all other functions in this class, linksForIdentifier()
-    depends on the currently set custom filter. Depending on the filter,
-    the function may return different results.
+    actual file data can then be retrived by calling fileData().
 
     The help engine can contain any number of custom filters.
     The management of the filters, including adding new filters,
@@ -612,7 +610,12 @@ QByteArray QHelpEngineCore::fileData(const QUrl &url) const
     return d->collectionHandler->fileData(url);
 }
 
+#if QT_DEPRECATED_SINCE(5, 15)
 /*!
+    \obsolete
+
+    Use documentsForIdentifier() instead.
+
     Returns a map of the documents found for the \a id. The map contains the
     document titles and their URLs. The returned map contents depend on
     the current filter, and therefore only the identifiers registered for
@@ -620,33 +623,53 @@ QByteArray QHelpEngineCore::fileData(const QUrl &url) const
 */
 QMap<QString, QUrl> QHelpEngineCore::linksForIdentifier(const QString &id) const
 {
-    return linksForIdentifier(id, d->usesFilterEngine
-                              ? d->filterEngine->activeFilter()
-                              : d->currentFilter);
+    if (!d->setup())
+        return QMap<QString, QUrl>();
+
+    if (d->usesFilterEngine)
+        return d->collectionHandler->linksForIdentifier(id, d->filterEngine->activeFilter());
+
+    // obsolete
+    return d->collectionHandler->linksForIdentifier(id, filterAttributes(d->currentFilter));
 }
+#endif
 
 /*!
     \since 5.15
 
-    Returns a map of the documents found for the \a id, filtered by \a filterName.
-    The map contains the document titles and their URLs. The returned map contents depend on
-    the passed filter, and therefore only the identifiers registered for
-    this filter will be returned. If you want to get all results unfiltered,
-    pass empty string as \a filterName.
+    Returns a list of all the document links found for the \a id.
+    The returned list contents depend on the current filter, and therefore only the keywords
+    registered for the current filter will be returned.
 */
-QMap<QString, QUrl> QHelpEngineCore::linksForIdentifier(const QString &id, const QString &filterName) const
+QList<QHelpLink> QHelpEngineCore::documentsForIdentifier(const QString &id) const
 {
-    if (!d->setup())
-        return QMap<QString, QUrl>();
+    return documentsForIdentifier(id, d->usesFilterEngine
+                                  ? d->filterEngine->activeFilter()
+                                  : d->currentFilter);
+}
 
-    if (d->usesFilterEngine)
-        return d->collectionHandler->linksForIdentifier(id, filterName);
+/*!
+    \since 5.15
 
-    // obsolete
-    return d->collectionHandler->linksForIdentifier(id, filterAttributes(filterName));
+    Returns a list of the document links found for the \a id, filtered by \a filterName.
+    The returned list contents depend on the passed filter, and therefore only the keywords
+    registered for this filter will be returned. If you want to get all results unfiltered,
+    pass empty string as \a filterName.
+*/
+QList<QHelpLink> QHelpEngineCore::documentsForIdentifier(const QString &id, const QString &filterName) const
+{
+    if (!d->setup() || !d->usesFilterEngine)
+        return QList<QHelpLink>();
+
+    return d->collectionHandler->documentsForIdentifier(id, filterName);
 }
 
+#if QT_DEPRECATED_SINCE(5, 15)
 /*!
+    \obsolete
+
+    Use documentsForKeyword() instead.
+
     Returns a map of all the documents found for the \a keyword. The map
     contains the document titles and URLs. The returned map contents depend
     on the current filter, and therefore only the keywords registered for
@@ -654,33 +677,46 @@ QMap<QString, QUrl> QHelpEngineCore::linksForIdentifier(const QString &id, const
 */
 QMap<QString, QUrl> QHelpEngineCore::linksForKeyword(const QString &keyword) const
 {
-    return linksForKeyword(keyword, d->usesFilterEngine
-                           ? d->filterEngine->activeFilter()
-                           : d->currentFilter);
+    if (!d->setup())
+        return QMap<QString, QUrl>();
+
+    if (d->usesFilterEngine)
+        return d->collectionHandler->linksForKeyword(keyword, d->filterEngine->activeFilter());
+
+    // obsolete
+    return d->collectionHandler->linksForKeyword(keyword, filterAttributes(d->currentFilter));
 }
+#endif
 
 /*!
     \since 5.15
 
-    Returns a map of the documents found for the \a keyword, filtered by \a filterName.
-    The map contains the document titles and their URLs. The returned map contents depend on
-    the passed filter, and therefore only the keywords registered for
-    this filter will be returned. If you want to get all results unfiltered,
-    pass empty string as \a filterName.
-
+    Returns a list of all the document links found for the \a keyword.
+    The returned list contents depend on the current filter, and therefore only the keywords
+    registered for the current filter will be returned.
 */
-QMap<QString, QUrl> QHelpEngineCore::linksForKeyword(const QString &keyword, const QString &filterName) const
+QList<QHelpLink> QHelpEngineCore::documentsForKeyword(const QString &keyword) const
 {
-    if (!d->setup())
-        return QMap<QString, QUrl>();
+    return documentsForKeyword(keyword, d->usesFilterEngine
+                               ? d->filterEngine->activeFilter()
+                               : d->currentFilter);
+}
 
-    if (d->usesFilterEngine)
-        return d->collectionHandler->linksForKeyword(keyword, filterName);
+/*!
+    \since 5.15
 
-    // obsolete
-    return d->collectionHandler->linksForKeyword(keyword, filterAttributes(filterName));
-}
+    Returns a list of the document links found for the \a keyword, filtered by \a filterName.
+    The returned list contents depend on the passed filter, and therefore only the keywords
+    registered for this filter will be returned. If you want to get all results unfiltered,
+    pass empty string as \a filterName.
+*/
+QList<QHelpLink> QHelpEngineCore::documentsForKeyword(const QString &keyword, const QString &filterName) const
+{
+    if (!d->setup() || !d->usesFilterEngine)
+        return QList<QHelpLink>();
 
+    return d->collectionHandler->documentsForKeyword(keyword, filterName);
+}
 
 /*!
     Removes the \a key from the settings section in the
diff --git a/src/assistant/help/qhelpenginecore.h b/src/assistant/help/qhelpenginecore.h
index cf0cf96c9..0a5faca55 100644
--- a/src/assistant/help/qhelpenginecore.h
+++ b/src/assistant/help/qhelpenginecore.h
@@ -51,6 +51,7 @@ QT_BEGIN_NAMESPACE
 
 class QHelpEngineCorePrivate;
 class QHelpFilterEngine;
+struct QHelpLink;
 
 class QHELP_EXPORT QHelpEngineCore : public QObject
 {
@@ -102,10 +103,17 @@ public:
                       const QString &extensionFilter = QString());
     QUrl findFile(const QUrl &url) const;
 
+#if QT_DEPRECATED_SINCE(5, 15)
+    QT_DEPRECATED_X("Use documentsForIdentifier() instead")
     QMap<QString, QUrl> linksForIdentifier(const QString &id) const;
-    QMap<QString, QUrl> linksForIdentifier(const QString &id, const QString &filterName) const;
+    QT_DEPRECATED_X("Use documentsForKeyword() instead")
     QMap<QString, QUrl> linksForKeyword(const QString &keyword) const;
-    QMap<QString, QUrl> linksForKeyword(const QString &keyword, const QString &filterName) const;
+#endif
+
+    QList<QHelpLink> documentsForIdentifier(const QString &id) const;
+    QList<QHelpLink> documentsForIdentifier(const QString &id, const QString &filterName) const;
+    QList<QHelpLink> documentsForKeyword(const QString &keyword) const;
+    QList<QHelpLink> documentsForKeyword(const QString &keyword, const QString &filterName) const;
 
     bool removeCustomValue(const QString &key);
     QVariant customValue(const QString &key,
diff --git a/src/assistant/help/qhelpindexwidget.cpp b/src/assistant/help/qhelpindexwidget.cpp
index 73de1489f..ddc21e426 100644
--- a/src/assistant/help/qhelpindexwidget.cpp
+++ b/src/assistant/help/qhelpindexwidget.cpp
@@ -45,6 +45,7 @@
 
 #include <QtCore/QThread>
 #include <QtCore/QMutex>
+#include <QtHelp/QHelpLink>
 #include <QtWidgets/QListView>
 #include <QtWidgets/QHeaderView>
 
@@ -223,13 +224,28 @@ bool QHelpIndexModel::isCreatingIndex() const
 }
 
 /*!
+    \since 5.15
+
+    Returns the associated help engine that manages this model.
+*/
+QHelpEngineCore *QHelpIndexModel::helpEngine() const
+{
+    return d->helpEngine->q;
+}
+
+#if QT_DEPRECATED_SINCE(5, 15)
+/*!
     \obsolete
-    Use QHelpEngineCore::linksForKeyword() instead.
+    Use QHelpEngineCore::documentsForKeyword() instead.
 */
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
 QMap<QString, QUrl> QHelpIndexModel::linksForKeyword(const QString &keyword) const
 {
     return d->helpEngine->q->linksForKeyword(keyword);
 }
+QT_WARNING_POP
+#endif
 
 /*!
     Filters the indices and returns the model index of the best
@@ -307,20 +323,50 @@ QModelIndex QHelpIndexModel::filter(const QString &filter, const QString &wildca
     \fn void QHelpIndexWidget::linkActivated(const QUrl &link,
         const QString &keyword)
 
+    \obsolete
+
+    Use documentActivated() instead.
+
     This signal is emitted when an item is activated and its
     associated \a link should be shown. To know where the link
-    belongs to, the \a keyword is given as a second paremeter.
+    belongs to, the \a keyword is given as a second parameter.
 */
 
 /*!
     \fn void QHelpIndexWidget::linksActivated(const QMap<QString, QUrl> &links,
         const QString &keyword)
 
+    \obsolete
+
+    Use documentsActivated() instead.
+
     This signal is emitted when the item representing the \a keyword
     is activated and the item has more than one link associated.
     The \a links consist of the document titles and their URLs.
 */
 
+/*!
+    \fn void QHelpIndexWidget::documentActivated(const QHelpLink &document,
+        const QString &keyword)
+
+    \since 5.15
+
+    This signal is emitted when an item is activated and its
+    associated \a document should be shown. To know where the link
+    belongs to, the \a keyword is given as a second parameter.
+*/
+
+/*!
+    \fn void QHelpIndexWidget::documentsActivated(const QList<QHelpLink> &documents,
+        const QString &keyword)
+
+    \since 5.15
+
+    This signal is emitted when the item representing the \a keyword
+    is activated and the item has more than one document associated.
+    The \a documents consist of the document titles and their URLs.
+*/
+
 QHelpIndexWidget::QHelpIndexWidget()
     : QListView(nullptr)
 {
@@ -342,11 +388,23 @@ void QHelpIndexWidget::showLink(const QModelIndex &index)
     const QVariant &v = indexModel->data(index, Qt::DisplayRole);
     const QString name = v.isValid() ? v.toString() : QString();
 
-    const QMap<QString, QUrl> &links = indexModel->linksForKeyword(name);
-    if (links.count() > 1)
+    const QList<QHelpLink> &docs = indexModel->helpEngine()->documentsForKeyword(name);
+    if (docs.count() > 1) {
+        emit documentsActivated(docs, name);
+        QT_WARNING_PUSH
+        QT_WARNING_DISABLE_DEPRECATED
+        QMap<QString, QUrl> links;
+        for (const auto &doc : docs)
+            static_cast<QMultiMap<QString, QUrl> &>(links).insert(doc.title, doc.url);
         emit linksActivated(links, name);
-    else if (!links.isEmpty())
-        emit linkActivated(links.first(), name);
+        QT_WARNING_POP
+    } else if (!docs.isEmpty()) {
+        emit documentActivated(docs.first(), name);
+        QT_WARNING_PUSH
+        QT_WARNING_DISABLE_DEPRECATED
+        emit linkActivated(docs.first().url, name);
+        QT_WARNING_POP
+    }
 }
 
 /*!
diff --git a/src/assistant/help/qhelpindexwidget.h b/src/assistant/help/qhelpindexwidget.h
index 58dda5e39..896b0871f 100644
--- a/src/assistant/help/qhelpindexwidget.h
+++ b/src/assistant/help/qhelpindexwidget.h
@@ -50,7 +50,9 @@ QT_BEGIN_NAMESPACE
 
 
 class QHelpEnginePrivate;
+class QHelpEngineCore;
 class QHelpIndexModelPrivate;
+struct QHelpLink;
 
 class QHELP_EXPORT QHelpIndexModel : public QStringListModel
 {
@@ -61,8 +63,12 @@ public:
     QModelIndex filter(const QString &filter,
         const QString &wildcard = QString());
 
+#if QT_DEPRECATED_SINCE(5, 15)
+    QT_DEPRECATED_X("Use QHelpEngineCore::documentsForKeyword() instead")
     QMap<QString, QUrl> linksForKeyword(const QString &keyword) const;
+#endif
     bool isCreatingIndex() const;
+    QHelpEngineCore *helpEngine() const;
 
 Q_SIGNALS:
     void indexCreationStarted();
@@ -84,9 +90,17 @@ class QHELP_EXPORT QHelpIndexWidget : public QListView
     Q_OBJECT
 
 Q_SIGNALS:
+#if QT_DEPRECATED_SINCE(5, 15)
+    QT_DEPRECATED_X("Use documentActivated() instead")
     void linkActivated(const QUrl &link, const QString &keyword);
+    QT_DEPRECATED_X("Use documentsActivated() instead")
     void linksActivated(const QMap<QString, QUrl> &links,
         const QString &keyword);
+#endif
+    void documentActivated(const QHelpLink &document,
+                           const QString &keyword);
+    void documentsActivated(const QList<QHelpLink> &documents,
+                            const QString &keyword);
 
 public Q_SLOTS:
     void filterIndices(const QString &filter,
diff --git a/src/assistant/help/qhelplink.cpp b/src/assistant/help/qhelplink.cpp
new file mode 100644
index 000000000..75cb16ab8
--- /dev/null
+++ b/src/assistant/help/qhelplink.cpp
@@ -0,0 +1,60 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Assistant of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or (at your option) the GNU General
+** Public license version 3 or any later version approved by the KDE Free
+** Qt Foundation. The licenses are as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-2.0.html and
+** https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qhelplink.h"
+
+/*!
+    \class QHelpLink
+    \since 5.15
+    \inmodule QtHelp
+    \brief The QHelpLink struct provides the data associated with a help link.
+
+    The QHelpLink object is a data object that describes a link to a documentation file.
+    The description of the help link contains the document title and URL of the document.
+    \sa QHelpEngineCore
+*/
+
+/*!
+    \variable QHelpLink::url
+    \brief The target url of the link.
+*/
+/*!
+    \variable QHelpLink::title
+    \brief The title of the link.
+*/
diff --git a/src/assistant/help/qhelplink.h b/src/assistant/help/qhelplink.h
new file mode 100644
index 000000000..92b5ec6d0
--- /dev/null
+++ b/src/assistant/help/qhelplink.h
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Assistant of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or (at your option) the GNU General
+** Public license version 3 or any later version approved by the KDE Free
+** Qt Foundation. The licenses are as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-2.0.html and
+** https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QHELPLINK_H
+#define QHELPLINK_H
+
+#include <QtHelp/qhelp_global.h>
+
+#include <QtCore/QUrl>
+
+QT_BEGIN_NAMESPACE
+
+struct QHELP_EXPORT QHelpLink final
+{
+    QUrl url;
+    QString title;
+};
+
+QT_END_NAMESPACE
+
+#endif // QHELPLINK_H