Unity Scopes API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
unity::scopes::PreviewWidget Class Reference

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

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.

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

The documentation for this class was generated from the following file: