unity.scopes.SearchReply

Allows the results of a search query to be sent to the query source. More...

#include <unity/scopes/SearchReply.h>

Inheritance diagram for unity::scopes::SearchReply: src="https://assets.ubuntu.com/v1/4c39ccb2-classunity_1_1scopes_1_1_search_reply__inherit__graph.png" border="0" alt="Inheritance graph"/>

Public Member Functions

virtual void register_departments (Department::SCPtr const &parent)=0
 Register departments for the current search reply and provide the current department. More...
 
virtual Category::SCPtr register_category (std::string const &id, std::string const &title, std::string const &icon, CategoryRenderer const &renderer_template=CategoryRenderer())=0
 Register new category and send it to the source of the query. More...
 
virtual void register_category (Category::SCPtr category)=0
 Register an existing category instance and send it to the source of the query. More...
 
virtual Category::SCPtr lookup_category (std::string const &id)=0
 Returns a previously registered category. More...
 
virtual bool push (CategorisedResult const &result)=0
 Sends a single result to the source of a query. More...
 
virtual bool push (experimental::Annotation const &annotation)=0
 Push an annotation. More...
 
virtual bool push (Filters const &filters, FilterState const &filter_state)=0
 Sends all filters and their state to the source of a query. More...
 
virtual ~SearchReply ()
 Destroys a Reply. More...
 
virtual Category::SCPtr register_category (std::string const &id, std::string const &title, std::string const &icon, CannedQuery const &query, CategoryRenderer const &renderer_template=CategoryRenderer())=0
 Register new category and send it to the source of the query. More...
 
virtual void push_surfacing_results_from_cache ()=0
 Push the results that were produced by the most recent surfacing query. More...
 
src="https://assets.ubuntu.com/v1/c6607712-closed.png" alt="-"/> Public Member Functions inherited from unity::scopes::Reply
virtual void finished ()=0
 Informs the source of a query that the query results are complete. More...
 
virtual void error (std::exception_ptr ex)=0
 Informs the source of a query that the query was terminated due to an error. More...
 
virtual void info (OperationInfo const &op_info)=0
 Informs the source of a query that additional information regarding the reply is available. More...
 
virtual ~Reply ()
 Destroys a Reply. More...
 
src="https://assets.ubuntu.com/v1/c6607712-closed.png" alt="-"/> Public Member Functions inherited from unity::scopes::Object
virtual std::string endpoint ()=0
 Returns the endpoint this proxy connects to. More...
 
virtual std::string identity ()=0
 Returns the identity of the target object of this proxy. More...
 
virtual std::string target_category ()=0
 Returns the category of the target object of this proxy. More...
 
virtual int64_t timeout ()=0
 Returns the timeout in milliseconds if this proxy is a twoway proxy. More...
 
virtual std::string to_string ()=0
 Converts a proxy into its string representation. More...
 

Detailed Description

Allows the results of a search query to be sent to the query source.

Constructor & Destructor Documentation

virtual unity::scopes::SearchReply::~SearchReply ( )
virtual

Destroys a Reply.

If a Reply goes out of scope without a prior call to finished(), the destructor implicitly calls finished().

Member Function Documentation

virtual Category::SCPtr unity::scopes::SearchReply::lookup_category ( std::string const &  id)
pure virtual

Returns a previously registered category.

Returns
The category instance or nullptr if the category does not exist.
virtual bool unity::scopes::SearchReply::push ( CategorisedResult const &  result)
pure virtual

Sends a single result to the source of a query.

Any calls to push() after finished() was called are ignored.

Returns
The return value is true if the result was accepted, false otherwise. A false return value can be due to finished() having been called earlier, or the client that sent the query having cancelled that query. The return value is false also if the query has a cardinality limit and is reached or exceeded. (The return value is false for the last valid push and subsequent pushes.)
virtual bool unity::scopes::SearchReply::push ( experimental::Annotation const &  annotation)
pure virtual

Push an annotation.

The annotation will be rendered at a next available spot below the category of last pushed result. To render an annotation in the top annotation area, push it before pushing search results.

Note
The Unity shell can ignore some or all annotations, depending on available screen real estate.
virtual bool unity::scopes::SearchReply::push ( Filters const &  filters,
FilterState const &  filter_state 
)
pure virtual

Sends all filters and their state to the source of a query.

Returns
True if the filters were accepted, false otherwise.
virtual void unity::scopes::SearchReply::push_surfacing_results_from_cache ( )
pure virtual

Push the results that were produced by the most recent surfacing query.

The runtime automatically saves the results of the most recent surfacing query. If a scope cannot produce a result for a surfacing query (presumably, due to connectivity problems), calling push_surfacing_results_from_cache() pushes the results that were produced by the most recent successful surfacing query from the cache. If a scope cannot produce surfacing results, it can call this method to "replay" the previous results. In turn, this avoids the user being presented with an empty screen if he/she swipes to the scope while the device does not have connectivity.

This method has an effect only if called for a surfacing query (that is, a query with an empty query string). If called for a non-empty query, it does nothing.

You must call this method before calling finished(), otherwise no cached results will be pushed (push_surfacing_results_from_cache() implicitly calls finished()).

virtual Category::SCPtr unity::scopes::SearchReply::register_category ( std::string const &  id,
std::string const &  title,
std::string const &  icon,
CategoryRenderer const &  renderer_template = CategoryRenderer() 
)
pure virtual

Register new category and send it to the source of the query.

Parameters
idThe identifier of the category
titleThe title of the category
iconThe icon of the category
renderer_templateThe renderer template to be used for results in this category
Returns
The category instance
Exceptions
unity::scopes::InvalidArgumentExceptionif category with that id has already been registered.
Note
The UI uses category IDs for incremental rendering when refreshing search results. For this to work correctly, you need to make sure that you use the same category ID for different queries if the search results apply to the same category as for a previous search.
virtual void unity::scopes::SearchReply::register_category ( Category::SCPtr  category)
pure virtual

Register an existing category instance and send it to the source of the query.

The purpose of this call is to register a category obtained via SearchListenerBase::push(Category::SCPtr const&) when aggregating results and categories from other scope(s).

Exceptions
unity::InvalidArgumentExceptionif category is already registered.
virtual Category::SCPtr unity::scopes::SearchReply::register_category ( std::string const &  id,
std::string const &  title,
std::string const &  icon,
CannedQuery const &  query,
CategoryRenderer const &  renderer_template = CategoryRenderer() 
)
pure virtual

Register new category and send it to the source of the query.

Parameters
idThe identifier of the category
titleThe title of the category
iconThe icon of the category
queryQuery to perform when expanding this category
renderer_templateThe renderer template to be used for results in this category
Returns
The category instance
Exceptions
unity::scopes::InvalidArgumentExceptionif category with that id has already been registered.
virtual void unity::scopes::SearchReply::register_departments ( Department::SCPtr const &  parent)
pure virtual

Register departments for the current search reply and provide the current department.

Departments are optional. If scope supports departments, it is expected to register departments on every search as follows:

For example, assuming the user is visiting a "History" department in "Books", and "History" has sub-departments such as "World War Two" and "Ancient", the code that registers departments for current search in "History" may look like this:

unity::scopes::Department::SPtr books = move(<a class="code" href="unity.scopes.Department.md#a11a3b8e9a3317f963d4bc9f46f79922b">unity::scopes::Department::create</a>(<span class="stringliteral">&quot;books&quot;</span>, query, <span class="stringliteral">&quot;Books&quot;</span>)); <span class="comment">// the parent of &quot;History&quot;</span>
unity::scopes::Department::SPtr history = move(<a class="code" href="unity.scopes.Department.md#a11a3b8e9a3317f963d4bc9f46f79922b">unity::scopes::Department::create</a>(<span class="stringliteral">&quot;history&quot;</span>, query, <span class="stringliteral">&quot;History&quot;</span>));
<a class="code" href="unity.scopes.md#ab8effc4ea05a59f2ddea896833f07231">unity::scopes::DepartmentList</a> history_depts({
move(<a class="code" href="unity.scopes.Department.md#a11a3b8e9a3317f963d4bc9f46f79922b">unity::scopes::Department::create</a>(<span class="stringliteral">&quot;ww2&quot;</span>, query, <span class="stringliteral">&quot;World War Two&quot;</span>)),
move(<a class="code" href="unity.scopes.Department.md#a11a3b8e9a3317f963d4bc9f46f79922b">unity::scopes::Department::create</a>(<span class="stringliteral">&quot;ancient&quot;</span>, query, <span class="stringliteral">&quot;Ancient&quot;</span>))});
history-&gt;set_subdepartments(history_depts);
books-&gt;set_subdepartments({history});
reply-&gt;register_departments(books);

Current department should be the department returned by unity::scopes::CannedQuery::department_id(). Empty department id denotes the root deparment.

Parameters
parentThe parent department of current department, or current one if visiting root department.
Exceptions
unity::LogicExceptionif departments are invalid (nullptr passed, current department not present in the parent's tree, duplicated department ids present in the tree).