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
.
The results of the search are