Differential D10078 Diff 31871 src/dbusrunner/abstractrunner.h

Changeset View

Standalone View

View Options

src/dbusrunner/abstractrunner.h

  • This file was added.
1​/*
2​ * Copyright 2018 Friedrich W. H. Kossebau <kossebau@kde.org>
3​ *
4​ * This program is free software; you can redistribute it and/or modify
5​ * it under the terms of the GNU Library General Public License version 2 as
6​ * published by the Free Software Foundation
7​ *
8​ * This program is distributed in the hope that it will be useful,
9​ * but WITHOUT ANY WARRANTY; without even the implied warranty of
10​ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11​ * GNU General Public License for more details
12​ *
13​ * You should have received a copy of the GNU Library General Public
14​ * License along with this program; if not, write to the
15​ * Free Software Foundation, Inc.,
16​ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17​ */
18​
19​#pragma once
20​
21​#include "kdbusrunner_export.h"
22​
23​#include "querymatch.h"
24​#include "action.h"
25​
26​#include <QObject>
27​#include <QSharedPointer>
28​
29​namespace KDBusRunner
30​{
31​ class Context;
32​ class ContextPrivate;
33​/**
34​ * @class AbstractRunner abstractrunner.h <KDBusRunner/AbstractRunner>
35​ *
36​ * @short An abstract base class for KRunner D-Bus plugins
37​ *
38​ * Example:
39​ * @code
40​#include <KDBusRunner/AbstractRunner>
41​
42​class MyRunner : public KDBusRunner::AbstractRunner
43​{
44​ Q_OBJECT
45​
46​public:
47​ MyRunner();
48​
49​public:
50​ KDBusRunner::Actions actions() override;
51​ void startMatching(QSharedPointer<KDBusRunner::Context> context) override;
52​ void run(const QString &id, const QString &actionId) override;
53​};
54​ * @endcode
55​ *
56​ * The implementation of the D-Bus runner class:
57​ * @code
58​MyRunner::MyRunner()
59​ : KDBusRunner::AbstractRunner(QStringLiteral("/myrunner"), QStringLiteral("org.example.myrunner"))
60​{
61​}
62​
63​void MyRunner::startMatching(QSharedPointer<KDBusRunner::Context> context)
64​{
65​ if (context->searchQuery().contains(QLatin1String("my"))) {
66​ context->addMatches({{
67​ QStringLiteral("matchid"),
68​ QStringLiteral("My Match"),
69​ QStringLiteral("fooicon"),
70​ KDBusRunner::QueryMatch::ExactMatch,
71​ 0.8,
72​ {}
73​ }});
74​ }
75​}
76​
77​KDBusRunner::Actions MyRunner::actions()
78​{
79​ return {{
80​ QStringLiteral("action1"),
81​ QStringLiteral("Open container"),
82​ QStringLiteral("document-browser")
83​ }};
84​}
85​
86​void MyRunner::run(const QString &id, const QString &actionId)
87​{
88​ // do actionId with id
89​}
90​ * @endcode
91​ *
92​ * Now the class just needs to be instantiated and activated by enabling it:
93​ * @code
94​void activateRunner()
95​{
96​ auto r = new MyRunner(parent);
97​ r->setEnabled();
98​}
99​ * @endcode
100​ *
101​ * The desktop file would get the matching entries:
102​ * @code
103​X-Plasma-API=DBus
104​X-Plasma-DBusRunner-Service=org.example.myrunner
105​X-Plasma-DBusRunner-Path=/myrunner
106​ * @endcode
107​ */
108​class KDBUSRUNNER_EXPORT AbstractRunner : public QObject
109​{
110​ Q_OBJECT
111​
112​public:
113​ /**
114​ * @param dBusObjectPath D-Bus object path to register the runner object at
115​ * @param dBusServiceName D-Bus service name to register, if empty none will be registered
116​ * @param parent optional QObject parent taking ownership
117​ */
118​ explicit AbstractRunner(const QString& dBusObjectPath, const QString& dBusServiceName = QString(), QObject* parent = nullptr);
119​ ~AbstractRunner() override;
120​
121​public: // API to implement
122​ /**
123​ * Returns a list of descriptions for additional actions possible
124​ * on the matched object.
125​ *
126​ * Default implementation returns an empty list.
127​ *
128​ * @return list of action descriptions
129​ */
130​ virtual Actions actions(); // TODO: const? async ever needed?
131​
132​ /**
133​ * Starts the matching.
134​ * For sync processing context can be filled within this method.
135​ * For async processing, a reference to the request can be kept and completed whenever.
136​ * Note the calling client may time out, so it is advised to only respond to the latest request.
137​ */
138​ virtual void startMatching(QSharedPointer<Context> context) = 0;
139​
140​ /**
141​ * Called whenever an exact or possible match associated with this
142​ * runner is triggered.
143​ *
144​ * @param id The context in which the match is triggered, i.e. for which
145​ * the match was created.
146​ * @param actionId The actual match to run/execute.
147​ */
148​ virtual void run(const QString &id, const QString &actionId) = 0;
149​
150​ bool isEnabled() const;
151​
152​ void virtual_hook(int id, void *data);
153​
154​ void setEnabled(bool enabled = true);
155​
156​
157​Q_SIGNALS:
158​ void matchingCancelled();
159​
160​private:
161​ const QScopedPointer<class AbstractRunnerPrivate> d;
162​};
davidedmundsonUnsubmitted
Done

please add a virtual hook for future expansion

davidedmundson: please add a virtual hook for future expansion
163​
164​class KDBUSRUNNER_EXPORT Context
165​{
166​public:
167​ Context(ContextPrivate *d);
168​ ~Context();
169​ QString searchQuery() const;
170​ void addMatches(const QueryMatches& matches);
171​ void cancel();
172​ void submit();
173​private:
174​ const QScopedPointer<class ContextPrivate> d;
175​ friend class AbstractRunner;
176​};
177​
178​
179​}