Widget catalog

The Apertis UI framework provides several UI components that can be leveraged to build UIs for apps. Here is an overview of available widgets.

Lightwood

The main component responsible for providing the UI building blocks is Lightwood. Lightwood provides API interfaces and base implementation for various widgets that can be reused to build UI components for variants such as Mildenhall.

Lightwood uses Clutter as its base, so widgets are Clutter actors and the Clutter APIs can be used with them.

Interfaces

Expandable

An interface to be implemented by widgets that provide two modes of operation, namely expanded and not expanded. It is mainly used inside Lightwood for the FixedRoller, which supports expanding items when they are selected.

Abstract widgets

These are base classes which can be leveraged by variants for their concrete implementations. They cannot be instantiated directly, only through a subclass. Some concrete subclasses are provided by Lightwood, some are left completely to the variants to define.

Container

A simple container widget. Doesn't do anything itself, only used as a bin to contain other widgets. This can be thought of as the base for other widgets.

Button

A button supporting several gestures. Presses and releases are joined by long presses and also swipes. There is also support for variants to configure tooltips. Those are not provided on the base widget.

PopupBase

A base class for variants to use when implementing their popups. Contains a property to indicate an audio file to be played when the popup appears.

ProgressBase

Provides a media playback state bar. Visualization for media duration, current time, buffering, as well as action buttons for play/pause and seeking.

MapBase

Provides a way of showing and interacting with maps. It is able to render maps from OpenStreetMap and supports zooming and markers.

Roller

A list of items resembling an infinite cylinder. It can be rotated, supports kinetic behaviour and visual effects such as motion blur. Two concrete classes are provided, with two different modes of operation: FixedRoller and VariableRoller.

Widgets

MultilineEntry

Text entry with several lines. Displays and allows editing text with several lines. Supports programmatic editing of the text, basic formatting of the displayed text, as well as scrolling the lines of text.

TextBox

Higher level text entry widget. Supports basic formatting of displayed text, password entry, with entered characters converted to an asterisk. Although it lacks the programmatic text editing capabilities of MultilineEntry, it does allow editing several lines of text if its multiline property is turned on.

VariableRoller

A specialization of the Roller which supports items with variable size. By allowing each item to have a different size, more visual flexibility is possible. Images of different sizes can be shown more naturally, for instance. However, this makes the roller less efficient and can degrade performance when there are many items.

FixedRoller

The roller can efficiently host many more items when their sizes are fixed, since it doesn't need to ask all of its children about their sizes for layout. This leads to some rigidity in the flow of the items, though. Images with different aspect ratios will not look as natural, for instance. For that, consider using VariableRoller.

Expander

A container that can be clicked, tapped or dragged to show or hide its child.

Flipper

An animated container for two actors. It places the actors on each other's back and can switch between showing one or the other by performing a flip animation ­— rotating both actors on their axes so that the one that had its front toward the screen puts its back towards the screen and vice versa.

The way the rotation is done and the animation properties such as duration and easing can be customized.

Data

Model

A subclass of ThornburyModel that notifies when it is waiting for data. In use cases where the model fetches data asynchronously from the disk or from remote sources, it may happen that a request for more data does not have an immediate response, the view needs to be notified. This is an abstract class, so it cannot be instantiated directly. A concrete subclass is necessary.

Effects

CylinderDeformEffect

A ClutterEffect that can be applied to any ClutterActor. When applied to a widget, the rendered content will be deformed so that it looks like a cylinder. It is used on the Roller give it its cylindrical look.

BlurEffect

A ClutterEffect that can be applied to any ClutterActor. When applied to a widget, the rendered content will be blurred. It is used on the Roller to provide a motion blur effect when scrolling fast.

DeformPageTurn

A ClutterEffect that can be applied to any ClutterActor. When applied to a widget, the rendered content will be deformed like a page that is being turned.

GlowShader

A ClutterEffect that can be applied to any ClutterActor. When applied to a widget, the rendered content will have a glow around it. The Roller uses this to highlight selected items, for instance.

Mildenhall

The Lightwood library is a base upon which variants are built. The reference variant implementation is Mildenhall.

Widgets

BottomBar

A horizontal bar with 3 buttons and a text label.

ButtonDrawer

A button which is also a drawer. It is built on LightwoodButton, and thus supports all its features. The button can optionally have multiple states other than normal and pressed, and swiping right and left can change those states.

RadioButton

A button which can be marked to select among exclusive alternatives. Several radio buttons are placed on a single group and selecting one of them deselects the others. It is built on LightwoodButton.

ToggleButton

A button which has two states. Clicking or tapping switches between those states.

