org.gnome.Shell.SearchProvider2: Shell Reference Manual

org.gnome.Shell.SearchProvider2

org.gnome.Shell.SearchProvider2 — Search provider interface

Methods

GetInitialResultSet   (IN  as     terms,
                       OUT as     results);
GetSubsearchResultSet (IN  as     previous_results,
                       IN  as     terms,
                       OUT as     results);
GetResultMetas        (IN  as     identifiers,
                       OUT aa{sv} metas);
ActivateResult        (IN  s      identifier,
                       IN  as     terms,
                       IN  u      timestamp);
LaunchSearch          (IN  as     terms,
                       IN  u      timestamp);

Description

The interface used for integrating into GNOME Shell's search interface (version 2).

Method Details

The GetInitialResultSet() method

GetInitialResultSet (IN  as terms,
                     OUT as results);

Called when the user first begins a search.

`IN as terms`:	Array of search terms, which the provider should treat as logical AND.
`OUT as results`:	An array of result identifier strings representing items which match the given search terms. Identifiers must be unique within the provider's domain, but other than that may be chosen freely by the provider.

The GetSubsearchResultSet() method

GetSubsearchResultSet (IN  as previous_results,
                       IN  as terms,
                       OUT as results);

Called when a search is performed which is a "subsearch" of the previous search, e.g. the method may return less results, but not more or different results.

This allows search providers to only search through the previous result set, rather than possibly performing a full re-query.

`IN as previous_results`:	Array of results previously returned by GetInitialResultSet().
`IN as terms`:	Array of updated search terms, which the provider should treat as logical AND.
`OUT as results`:	An array of result identifier strings representing items which match the given search terms. Identifiers must be unique within the provider's domain, but other than that may be chosen freely by the provider.

The GetResultMetas() method

GetResultMetas (IN  as     identifiers,
                OUT aa{sv} metas);

Return an array of meta data used to display each given result

IN as identifiers:

An array of result identifiers as returned by GetInitialResultSet() or GetSubsearchResultSet()

OUT aa{sv} metas:

A dictionary describing the given search result, containing a human-readable 'name' (string), along with the result identifier this meta is for, 'id' (string). Optionally, 'icon' (a serialized GIcon as obtained by g_icon_serialize) can be specified if the result can be better served with a thumbnail of the content (such as with images). 'gicon' (a serialized GIcon as obtained by g_icon_to_string) or 'icon-data' (raw image data as (iiibiiay) - width, height, rowstride, has-alpha, bits per sample, channels, data) are deprecated values that can also be used for that purpose. A 'description' field (string) may also be specified if more context would help the user find the desired result.

The ActivateResult() method

ActivateResult (IN  s  identifier,
                IN  as terms,
                IN  u  timestamp);

Called when the users chooses a given result. The result should be displayed in the application associated with the corresponding provider. The provided search terms can be used to allow launching a full search in the application.

`IN s identifier`:	A result identifier as returned by GetInitialResultSet() or GetSubsearchResultSet()
`IN as terms`:	Array of search terms, which the provider should treat as logical AND.
`IN u timestamp`:	A timestamp of the user interaction that triggered this call

The LaunchSearch() method

LaunchSearch (IN  as terms,
              IN  u  timestamp);

Asks the search provider to launch a full search in the application for the provided terms.

`IN as terms`:	Array of search terms, which the provider should treat as logical AND.
`IN u timestamp`:	A timestamp of the user interaction that triggered this call