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