Differential D25698 Diff 70787 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-2019 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​class KApplicationTraderPrivate;
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::self()->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::self()->preferredService("image/png");
42​ * @endcode
43​ *
44​ * @see KService
45​ * @since 5.66
46​ */
47​class KSERVICE_EXPORT KApplicationTrader
48​{
49​public:
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​ /**
52​ * Destructor
53​ */
54​ ~KApplicationTrader();
55​
56​
57​ /**
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​ * This method returns a list of services (applications) which are associated with a given mimetype.
aacidUnsubmitted
Done

all this "constraint" definition needs updating

aacid: all this "constraint" definition needs updating
59​ *
60​ * The constraint parameter is used to limit the possible choices
61​ * returned based on the constraints you give it.
62​ *
63​ * The @p constraint language is rather full. The most common
64​ * keywords are AND, OR, NOT, IN, and EXIST, all used in an
65​ * almost spoken-word form. An example is:
66​ * \code
67​ * 'Email' in Categories and 'km' ~ Name
68​ * \endcode
69​ *
70​ * The keys used in the query (Categories, Name) are all
71​ * fields found in the .desktop files.
72​ *
73​ * @param constraint A constraint to limit the choices returned. Do not pass an empty string,
74​ * this would return the complete list of all installed applications (slow).
75​ *
76​ * @return A list of services that satisfy the query
77​ * @see http://techbase.kde.org/Development/Tutorials/Services/Traders#The_KTrader_Query_Language
78​ */
79​ KService::List query(const QString &constraint) const;
80​
81​ /**
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​ * This method returns a list of services (applications) which are associated with a given mimetype.
83​ *
84​ * See the documentation for query() about the constraint string.
85​ *
86​ * @param mimeType A mime type like 'text/plain' or 'text/html'.
87​ * @param constraint A constraint to limit the choices returned, QString() to
88​ * get all applications that can handle the given @p mimetype
89​ *
90​ * @return A list of services that satisfy the query, sorted by preference
91​ * (preferred service first)
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​ * @see http://techbase.kde.org/Development/Tutorials/Services/Traders#The_KTrader_Query_Language
93​ */
94​ KService::List queryByMimeType(const QString &mimeType,
95​ const QString &constraint = QString()) const;
96​
97​ /**
98​ * Returns the preferred service for @p mimeType
99​ *
100​ * This a convenience methode for queryByMimeType(mimeType).at(0), with a check for empty.
101​ *
102​ * @param mimeType the mime type (see query())
103​ * @return the preferred service, or @c nullptr if no service is available
104​ */
105​ KService::Ptr preferredService(const QString &mimeType);
106​
107​ /**
108​ * This is a static pointer to the KApplicationTrader singleton.
109​ *
110​ * You will need to use this to access the KApplicationTrader functionality since the
111​ * constructor is protected.
112​ *
113​ * @return Static KApplicationTrader instance
114​ */
115​ static KApplicationTrader *self();
116​
117​private:
118​ /**
119​ * @internal
120​ */
121​ KApplicationTrader();
122​
123​private:
124​ KApplicationTraderPrivate * d;
125​
126​ // class-static so that it can access KSycocaEntry::offset()
127​ static void filterMimeTypeOffers(KService::List &list);
128​};
129​
130​#endif