File indexing completed on 2024-12-08 03:41:39

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2000 Torben Weis <weis@kde.org>
0004     SPDX-FileCopyrightText: 2006-2020 David Faure <faure@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KAPPLICATIONTRADER_H
0010 #define KAPPLICATIONTRADER_H
0011 
0012 #include <functional>
0013 #include <kservice.h>
0014 
0015 /**
0016  * @namespace KApplicationTrader
0017  *
0018  * The application trader is a convenient way to find installed applications
0019  * based on specific criteria (association with a MIME type, name contains Foo, etc.)
0020  *
0021  * Example: say that you want to get the list of all applications that can handle PNG images.
0022  * The code would look like:
0023  * \code
0024  * KService::List lst = KApplicationTrader::queryByMimeType("image/png");
0025  * \endcode
0026  *
0027  * If you want to get the preferred application for image/png you would use:
0028  * @code
0029  * KService::Ptr service = KApplicationTrader::preferredService("image/png");
0030  * @endcode
0031  *
0032  * @see KService
0033  */
0034 namespace KApplicationTrader
0035 {
0036 /**
0037  * Filter function, used for filtering results of query and queryByMimeType.
0038  */
0039 using FilterFunc = std::function<bool(const KService::Ptr &)>;
0040 
0041 /**
0042  * This method returns a list of services (applications) that match a given filter.
0043  *
0044  * @param filter a callback function that returns @c true if the application
0045  * should be selected and @c false if it should be skipped.
0046  *
0047  * @return A list of services that satisfy the query
0048  * @since 5.68
0049  */
0050 KSERVICE_EXPORT KService::List query(FilterFunc filterFunc);
0051 
0052 /**
0053  * This method returns a list of services (applications) which are associated with a given MIME type.
0054  *
0055  * @param mimeType a MIME type like 'text/plain' or 'text/html'
0056  * @param filter a callback function that returns @c true if the application
0057  * should be selected and @c false if it should be skipped. Do not return
0058  * true for all services, this would return the complete list of all
0059  * installed applications (slow).
0060  *
0061  * @return A list of services that satisfy the query, sorted by preference
0062  * (preferred service first)
0063  * @since 5.68
0064  */
0065 KSERVICE_EXPORT KService::List queryByMimeType(const QString &mimeType, FilterFunc filterFunc = {});
0066 
0067 /**
0068  * Returns the preferred service for @p mimeType
0069  *
0070  * This a convenience method for queryByMimeType(mimeType).at(0), with a check for empty.
0071  *
0072  * @param mimeType the MIME type (see query())
0073  * @return the preferred service, or @c nullptr if no service is available
0074  * @since 5.68
0075  */
0076 KSERVICE_EXPORT KService::Ptr preferredService(const QString &mimeType);
0077 
0078 /**
0079  * Changes the preferred service for @p mimeType to @p service
0080  *
0081  * You may need to rebuild KSyCoca for the change to be reflected
0082  *
0083  * @param mimeType the MIME type
0084  * @param service the service to set as the preferred one
0085  * @since 5.101
0086  */
0087 KSERVICE_EXPORT void setPreferredService(const QString &mimeType, const KService::Ptr service);
0088 
0089 /**
0090  * Returns true if @p pattern matches a subsequence of the string @p text.
0091  * For instance the pattern "libremath" matches the text "LibreOffice Math", assuming
0092  * @p cs is Qt::CaseInsensitive.
0093  *
0094  * This can be useful from your filter function, e.g. with @p text being service->name().
0095  * @since 5.68
0096  */
0097 KSERVICE_EXPORT bool isSubsequence(const QString &pattern, const QString &text, Qt::CaseSensitivity cs = Qt::CaseSensitive);
0098 }
0099 
0100 #endif