2
* Copyright (C) 2015 Canonical Ltd
4
* This program is free software: you can redistribute it and/or modify
5
* it under the terms of the GNU Lesser General Public License version 3 as
6
* published by the Free Software Foundation.
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 Lesser General Public License for more details.
13
* You should have received a copy of the GNU Lesser General Public License
14
* along with this program. If not, see <http://www.gnu.org/licenses/>.
16
* Authored by: Xavi Garcia <xavi.garcia.mena@canonical.com>
21
#include <unity/util/DefinesPtrs.h>
23
#include <unity/scopes/ScopeProxyFwd.h>
24
#include <unity/scopes/Variant.h>
26
#include <unity/scopes/qt/QScopeVariant.h>
28
#include <QtCore/QString>
29
#include <QtCore/QVariant>
43
class QCategorisedResult;
48
class QPreviewQueryBaseImpl;
52
\brief The attributes of a result returned by a Scope.
54
The Result API provides convenience methods for some typical attributes (title,
55
art), but scopes are free to add and use any custom attributes with `operator[]`.
56
The only required attribute is 'uri' and it must not be empty before
57
calling Reply::push().
63
UNITY_DEFINES_PTRS(QResult);
67
/**@name Copy and assignment
68
Copy and assignment (move and non-move versions) have the usual value semantics.
71
QResult(QResult const& other);
74
QResult& operator=(QResult const& other);
75
QResult& operator=(QResult&&);
84
\brief Stores a Result inside this Result instance.
86
This method is meant to be used by aggregator scopes which want to modify results they receive, but want
87
to keep a copy of the original result so that they can be correctly handled by the original scopes
88
who created them when it comes to activation or previews.
89
Scopes middleware will automatically pass the correct inner stored result to the activation or preview request
91
of a scope which created it.
92
\param other The original result to store within this result.
93
\param intercept_activation True if this scope should receive activation and preview requests.
95
void store(QResult const& other, bool intercept_activation = false);
98
\brief Check if this Result instance has a stored result.
99
\return True if there is a stored result
101
bool has_stored_result() const;
104
\brief Get a stored result.
105
\return stored result
106
\throws unity::InvalidArgumentException if no result was stored in this Result instance.
108
QResult retrieve() const;
111
\brief Set the "uri" attribute of this result.
113
void set_uri(QString const& uri);
116
\brief Set the "title" attribute of this result.
118
Equivalent to calling `result["title"] = title;`
120
void set_title(QString const& title);
122
\brief Set the "art" attribute of this result.
124
Equivalent to calling `result["art"] = image;`
126
void set_art(QString const& image);
129
\brief Set the "dnd_uri" attribute of this result.
131
Equivalent to calling `result["dnd_uri"] = dnd_uri;`
133
void set_dnd_uri(QString const& dnd_uri);
136
\brief Indicates to the receiver that this scope should intercept activation requests for this result.
138
By default, a scope receives preview requests for the results it creates, but does not receive activation
139
requests (they are handled directly by the shell).
140
Intercepting activation implies intercepting preview requests as well; this is important for scopes that
141
forward results from other scopes and call set_intercept_activation() on these scopes.
142
A scope that sets intercept activation flag for a result should re-implement ScopeBase::activate()
143
and provide an implementation of ActivationQueryBase that handles the actual activation.
144
If not called, the result will be activated directly by the Unity shell whithout involving the scope,
145
assuming an appropriate URI schema handler is present on the system.
147
void set_intercept_activation();
150
\brief Check if this result should be activated directly by the shell
151
because the scope doesn't handle activation of this result.
152
\return True if this result needs to be activated directly.
154
bool direct_activation() const;
157
\brief Get the proxy of a scope that handles activation and preview of this result.
159
The proxy is available only when receiving this result from a scope, otherwise
160
this method throws LogicException. Activation requests should be sent to a scope
161
returned by this method only if direct_activation() is false.
162
\return The scope proxy.
164
ScopeProxy target_scope_proxy() const;
167
\brief Returns reference of a Result attribute.
169
This method can be used to read or initialize both standard ("uri", "title", "art", "dnd_uri")
170
and custom metadata attributes. Referencing a non-existing attribute automatically creates
171
it with a default value of Variant::Type::Null.
172
\param key The name of the attribute.
173
\return A reference to the attribute.
174
\throws unity::Invalidargument if no attribute with the given name exists.
176
QScopeVariant& operator[](QString const& key);
179
\brief Returns a const reference to a Result attribute.
181
This method can be used for read-only access to both standard ("uri", "title", "art", "dnd_uri")
182
and custom metadata attributes. Referencing a non-existing attribute throws unity::InvalidArgumentException.
183
\param key The name of the attribute.
184
\return A const reference to the attribute.
185
\throws unity::Invalidargument if no attribute with the given name exists.
187
QVariant const& operator[](QString const& key) const;
190
\brief Get the "uri" property of this Result.
192
This method returns an empty string if this attribute is not of type Variant::Type::String (e.g. it was set with
194
\return The value of "uri" or the empty string.
196
QString uri() const noexcept;
199
\brief Get the "title" property of this Result.
201
This method returns an empty string if this attribute is not of type Variant::Type::String (e.g. it was set with
203
\return The value of "title" or the empty string.
205
QString title() const noexcept;
208
\brief Get the "art" property of this Result.
210
This method returns an empty string if this attribute is not of type Variant::Type::String (e.g. it was set with
212
\return The value of "art" or the empty string.
214
QString art() const noexcept;
217
\brief Get the "dnd_uri" property of this Result.
219
This method returns an empty string if this attribute is not of type Variant::Type::String type (e.g. it was set
221
\return The value of "dnd_uri" or the empty string.
223
QString dnd_uri() const noexcept;
226
\brief Check if this Result has an attribute.
227
\param key The attribute name.
228
\return True if the attribute is set.
230
bool contains(QString const& key) const;
233
\brief Get the value of an attribute.
235
\param key The attribute name.
236
\return The attribute value.
237
\throws unity::InvalidArgumentException if given attribute hasn't been set.
239
QVariant const& value(QString const& key) const;
242
\brief Returns a dictionary of all attributes of this Result instance.
243
\return All base attributes and custom attributes set with add_metadata().
245
VariantMap serialize() const;
249
explicit QResult(const VariantMap& variant_map);
250
explicit QResult(internal::QResultImpl* impl);
251
explicit QResult(unity::scopes::Result const& result);
254
std::unique_ptr<internal::QResultImpl> p;
256
friend class internal::QResultImpl;
257
friend class QCategorisedResult;
258
friend class internal::QPreviewQueryBaseImpl;
259
friend class QPreviewQueryBaseAPI;
265
} // namespace scopes
added
removed
include/unity/scopes/qt/QResult.h
