1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999, 2000 Carsten Pfeiffer <pfeiffer@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KCOMPLETIONMATCHES_H
9#define KCOMPLETIONMATCHES_H
10
11#include <kcompletion_export.h>
12#include <ksortablelist.h>
13
14#include <QStringList>
15#include <memory>
16
17class KCompletionMatchesWrapper;
18class KCompletionMatchesPrivate;
19
20/*!
21 * \typedef KCompletionMatchesList
22 * \relates KCompletionMatches
23 */
24typedef KSortableList<QString> KCompletionMatchesList;
25
26/*!
27 * \class KCompletionMatches
28 * \inmodule KCompletion
29 *
30 * \brief List for keeping matches returned from KCompletion.
31 *
32 * This structure is returned by KCompletion::allWeightedMatches().
33 * It also keeps the weight of the matches, allowing
34 * you to modify some matches or merge them with matches
35 * from another call to allWeightedMatches(), and sort the matches
36 * after that in order to have the matches ordered correctly.
37 *
38 * Example (a simplified example of what Konqueror's completion does):
39 * \code
40 * KCompletionMatches matches = completion->allWeightedMatches(location);
41 * if(!location.startsWith("www."))
42 * matches += completion->allWeightedmatches("www." + location");
43 * matches.removeDuplicates();
44 * QStringList list = matches.list();
45 * \endcode
46 */
47class KCOMPLETION_EXPORT KCompletionMatches : public KCompletionMatchesList
48{
49public:
50 Q_DECLARE_PRIVATE(KCompletionMatches)
51 /*!
52 * Default constructor.
53 *
54 * \a sort if false, the matches won't be sorted before the conversion,
55 * use only if you're sure the sorting is not needed
56 */
57 KCompletionMatches(bool sort);
58
59 KCompletionMatches(const KCompletionMatches &);
60
61 KCompletionMatches &operator=(const KCompletionMatches &);
62
63 /*!
64 * \internal
65 */
66 KCompletionMatches(const KCompletionMatchesWrapper &matches);
67
68 ~KCompletionMatches();
69 /*!
70 * Removes duplicate matches. Needed only when you merged several matches
71 * results and there's a possibility of duplicates.
72 */
73 void removeDuplicates();
74 /*!
75 * Returns the matches as a QStringList.
76 *
77 * \a sort if false, the matches won't be sorted before the conversion,
78 * use only if you're sure the sorting is not needed
79 *
80 * Returns the list of matches
81 */
82 QStringList list(bool sort = true) const;
83 /*!
84 * If sorting() returns \c false, the matches aren't sorted by their weight,
85 * even if \c true is passed to list().
86 *
87 * \c true if the matches won't be sorted
88 */
89 bool sorting() const;
90
91private:
92 std::unique_ptr<KCompletionMatchesPrivate> const d_ptr;
93};
94
95#endif // KCOMPLETIONMATCHES_H
96

source code of kcompletion/src/kcompletionmatches.h