Differential D25698 Diff 74335 src/services/kapplicationtrader.h

Changeset View

Standalone View

View Options

src/services/kapplicationtrader.h

  • This file was added.
1​/* This file is part of the KDE libraries
2​ Copyright (C) 2000 Torben Weis <weis@kde.org>
3​ Copyright (C) 2006-2020 David Faure <faure@kde.org>
4​
5​ This library is free software; you can redistribute it and/or
6​ modify it under the terms of the GNU Library General Public
7​ License as published by the Free Software Foundation; either
8​ version 2 of the License, or (at your option) any later version.
9​
10​ This library is distributed in the hope that it will be useful,
11​ but WITHOUT ANY WARRANTY; without even the implied warranty of
12​ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13​ Library General Public License for more details.
14​
15​ You should have received a copy of the GNU Library General Public License
16​ along with this library; see the file COPYING.LIB. If not, write to
17​ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18​ Boston, MA 02110-1301, USA.
19​*/
20​
21​#ifndef KAPPLICATIONTRADER_H
22​#define KAPPLICATIONTRADER_H
23​
24​#include <kservice.h>
25​#include <functional>
26​
27​/**
28​ * @class KApplicationTrader kapplicationtrader.h <KApplicationTrader>
29​ *
30​ * The application trader is a convenient way to find installed applications
31​ * based on specific criteria (association with a mimetype, name contains Foo, etc.)
32​ *
33​ * Example: say that you want to get the list of all applications that can handle PNG images.
34​ * The code would look like:
dhaumannUnsubmitted
Done

Typo: you want to _get_...

dhaumann: Typo: you want to _get_...
35​ * \code
36​ * KService::List lst = KApplicationTrader::queryByMimeType("image/png");
37​ * \endcode
38​ *
39​ * If you want to get the preferred application for image/png you would use:
40​ * @code
41​ * KService::Ptr service = KApplicationTrader::preferredService("image/png");
42​ * @endcode
43​ *
44​ * @see KService
45​ */
46​namespace KApplicationTrader
47​{
48​ /**
49​ * Filter function, used for filtering results of query and queryByMimeType.
dhaumannUnsubmitted
Done

Please document this typedef so that FilterFunc will be clickable in the generated API documentation.

dhaumann: Please document this typedef so that FilterFunc will be clickable in the generated API…
50​ */
51​ using FilterFunc = std::function<bool(const KService::Ptr &)>;
52​
53​ /**
54​ * This method returns a list of services (applications) which are associated with a given mimetype.
55​ *
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.
aacidUnsubmitted
Done

why is it slow? Looking at the code we have to go trhough all apps anyway since what we do is erase if returning false, so wouldn't returning true actually be faster?

aacid: why is it slow? Looking at the code we have to go trhough all apps anyway since what we do is…
dfaureAuthorUnsubmitted
Done

Excellent point.

This was a mental copy/paste from allServices() which basically tells people, instead of iterating over the full list of services, better try to use an existing "database index" like "query by servicetype" or "query by mimetype" or "query by name". Here's there's no choice (well, this is a query by servicetype "Application", at least it doesn't look at plugins).

I'll remove this.

dfaure: Excellent point. This was a mental copy/paste from allServices() which basically tells people…
58​ *
aacidUnsubmitted
Done

all this "constraint" definition needs updating

aacid: all this "constraint" definition needs updating
59​ * @return A list of services that satisfy the query
60​ * @since 5.67
61​ */
62​ KSERVICE_EXPORT KService::List query(FilterFunc filterFunc);
63​
64​ /**
65​ * This method returns a list of services (applications) which are associated with a given mimetype.
66​ *
67​ * @param mimeType A mime type like 'text/plain' or 'text/html'.
68​ * @param filter a callback function that returns @c true if the application
69​ * should be selected and @c false if it should be skipped. Do not return
70​ * true for all services, this would return the complete list of all
71​ * installed applications (slow).
72​ *
73​ * @return A list of services that satisfy the query, sorted by preference
74​ * (preferred service first)
75​ * @since 5.67
76​ */
77​ KSERVICE_EXPORT KService::List queryByMimeType(const QString &mimeType,
78​ FilterFunc filterFunc = {});
79​
80​ /**
81​ * Returns the preferred service for @p mimeType
dhaumannUnsubmitted
Not Done

method without training e.

dhaumann: method without training e.
dfaureAuthorUnsubmitted
Not Done

LOL, I'm trying but sometimes the French in me takes over :)

dfaure: LOL, I'm trying but sometimes the French in me takes over :)
82​ *
83​ * This a convenience method for queryByMimeType(mimeType).at(0), with a check for empty.
84​ *
85​ * @param mimeType the mime type (see query())
86​ * @return the preferred service, or @c nullptr if no service is available
87​ * @since 5.67
88​ */
89​ KSERVICE_EXPORT KService::Ptr preferredService(const QString &mimeType);
90​
91​
dhaumannUnsubmitted
Not Done

Maybe mention when this function is useful? For me it looks like a private helper function. Why is it public?

dhaumann: Maybe mention when this function is useful? For me it looks like a private helper function. Why…
dfaureAuthorUnsubmitted
Not Done

It's not a private helper, it's one of the things you might want to call from your lambda filter function. See the unittest (which is a bit of a "porting guide" from the old traders).

Added a line of docu about that.

dfaure: It's not a private helper, it's one of the things you might want to call from your lambda…
92​ /**
93​ * Returns true if @p pattern matches a subsequence of the string @p text.
94​ * For instance the pattern "libremath" matches the text "LibreOffice Math", assuming
95​ * @p cs is Qt::CaseInsensitive.
96​ *
97​ * This can be useful from your filter function, e.g. with @p text being service->name().
98​ * @since 5.67
99​ */
100​ KSERVICE_EXPORT bool isSubsequence(const QString& pattern, const QString& text, Qt::CaseSensitivity cs = Qt::CaseSensitive);
101​
102​}
103​
104​#endif