← Back to branch summary

~mhr3/unity-scopes-api/merge-trunk

« back to all changes in this revision

Viewing changes to include/unity/scopes/ScopeBase.h

  • Committer: Michi Henning
  • Date: 2014-07-29 09:33:53 UTC
  • mfrom: (425 devel)
  • mto: This revision was merged to the branch mainline in revision 427.
  • Revision ID: michi.henning@canonical.com-20140729093353-ndu77ndikxqtaqsc
Merged devel and fixed conflicts.

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/unity/scopes/ScopeBase.h
19
19
#ifndef UNITY_SCOPES_SCOPEBASE_H
20
20
#define UNITY_SCOPES_SCOPEBASE_H
21
21
 
22
 
#include <unity/scopes/SearchQueryBase.h>
23
 
#include <unity/scopes/PreviewQueryBase.h>
24
 
#include <unity/scopes/RegistryProxyFwd.h>
25
 
#include <unity/scopes/ActivationQueryBase.h>
26
 
#include <unity/scopes/Version.h>
27
 
#include <unity/scopes/Result.h>
 
22
#include <unity/scopes/AbstractScopeBase.h>
28
23
#include <unity/scopes/ActionMetadata.h>
29
24
#include <unity/scopes/SearchMetadata.h>
 
25
#include <unity/scopes/Version.h>
30
26
 
31
27
/**
32
28
\brief Expands to the identifier of the scope create function. @hideinitializer
68
64
 
69
65
namespace internal
70
66
{
 
67
 
71
68
class ScopeBaseImpl;
72
 
class ScopeLoader;
73
69
class RuntimeImpl;
 
70
 
74
71
}
75
72
 
76
73
/**
90
87
    MyScope();
91
88
    virtual ~MyScope();
92
89
 
93
 
    virtual void start();   // Optional
94
 
    virtual void stop();    // Optional
95
 
    virtual void run();     // Optional
 
90
    virtual void start(std::string const& scope_id);   // Optional
 
91
    virtual void stop();                               // Optional
 
92
    virtual void run();                                // Optional
96
93
};
97
94
~~~
98
95
 
134
131
call to stop() in a timely manner.
135
132
*/
136
133
 
137
 
class ScopeBase
 
134
class ScopeBase : public AbstractScopeBase
138
135
{
139
136
public:
140
137
    /// @cond
150
147
    The call to start() is made by the same thread that calls the create function.
151
148
 
152
149
    \param scope_id The name of the scope as defined by the scope's configuration file.
153
 
 
154
 
    \param registry A proxy to the scope registry. This parameter is provided for aggregating
155
 
    scopes that need to retrieve proxies to their child scopes.
156
150
    */
157
 
    virtual void start(std::string const& scope_id, RegistryProxy const& registry);
 
151
    virtual void start(std::string const& scope_id);
158
152
 
159
153
    /**
160
154
    \brief Called by the scopes run time when the scope should shut down.
184
178
    /**
185
179
    \brief Called by the scopes run time when a scope needs to instantiate a query.
186
180
 
187
 
    This method must return an instance that is derived from QueryBase. The implementation
 
181
    This method must return an instance that is derived from `QueryBase`. The implementation
188
182
    of this method must return in a timely manner, that is, it should perform only minimal
189
183
    initialization that is guaranteed to complete quickly. The call to search() is made
190
184
    by an arbitrary thread.
197
191
    /**
198
192
    \brief Called by the scopes run time when a scope needs to respond to a result activation request.
199
193
 
200
 
    This method must return an instance that is derived from ActivationQueryBase. The implementation
 
194
    This method must return an instance that is derived from `ActivationQueryBase`. The implementation
201
195
    of this method must return in a timely manner, that is, it should perform only minimal
202
196
    initialization that is guaranteed to complete quickly. The call to activate() is made
203
197
    by an arbitrary thread.
206
200
    \param result The result that should be activated.
207
201
    \param metadata additional data sent by the client.
208
202
    \return The activation instance.
209
 
     */
 
203
    */
210
204
    virtual ActivationQueryBase::UPtr activate(Result const& result, ActionMetadata const& metadata);
211
205
 
212
206
    /**
213
207
    \brief Invoked when a scope is requested to handle a preview action.
214
208
 
215
 
    This method must return an instance that is derived from ActivationQueryBase. The implementation
 
209
    This method must return an instance that is derived from `ActivationQueryBase`. The implementation
216
210
    of this method must return in a timely manner, that is, it should perform only minimal
217
211
    initialization that is guaranteed to complete quickly. The call to activate() is made
218
212
    by an arbitrary thread.
223
217
    \param widget_id The identifier of the 'actions' widget of the activated action.
224
218
    \param action_id The identifier of the action that was activated.
225
219
    \return The activation instance.
226
 
     */
227
 
    virtual ActivationQueryBase::UPtr perform_action(Result const& result, ActionMetadata const& metadata, std::string const& widget_id, std::string const& action_id);
 
220
    */
 
221
    virtual ActivationQueryBase::UPtr perform_action(Result const& result,
 
222
                                                     ActionMetadata const& metadata,
 
223
                                                     std::string const& widget_id,
 
224
                                                     std::string const& action_id);
228
225
 
229
226
    /**
230
227
    \brief Invoked when a scope is requested to create a preview for a particular result.
231
228
 
232
 
    This method must return an instance that is derived from PreviewQueryBase. The implementation
 
229
    This method must return an instance that is derived from `PreviewQueryBase`. The implementation
233
230
    of this method must return in a timely manner, that is, it should perform only minimal
234
231
    initialization that is guaranteed to complete quickly. The call to activate() is made
235
232
    by an arbitrary thread.
236
233
    \param result The result that should be previewed.
237
234
    \param metadata Additional data sent by the client.
238
235
    \return The preview instance.
239
 
     */
 
236
    */
240
237
    virtual PreviewQueryBase::UPtr preview(Result const& result, ActionMetadata const& metadata) = 0;
241
238
 
242
239
    /**
251
248
    call this method from the constructor!
252
249
 
253
250
    \return The scope's configuration directory.
254
 
    */
255
 
    std::string scope_directory() const;
 
251
    \throws LogicException if called from the constructor of this instance.
 
252
    */
 
253
    virtual std::string scope_directory() const final;
 
254
 
 
255
    /**
 
256
    \brief Returns a directory that is (exclusively) writable for the scope.
 
257
 
 
258
    This directory allows scopes to store persistent information, such
 
259
    as cached content or similar.
 
260
 
 
261
    \note The cache directory is available only after this ScopeBase is instantiated; do not
 
262
    call this method from the constructor!
 
263
 
 
264
    \return The root directory of the filesystem sub-tree that is writable for the scope.
 
265
    \throws LogicException if called from the constructor of this instance.
 
266
    */
 
267
    virtual std::string cache_directory() const final;
 
268
 
 
269
    /**
 
270
    \brief Returns the proxy to the registry.
 
271
 
 
272
    \note The registr proxy is available only after this ScopeBase is instantiated; do not
 
273
    call this method from the constructor!
 
274
 
 
275
    \return The proxy to the registry.
 
276
    \throws LogicException if called from the constructor of this instance.
 
277
    */
 
278
    virtual unity::scopes::RegistryProxy registry() const final;
256
279
 
257
280
    /**
258
281
    \brief Returns a dictionary with the scope's current settings.
266
289
    call this method from the constructor!
267
290
 
268
291
    \return The scope's current settings.
 
292
    \throws LogicException if called from the constructor of this instance.
269
293
    */
270
 
    VariantMap settings() const;
 
294
    virtual VariantMap settings() const final;
271
295
 
272
296
protected:
273
297
    /// @cond
275
299
private:
276
300
    std::unique_ptr<internal::ScopeBaseImpl> p;
277
301
 
278
 
    friend class internal::ScopeLoader;
 
302
    friend class internal::RuntimeImpl;
279
303
    friend class internal::ScopeObject;
280
 
    friend class internal::RuntimeImpl;
281
304
    /// @endcond
282
305
};
283
306
 
287
310
 
288
311
/**
289
312
\brief The function called by the scopes run time to initialize the scope.
290
 
It must return a pointer to an instance derived from ScopeBase. The returned
 
313
It must return a pointer to an instance derived from `ScopeBase`. The returned
291
314
instance need not be heap-allocated, but must remain in scope until the
292
315
destroy function is called by the scopes run time.
293
316
 
294
317
If this function throws an exception, the destroy function will _not_ be called. If this function returns NULL,
295
318
the destroy function _will_ be called with NULL as its argument.
296
319
 
 
320
\note The only purpose of the create function is to return the an instance.
 
321
Do not do anything in the implementation that might block, and do
 
322
not attempt to call any methods on `ScopeBase` from the constructor.
 
323
 
297
324
\return The pointer to the ScopeBase instance.
298
325
*/
299
326
extern "C" unity::scopes::ScopeBase* UNITY_SCOPE_CREATE_FUNCTION();