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

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