1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000 Torben Weis <weis@kde.org>
4 SPDX-FileCopyrightText: 2006-2020 David Faure <faure@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KAPPLICATIONTRADER_H
10#define KAPPLICATIONTRADER_H
11
12#include <functional>
13#include <kservice.h>
14
15/*!
16 * \namespace KApplicationTrader
17 * \inmodule KService
18 *
19 * \brief The application trader is a convenient way to find installed applications
20 * based on specific criteria (association with a MIME type, name contains Foo, etc.).
21 *
22 * Example: say that you want to get the list of all applications that can handle PNG images.
23 * The code would look like:
24 * \code
25 * KService::List lst = KApplicationTrader::queryByMimeType("image/png");
26 * \endcode
27 *
28 * If you want to get the preferred application for image/png you would use:
29 * \code
30 * KService::Ptr service = KApplicationTrader::preferredService("image/png");
31 * \endcode
32 *
33 * \sa KService
34 */
35namespace KApplicationTrader
36{
37/*!
38 * \typealias KApplicationTrader::FilterFunc
39 * Filter function, used for filtering results of query and queryByMimeType.
40 */
41using FilterFunc = std::function<bool(const KService::Ptr &)>;
42
43/*!
44 * This method returns a list of services (applications) that match a given filter.
45 *
46 * \a filterFunc a callback function that returns \c true if the application
47 * should be selected and \c false if it should be skipped.
48 *
49 * Returns a list of services that satisfy the query
50 * \since 5.68
51 */
52KSERVICE_EXPORT KService::List query(FilterFunc filterFunc);
53
54/*!
55 * This method returns a list of services (applications) which are associated with a given MIME type.
56 *
57 * \a mimeType a MIME type like 'text/plain' or 'text/html'
58 *
59 * \a filterFunc a callback function that returns \c true if the application
60 * should be selected and \c false if it should be skipped. Do not return
61 * true for all services, this would return the complete list of all
62 * installed applications (slow).
63 *
64 * Returns a list of services that satisfy the query, sorted by preference
65 * (preferred service first)
66 * \since 5.68
67 */
68KSERVICE_EXPORT KService::List queryByMimeType(const QString &mimeType, FilterFunc filterFunc = {});
69
70/*!
71 * Returns the preferred service for \a mimeType
72 *
73 * This a convenience method for queryByMimeType(mimeType).at(0), with a check for empty.
74 *
75 * \a mimeType the MIME type (see query())
76 *
77 * Returns the preferred service, or \c nullptr if no service is available
78 *
79 * \since 5.68
80 */
81KSERVICE_EXPORT KService::Ptr preferredService(const QString &mimeType);
82
83/*!
84 * Changes the preferred service for \a mimeType to \a service
85 *
86 * You may need to rebuild KSyCoca for the change to be reflected
87 *
88 * \a mimeType the MIME type
89 *
90 * \a service the service to set as the preferred one
91 *
92 * \since 5.101
93 */
94KSERVICE_EXPORT void setPreferredService(const QString &mimeType, const KService::Ptr service);
95
96/*!
97 * Returns true if \a pattern matches a subsequence of the string \a text.
98 * For instance the pattern "libremath" matches the text "LibreOffice Math", assuming
99 * \a cs is Qt::CaseInsensitive.
100 *
101 * This can be useful from your filter function, e.g. with \a text being service->name().
102 * \since 5.68
103 */
104KSERVICE_EXPORT bool isSubsequence(const QString &pattern, const QString &text, Qt::CaseSensitivity cs = Qt::CaseSensitive);
105}
106
107#endif
108

source code of kservice/src/services/kapplicationtrader.h