DrawerBase

A button which opens a drop-down or pull-up menu with more buttons. Beside the buttons a tooltip is shown for a time describing it.

LbsBottomBar

A horizontal bar with 3 labels arranged such that one is to the left, one at the center, one to the right.

LoadingBar

A progress bar that can be used to show the status of tasks.

MapWidget

Shows a map and allows interaction with it. Zooming and markers are supported.

MetaInfoFooter

A horizontal bar providing an icon, a label and optional 5-star rating. It can also display a decorative top bar.

MetaInfoHeader

A horizontal bar providing an icon, and a label. It can also display a decorative bottom bar.

Overlay

An overlay that can place an image on top of something else.

MediaOverlay

An overlay that can be placed on top of video. It includes a play/pause button and text.

ProgressBar

A media playback state widget, built on LightwoodProgressBase. Visualization for media duration, current time, buffering, as well as action buttons for play/pause and seeking.

RatingBottomBar

A horizontal bar with a 5-start rating or text label at the top-left and 2 text labels, one at the bottom left, one to the right.

RollerContainer

The generic implementaton for the LightwoodRoller. It is actually not a subclass, but rather a container that can host either a FixedRoller or a VariableRoller.

CabinetRoller

Allows navigation of hierarchical content, such as folders. It shows up to two Rollers side by side. Selecting an item will show the contents of that item on the right-side roller.

InfoRoller

A mix of a drawer and either a FixedRoller or VariableRoller from Lightwood. The drawer can be opened to show the roller.

PullupRoller

A widget that mixes a drawer, a MetaInfoFooter from Mildehall and either a FixedRoller or a VariableRoller from Lightwood. The drawer can be opened to show the roller. It differs from InfoRoller in that it uses a MetaInfoFooter to provide the base of the drawer.

scroller

A viewport that allows scrolling over content that overflows its size. Supports finger scrolling with kinetic behaviour.

SelectionPopup

A popup dialog that provides the user with a message and several buttons that can be used to choose how to respond to the message.

Speller

A virtual keyboard. It works by using its own text entry widgets rather than by sending key events immediately to the application. There are signals to be notified when the user has pressed a key and when text is committed.

TextBox

A text entry widget implementing LightwoodTextBox. Supports basic formatting of displayed text, password entry, with entered characters converted to an asterisk. Allow editing several lines of text if its multiline property is turned on.

WebViewWidget

A widget providing a web engine. It can be used to render local and remote web pages.

WidgetContainer

A container that can be used to lay out other widgets. It supports animating widgets when moving them inside its viewport.

PopupInfo

Implementation of LightwoodPopupBase. It is able to show text and 3 buttons.

Roller item widgets

The Roller widgets can be populated by several types of items. These are some of the items provided by Mildenhall. The developer decides which type of item to use and the Roller will create them as needed based on the model.

DetailRoller

A Roller item for showing several icons and several labels of text.

IconLabelIconItem

A Roller item to display a label and two icons, one at each side of the label. It also supports showing progress information using a MildenhallLoadingBar.

IconLabelRadioButtonItem

A Roller item to display an icon, a label and a radio button.

IconTextVariable

A Roller item for showing an image, a label and optionally a 5-star rating.

ListItem

A Roller item with an icon and four labels.

LbsListRollerItem

A Roller item with 3 labels placed such that one is at the top, two at the left and right sides of the bottom, with an icon in the middle.

MessageRollerItem

A widget capable of showing an email message, fit for using on Roller widgets.

SampleDetailItem

A Roller item showing a short text and a long text.

SampleThumbnailItem

Shows images as Roller items.

SampleVariableItem

Item showing icon and label with variable height, for use with VariableRoller.

SBrowserDetail

Shows a video or audio inside a Roller.

SingleItem

Roller item with 3 text labels and optional footer

SortRoller

A Roller item with data that can be sorted by its parent either alphabetically or numerically.

Speller entry widgets

The virtual keyboard provided by Mildenhall supports several types of entries where text can be typed. The entry type can be specified as a property of the Speller object.

SpellerDefaultEntry

The default entry type used by the Speller. It provides autocomplete and history features.

SpellerFourToggleEntry

An entry that includes a text entry and four MildenhallToggleButton instances.

SpellerMultiLineEntry

Text entry where several lines of text can be edited at once.

SpellerMultipleEntry

Several entries that can be edited on the same virtual keyboard.

ThumbnailItem

Item for the Roller hosting a MediaOverlay widget.

VideoListRollerItem

Item with 3 text labels and an icon for the Roller.

VideoThumbRoller

Item to show an image and optionally a video player on a Roller.