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 ()
 
PreviewWidgetoperator= (PreviewWidget const &other)
 
PreviewWidgetoperator= (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:

void MyPreview::run(PreviewReplyProxy const& reply)
{
PreviewWidget w1("img", "image");
// directly specify source URI for the image widget
w1.add_attribute_value("source", Variant("http://www.example.org/graphics.png"));
PreviewWidget w2("hdr", "header");
// the result associated with this preview already had a title specified, so we'll just map it to the preview widget
w2.add_attribute_mapping("title", "title");
// description is not present in the result, but we'll push it later
w2.add_attribute_mapping("summary", "description");
widgets.push_back(w1);
widgets.push_back(w2);
reply->push(widgets);
// do a costly database lookup for the description
std::string description = fetch_description(result().uri());
reply->push("description", 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
idThe unique widget identifier.
widget_typeThe 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:

PreviewWidget img(R"({"id": "img", "type": "image", "source": "http://imageuri",
"fallback": "file:///tmp/image.png"})");

For cases where attribute mappings are to be used instead of direct values, they need to be enclosed in the "components" dictionary, e.g.

PreviewWidget img(R"({"id": "img", "type": "image", "fallback": "file:///tmp/image.png",
"components": { "source": "screenshot-url" } })");

(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
definitionThe 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
keyThe name of the attribute.
valueThe 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::LogicExceptionif 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.