Ubuntu Phone documentation
unity.scopes.PreviewWidget
A widget for a preview. More...
Public Member Functions | |
| PreviewWidget (std::string const &id, std::string const &widget_type) | |
| Create an empty widget definition with a specific id and type. More... | |
| PreviewWidget (std::string const &definition) | |
| Create a widget from a JSON definition. More... | |
| void | add_attribute_value (std::string const &key, Variant const &value) |
| Adds an attribute definition and its value. More... | |
| void | add_attribute_mapping (std::string const &key, std::string const &field_name) |
| Adds an attribute definition using a component mapping. More... | |
| void | add_widget (PreviewWidget const &widget) |
| Adds a widget into expandable widget. More... | |
| std::string | id () const |
| Get the identifier of this widget. More... | |
| std::string | widget_type () const |
| Get type name of this widget. More... | |
| std::map< std::string, std::string > | attribute_mappings () const |
| Get the components of this widget. More... | |
| VariantMap | attribute_values () const |
| Get the attributes of this widget. More... | |
| PreviewWidgetList | widgets () const |
| Get widgets of 'expandable' widget. More... | |
| std::string | data () const |
| Get a JSON representation of this widget. More... | |
| Copy and assignment | |
Copy and assignment operators (move and non-move versions) have the usual value semantics. | |
| PreviewWidget (PreviewWidget const &other) | |
| PreviewWidget (PreviewWidget &&other) | |
| virtual | ~PreviewWidget () |
| PreviewWidget & | operator= (PreviewWidget const &other) |
| PreviewWidget & | operator= (PreviewWidget &&other) |
Detailed Description
A widget for a preview.
This class describes an individual widget used when constructing a preview for a result item. Note that the data that applies to particular widget types is likely to change with different major versions of Unity; therefore, attributes are of type Variant, that is, loosely typed.
When Unity requests a preview for a particular result, the scope is expected to construct the preview by instantiating a PreviewWidget. Each widget has a free-form id, a type, and a number of attributes whose names and types depend on the specific widget type (see Preview Widgets).
The attribute values can either be filled in directly before pushing the widget to Unity (using add_attribute_value()), or they can be mapped from a result field in a similar fashion to the components mapping when specifying a CategoryRenderer (see add_attribute_mapping()). When using add_attribute_mapping(), the corresponding attribute need not be present in the result; instead, its value can be pushed later using the PreviewReply::push() method, which accepts the name of the field and its value as a Variant.
Preview widget can also be created entirely from a JSON string. See the documentation of unity::scopes::PreviewWidget::PreviewWidget(std::string const&) constructor for details.
Here is an example that creates a preview and illustrates three ways to associate a preview widget attribute with its value:
<span class="keywordtype">void</span> MyPreview::run(<a class="code" href="unity.scopes.md#a7b46ef0e880da4c75314fe60bdd55754">PreviewReplyProxy</a> <span class="keyword">const</span>& reply) { <a class="code" href="#ace84578d55583c7c21f82d53ff6f0ed9">PreviewWidget</a> w1(<span class="stringliteral">"img"</span>, <span class="stringliteral">"image"</span>); <span class="comment">// directly specify source URI for the image widget</span> w1.add_attribute_value(<span class="stringliteral">"source"</span>, Variant(<span class="stringliteral">"http://www.example.org/graphics.png"</span>)); <a class="code" href="#ace84578d55583c7c21f82d53ff6f0ed9">PreviewWidget</a> w2(<span class="stringliteral">"hdr"</span>, <span class="stringliteral">"header"</span>); <span class="comment">// the result associated with this preview already had a title specified, so we'll just map it to the preview widget</span> w2.add_attribute_mapping(<span class="stringliteral">"title"</span>, <span class="stringliteral">"title"</span>); <span class="comment">// description is not present in the result, but we'll push it later</span> w2.add_attribute_mapping(<span class="stringliteral">"summary"</span>, <span class="stringliteral">"description"</span>); <a class="code" href="unity.scopes.md#aed3b7b1daf2e49d0a820ef931caa792d">PreviewWidgetList</a> <a class="code" href="#a879e64d5ee205b4db8cb6ab9b66d18ee">widgets</a>; widgets.push_back(w1); widgets.push_back(w2); reply->push(widgets); <span class="comment">// do a costly database lookup for the description</span> std::string description = fetch_description(result().uri()); reply->push(<span class="stringliteral">"description"</span>, Variant(description)); }
Constructor & Destructor Documentation
| unity::scopes::PreviewWidget::PreviewWidget | ( | std::string const & | id, |
| std::string const & | widget_type | ||
| ) |
Create an empty widget definition with a specific id and type.
- Parameters
-
id The unique widget identifier. widget_type The type of the widget.
| unity::scopes::PreviewWidget::PreviewWidget | ( | std::string const & | definition | ) |
Create a widget from a JSON definition.
The JSON definition must be a dictionary that includes widget "id" and all the values of attributes required by desired widget type. For example, a definition of image widget may look as follows:
<a class="code" href="#ace84578d55583c7c21f82d53ff6f0ed9">PreviewWidget</a> img(R<span class="stringliteral">"({"id": "img", "type": "image", "source": "http://imageuri",</span> <span class="stringliteral"> "fallback": "file:///tmp/image.png"})");</span>
For cases where attribute mappings are to be used instead of direct values, they need to be enclosed in the "components" dictionary, e.g.
<a class="code" href="#ace84578d55583c7c21f82d53ff6f0ed9">PreviewWidget</a> img(R<span class="stringliteral">"({"id": "img", "type": "image", "fallback": "file:///tmp/image.png",</span> <span class="stringliteral"> "components": { "source": "screenshot-url" } })");</span>
(this example assumes "screenshot-url" value is either available in the result object that's being previewed, or it will be pushed with unity::scopes::PreviewReply::push() method)
- Note
- It is recommended to create widgets via unity::scopes::PreviewWidget(std::string const&, std::string const&) constructor and unity::scopes::PreviewWidget::add_attribute_value() / unity::scopes::PreviewWidget::add_attribute_mapping() methods, rather than via JSON definition.
- Parameters
-
definition The JSON definition.
Member Function Documentation
| void unity::scopes::PreviewWidget::add_attribute_mapping | ( | std::string const & | key, |
| std::string const & | field_name | ||
| ) |
Adds an attribute definition using a component mapping.
If an attribute value is either not known, or the value is already present in a result field, this method creates a mapping between the attribute name and given the field name.
If an attribute value is not known, the scope is expected to push the attribute value using unity::scopes::PreviewReply::push(); otherwise, the value is automatically mapped from the result.
| void unity::scopes::PreviewWidget::add_attribute_value | ( | std::string const & | key, |
| Variant const & | value | ||
| ) |
Adds an attribute definition and its value.
- Parameters
-
key The name of the attribute. value The value of the attribute.
| void unity::scopes::PreviewWidget::add_widget | ( | PreviewWidget const & | widget | ) |
Adds a widget into expandable widget.
Adds a widget into this widget, which needs to be of 'expandable' type. This method throws if adding a widget into any other widget type. Also, adding an 'expandable' widget into another 'expandable' is not allowed.
- Exceptions
-
unity::LogicException if type of this widget is other than 'expandable', or when adding 'expandable' to 'expandable'.
| std::map<std::string, std::string> unity::scopes::PreviewWidget::attribute_mappings | ( | ) | const |
Get the components of this widget.
The returned map is a dictionary of (key, field name) pairs, as defined by calls to add_attribute_mapping().
- Returns
- The components map.
| VariantMap unity::scopes::PreviewWidget::attribute_values | ( | ) | const |
Get the attributes of this widget.
The returned map is a dictionary of (key, value) pairs, as defined by calls to add_attribute_value().
- Returns
- The attribute map.
| std::string unity::scopes::PreviewWidget::data | ( | ) | const |
Get a JSON representation of this widget.
- Returns
- The JSON string.
| std::string unity::scopes::PreviewWidget::id | ( | ) | const |
Get the identifier of this widget.
- Returns
- The widget identifier.
| std::string unity::scopes::PreviewWidget::widget_type | ( | ) | const |
Get type name of this widget.
- Returns
- The widget type.
| PreviewWidgetList unity::scopes::PreviewWidget::widgets | ( | ) | const |
Get widgets of 'expandable' widget.
Returns the list of widget attached to this widget, which must be of 'expandable' type. This list is always empty for other widget types.