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 states 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...

virtual bool	push (Filters const &filters)=0
	Sends all filter definitions to the source of a 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 states to the source of a query.

Deprecated:

Sending filter state back to the UI is deprecated and will be removed from future releases. Please use the push(Filters const&) method instead.

Returns: True if the filters were accepted, false otherwise.

virtual bool unity::scopes::SearchReply::push ( Filters const & filters )

pure virtual

Sends all filter definitions 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

Parameters

id	The identifier of the category
title	The title of the category
icon	The icon of the category
renderer_template	The renderer template to be used for results in this category

Returns: The category instance

Exceptions

unity::scopes::InvalidArgumentException if 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

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::InvalidArgumentException if 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

Parameters

id	The identifier of the category
title	The title of the category
icon	The icon of the category
query	Query to perform when expanding this category
renderer_template	The renderer template to be used for results in this category

Returns: The category instance

Exceptions

unity::scopes::InvalidArgumentException if category with that id has already been registered.

virtual void unity::scopes::SearchReply::register_departments ( Department::SCPtr const & parent )

pure virtual

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

create a Department node for current department and attach to it a list of its subdepartments (unless current department is a leaf department) using unity::scopes::Department::set_subdepartments() method. For every subdepartment on the list set "has_subdepartments" flag if applicable.
provide an alternate label for current department with unity::scopes::Department::set_alternate_label().
create a Department node for parent of current department (if applicable - not when in root department), and attach current Department node to it with unity::scopes::Department::set_subdepartments() method.
register the parent department with unity::scopes::SearchReply::register_departments().

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

parent The parent department of current department, or current one if visiting root department.

Exceptions

unity::LogicException if departments are invalid (nullptr passed, current department not present in the parent's tree, duplicated department ids present in the tree).

unity.scopes.SearchReply

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation