1// Copyright (C) 2018 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qhelpfilterengine.h"
5#include "qhelpcollectionhandler_p.h"
6#include "qhelpenginecore.h"
7#include "qhelpfilterdata.h"
8
9#include <QtCore/qthread.h>
10#include <QtCore/qversionnumber.h>
11
12QT_BEGIN_NAMESPACE
13
14static const char ActiveFilter[] = "activeFilter";
15
16class QHelpFilterEnginePrivate
17{
18public:
19 bool setup();
20
21 QHelpFilterEngine *q = nullptr;
22 QHelpEngineCore *m_helpEngine = nullptr;
23 QHelpCollectionHandler *m_collectionHandler = nullptr;
24 QString m_currentFilter;
25 bool m_needsSetup = true;
26};
27
28bool QHelpFilterEnginePrivate::setup()
29{
30 if (!m_collectionHandler)
31 return false;
32
33 if (!m_needsSetup)
34 return true;
35
36 // Prevent endless loop when connected to setupFinished() signal
37 // and using from there QHelpFilterEngine, causing setup() to be
38 // called in turn.
39 m_needsSetup = false;
40
41 if (!m_helpEngine->setupData()) {
42 m_needsSetup = true;
43 return false;
44 }
45
46 const QString filter = m_collectionHandler->customValue(
47 key: QLatin1StringView(ActiveFilter), defaultValue: QString()).toString();
48 if (!filter.isEmpty() && m_collectionHandler->filters().contains(str: filter))
49 m_currentFilter = filter;
50
51 emit q->filterActivated(newFilter: m_currentFilter);
52 return true;
53}
54
55//////////////
56
57/*!
58 \class QHelpFilterEngine
59 \since 5.13
60 \inmodule QtHelp
61 \brief The QHelpFilterEngine class provides a filtered view of the
62 help contents.
63
64 The filter engine allows the management of filters associated with
65 a QHelpEngineCore instance. The help engine internally creates an
66 instance of the filter engine, which can be accessed by calling
67 QHelpEngineCore::filterEngine(). Therefore, the public constructor
68 of this class is disabled.
69
70 The filters are identified by a filter name string. Filter details are
71 described by the \l QHelpFilterData class.
72
73 The filter engine allows for adding new filters and changing the existing
74 filters' data through the setFilterData() method. An existing filter can
75 be removed through the removeFilter() method.
76
77 Out of the registered filters one can be marked as the active one.
78 The active filter will be used by the associated help engine for returning
79 filtered results of many different functions, such as content, index, or
80 search results. If no filter is marked active, the help engine returns the
81 full results list available.
82
83 The active filter is returned by activeFilter() and it can be changed by
84 setActiveFilter().
85
86 \sa QHelpEngineCore
87*/
88
89/*!
90 \fn void QHelpFilterEngine::filterActivated(const QString &newFilter)
91
92 This signal is emitted when the active filter is set. \a newFilter
93 specifies the name of the filter.
94
95 \sa setActiveFilter()
96*/
97
98/*!
99 \internal
100 Constructs the filter engine for \a helpEngine.
101*/
102QHelpFilterEngine::QHelpFilterEngine(QHelpEngineCore *helpEngine)
103 : QObject(helpEngine),
104 d(new QHelpFilterEnginePrivate)
105{
106 d->q = this;
107 d->m_helpEngine = helpEngine;
108}
109
110/*!
111 \internal
112 Destroys the existing filter engine.
113*/
114QHelpFilterEngine::~QHelpFilterEngine()
115{
116 delete d;
117}
118
119/*!
120 \internal
121 Sets the \a collectionHandler to be used for this filter engine.
122*/
123void QHelpFilterEngine::setCollectionHandler(QHelpCollectionHandler *collectionHandler)
124{
125 d->m_collectionHandler = collectionHandler;
126 d->m_currentFilter.clear();
127 d->m_needsSetup = true;
128}
129
130/*!
131 Returns the map of all the available namespaces as keys
132 together with their associated components as values.
133*/
134QMap<QString, QString> QHelpFilterEngine::namespaceToComponent() const
135{
136 if (!d->setup())
137 return {};
138 return d->m_collectionHandler->namespaceToComponent();
139}
140
141/*!
142 Returns the map of all the available namespaces as keys
143 together with their associated versions as values.
144*/
145QMap<QString, QVersionNumber> QHelpFilterEngine::namespaceToVersion() const
146{
147 if (!d->setup())
148 return {};
149 return d->m_collectionHandler->namespaceToVersion();
150}
151
152/*!
153 Returns the list of all filter names defined inside the filter engine.
154*/
155QStringList QHelpFilterEngine::filters() const
156{
157 if (!d->setup())
158 return {};
159 return d->m_collectionHandler->filters();
160}
161
162/*!
163 Returns the list of all available components defined in all
164 registered documentation files.
165*/
166QStringList QHelpFilterEngine::availableComponents() const
167{
168 if (!d->setup())
169 return {};
170 return d->m_collectionHandler->availableComponents();
171}
172
173/*!
174 \since 5.15
175
176 Returns the list of all available versions defined in all
177 registered documentation files.
178*/
179QList<QVersionNumber> QHelpFilterEngine::availableVersions() const
180{
181 if (!d->setup())
182 return {};
183 return d->m_collectionHandler->availableVersions();
184}
185
186/*!
187 Returns the filter details associated with \a filterName.
188*/
189QHelpFilterData QHelpFilterEngine::filterData(const QString &filterName) const
190{
191 if (!d->setup())
192 return {};
193 return d->m_collectionHandler->filterData(filterName);
194}
195
196/*!
197 Changes the existing filter details of the filter identified by
198 \a filterName to \a filterData. If the filter does not exist, a
199 new filter is created.
200
201 Returns \c true if setting the filter succeeded, otherwise returns \c false.
202*/
203bool QHelpFilterEngine::setFilterData(const QString &filterName, const QHelpFilterData &filterData)
204{
205 if (!d->setup())
206 return false;
207 return d->m_collectionHandler->setFilterData(filterName, filterData);
208}
209
210/*!
211 Removes the filter identified by \a filterName.
212
213 Returns \c true if removing the filter succeeded, otherwise returns
214 \c false.
215*/
216bool QHelpFilterEngine::removeFilter(const QString &filterName)
217{
218 if (!d->setup())
219 return false;
220 return d->m_collectionHandler->removeFilter(filterName);
221}
222
223/*!
224 Returns the name of the currently active filter.
225*/
226QString QHelpFilterEngine::activeFilter() const
227{
228 if (!d->setup())
229 return {};
230 return d->m_currentFilter;
231}
232
233/*!
234 Changes the currently active filter to \a filterName.
235
236 Returns \c true if changing the filter succeeded, otherwise
237 returns \c false.
238*/
239bool QHelpFilterEngine::setActiveFilter(const QString &filterName)
240{
241 if (!d->setup())
242 return false;
243
244 if (filterName == d->m_currentFilter)
245 return true;
246
247 if (!filterName.isEmpty() && !d->m_collectionHandler->filters().contains(str: filterName))
248 return false;
249
250 d->m_currentFilter = filterName;
251 d->m_collectionHandler->setCustomValue(key: QLatin1StringView(ActiveFilter), value: d->m_currentFilter);
252 emit filterActivated(newFilter: d->m_currentFilter);
253 return true;
254}
255
256/*!
257 Returns the list of all registered documentation namespaces that match
258 the filter identified by \a filterName.
259*/
260QStringList QHelpFilterEngine::namespacesForFilter(const QString &filterName) const
261{
262 if (!d->setup())
263 return {};
264 return d->m_collectionHandler->namespacesForFilter(filterName);
265}
266
267/*!
268 \since 5.15
269
270 Returns a sorted list of available indices.
271 The returned list contents depend on the active filter, and therefore only
272 the indices registered for the active filter will be returned.
273*/
274QStringList QHelpFilterEngine::indices() const
275{
276 return indices(filterName: activeFilter());
277}
278
279/*!
280 \since 5.15
281
282 Returns a sorted list of available indices, filtered by \a filterName.
283 The returned list contents depend on the passed filter, and therefore only
284 the indices registered for this filter will be returned.
285 If you want to get all available indices unfiltered,
286 pass empty string as \a filterName.
287*/
288QStringList QHelpFilterEngine::indices(const QString &filterName) const
289{
290 if (!d->setup())
291 return {};
292 return d->m_collectionHandler->indicesForFilter(filterName);
293}
294
295QT_END_NAMESPACE
296

source code of qttools/src/assistant/help/qhelpfilterengine.cpp