Unity Scopes API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Preview widget types

Recognized preview widget types

The following widget types are recognized by Unity:

  • audio
  • video
  • image
  • gallery
  • header
  • actions
  • progress
  • text
  • rating-input
  • reviews

audio widget

The audio widget displays a list of tracks with play/pause controls.

List of attributes:

  • tracks A composite attribute containing an array of tuples, where each tuple has up to four fields: title (mandatory string), subtitle (optional string), source (mandatory URI), and length (optional integer specifying the track length in seconds)

You can construct composite attributes with unity::scopes::VariantBuilder:

{
PreviewWidget w1("tracks", "audio");
VariantBuilder builder;
builder.add_tuple({
{"title", Variant("Track #1")},
{"source", Variant("file:///tmp/song1.mp3")},
{"length", Variant(194)}
});
builder.add_tuple({
{"title", Variant("Track #2")},
{"source", Variant("file:///tmp/song2.mp3")},
{"length", Variant(207)}
});
w1.add_attribute_value("tracks", builder.end());
...
}

video widget

The video widget displays a still from a video and allows playing the video.

List of attributes:

  • source A URI pointing to the video
  • screenshot A URI pointing to a screenshot of the video (optional)
{
PreviewWidget w1("video1", "video");
w1.add_attribute_value("source", Variant("file:///tmp/video1.mp4"));
...
}

image widget

The image widget displays a single image.

List of attributes:

  • source A URI pointing to the image
  • zoomable A boolean specifying whether the image is zoomable (default: false)
{
PreviewWidget w1("img1", "image");
w1.add_attribute_value("source", Variant("file:///tmp/image.jpg"));
...
}

gallery widget

The gallery widget displays a set of images.

List of attributes:

  • sources An array of image URIs
{
PreviewWidget w1("gal", "gallery");
arr.push_back(Variant("file:///tmp/image1.jpg"));
arr.push_back(Variant("file:///tmp/image2.jpg"));
arr.push_back(Variant("file:///tmp/image3.jpg"));
w1.add_attribute_value("sources", Variant(arr));
...
}

header widget

The header widget displays basic infomation about the result.

List of attributes:

  • title A string specifying the title
  • subtitle A string specifying the subtitle
  • mascot A URI specifying the mascot
  • emblem A URI specifying the emblem
{
PreviewWidget w1("hdr", "header");
w1.add_attribute_value("title", Variant("Result item"));
w1.add_attribute_value("mascot", Variant("file:///tmp/mascot.png"));
...
}

actions widget

The actions widget displays one or more buttons.

List of attributes:

  • actions A composite attribute containing an array of tuples, where each tuple has at least these fields: id (a mandatory string that is passed to unity::scopes::ScopeBase::activate_preview_action()), label (mandatory string), and icon (optional URI).

You can construct composite attributes with unity::scopes::VariantBuilder:

{
PreviewWidget w1("buttons", "actions");
VariantBuilder builder;
builder.add_tuple({
{"id", Variant("open")},
{"label", Variant("Open")}
});
builder.add_tuple({
{"id", Variant("download")},
{"label", Variant("Download")}
});
w1.add_attribute_value("actions", builder.end());
...
}

progress widget

The progress widget displays the progress of an action, such as download progress.

On completion, the scope receives a preview action activation with the id "finished" or "failed", depending on the outcome of the operation.

List of attributes:

  • source A tuple with keys understood by a progress provider
{
PreviewWidget w1("download", "progress");
VariantMap tuple;
tuple["dbus-name"] = "com.canonical.DownloadManager";
tuple["dbus-object"] = "/com/canonical/download/obj1";
w1.add_attribute_value("source", Variant(tuple));
...
}

text widget

A text widget can be used for text of any length (without formatting).

List of attributes:

  • title Optional string
  • text A string containing the text
{
PreviewWidget w1("summary", "text");
w1.add_attribute_value("text", Variant("Lorem Ipsum ..."));
...
}

rating-input widget

The rating-input widget allows users to rate content. It consists of two types of widget: a star-based rating and an input field for the user to enter his/her review. It is possible to hide each widget as well as to require them to be filled in.

When a user presses the "Send" button, the scope receives a preview action activation with the id "rated".

List of attributes:

  • rating-label String for the star-based rating (default: "Rate this")
  • review-label String for the review input (default: "Add a review")
  • submit-label String for the confirmation button (default: "Send")
  • rating-icon-empty URI for an empty rating icon
  • rating-icon-full URI for a full rating icon
  • visible String specifying which of the two widgets are visible ("rating", "review" or default:"both")
  • required String specifying which of the two widgets are required to be filled in ("rating", "review" or default:"both")
{
PreviewWidget w1("rating", "rating-input");
w1.add_attribute_value("visible", Variant("rating"));
w1.add_attribute_value("required", Variant("rating"));
w1.add_attribute_value("rating-icon-empty", Variant("file:///tmp/star-empty.svg"));
w1.add_attribute_value("rating-icon-full", Variant("file:///tmp/star-full.svg"));
...
}

reviews widget

The reviews widget is used to display previously-rated content.

List of attributes:

  • rating-icon-empty URI for an empty rating icon
  • rating-icon-half URI for an half-full rating icon
  • rating-icon-full URI for a full rating icon
  • reviews A composite attribute containing an array of tuples, where each tuple has up to three fields: rating (optional integer specifying the number of stars), author (mandatory string) and review (optional string).

You can construct composite attributes with unity::scopes::VariantBuilder:

{
PreviewWidget w1("summary", "reviews");
w1.add_attribute_value("rating-icon-empty", Variant("file:///tmp/star-empty.svg"));
w1.add_attribute_value("rating-icon-full", Variant("file:///tmp/star-full.svg"));
VariantBuilder builder;
builder.add_tuple({
{"author", Variant("John Doe")},
{"rating", Variant(3)}
});
builder.add_tuple({
{"author", Variant("Mr. Smith")},
{"rating", Variant(5)}
});
w1.add_attribute_value("reviews", builder.end());
...
}