unity.scopes.QueryBase

Abstract server-side base interface for a query that is executed inside a scope. More...

#include <unity/scopes/QueryBase.h>

Inheritance diagram for unity::scopes::QueryBase: src="https://assets.ubuntu.com/v1/62ab339d-classunity_1_1scopes_1_1_query_base__inherit__graph.png" border="0" alt="Inheritance graph"/>

Public Member Functions

virtual void cancelled ()=0
 Called by the scopes runtime when the query originator cancels a query. More...
 
bool valid () const
 Check whether this query is still valid. More...
 
unity::scopes::VariantMap settings () const
 Returns a dictionary with the scope's current settings. More...
 

Detailed Description

Abstract server-side base interface for a query that is executed inside a scope.

See also
SearchQueryBase, PreviewQueryBase, ActivationQueryBase

Member Function Documentation

virtual void unity::scopes::QueryBase::cancelled ( )
pure virtual

Called by the scopes runtime when the query originator cancels a query.

Your implementation of this method should ensure that the scope stops processing the current query as soon as possible. Any calls to a push() method once a query is cancelled are ignored, so continuing to push after cancellation only wastes CPU cycles. (push() returns false once a query is cancelled or exceeds its cardinality limit.)

Implemented in unity::scopes::qt::QPreviewQueryBaseAPI, unity::scopes::qt::QSearchQueryBaseAPI, and unity::scopes::ActivationQueryBase.

VariantMap unity::scopes::QueryBase::settings ( ) const

Returns a dictionary with the scope's current settings.

Instead of storing the return value, it is preferable to call settings() each time your implementation requires a settings value. This ensures that, if a user changes settings while the scope is running, the new settings take effect with the next query, preview, and so on.

Note
The settings are available only after this QueryBase is instantiated; do not call this method from the constructor!
Returns
The scope's current settings.
bool unity::scopes::QueryBase::valid ( ) const

Check whether this query is still valid.

valid() returns false if this query is finished or was cancelled earlier. Note that it is possible that the runtime may call SearchQueryBase::run(), ActivationQueryBase::activate(), or PreviewQueryBase::run() after cancelled() was called. Your implementation of these methods should check whether the query is still valid and, if not, do nothing.

This method is provided mainly for convenience: it can be used in your s run() or activate() implementation to avoid doing a lot of work setting up a query that was cancelled earlier. Note that, because cancellation can happen at any time during query execution, your implementation should always test the return value of push(). If push() returns false, the query was either cancelled or exceeded its cardinality limit. Either way, there is no point in continuing to push more results because, once push() returns false, the scopes runtime discards all subsequent results for the query.