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");
    VariantArray arr;
    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());
    ...
}