From 9a19c4d48acdf70057bfea8e17f954f09b758829 Mon Sep 17 00:00:00 2001
From: Martyn Welch <martyn.welch@collabora.com>
Date: Wed, 21 Apr 2021 17:04:54 +0100
Subject: [PATCH] Remove obsolete documentation
The remaining documents in designs are completely obsolete. Remove these
designs to avoid confusion. The designs folder is part of the legacy
layout so remove it completely now that there's no documents. Fix any
broken links.
Signed-off-by: Martyn Welch <martyn.welch@collabora.com>
---
content/_index.md | 1 -
content/concepts/egress_filtering.md | 7 +-
content/designs/attack_detection.md | 28 -
content/designs/clutter.md | 462 -------
content/designs/list.md | 1210 -----------------
content/designs/software-development-kit.md | 469 -------
.../guides/gitlab-based_packaging_workflow.md | 2 +-
content/guides/howtodevelopondevices.md | 2 +-
8 files changed, 5 insertions(+), 2176 deletions(-)
delete mode 100644 content/designs/attack_detection.md
delete mode 100644 content/designs/clutter.md
delete mode 100644 content/designs/list.md
delete mode 100644 content/designs/software-development-kit.md
diff --git a/content/_index.md b/content/_index.md
index 9f08cc7a6..c83f5fcb5 100644
--- a/content/_index.md
+++ b/content/_index.md
@@ -85,5 +85,4 @@ platform.
* [Source code](https://gitlab.apertis.org)
* [Architectural documentation]( {{< ref "architecture" >}})
* [Development guides]( {{< ref "guides" >}} )
-* [Design documents]( {{< ref "designs" >}} )
* [Concept designs]( {{< ref "concepts" >}} )
diff --git a/content/concepts/egress_filtering.md b/content/concepts/egress_filtering.md
index 71855ff15..e0ec7c0f9 100644
--- a/content/concepts/egress_filtering.md
+++ b/content/concepts/egress_filtering.md
@@ -594,8 +594,8 @@ performed.
### Attack detection
-The platform should have [a heuristic for detecting whether an app has
-been compromised or is malicious]( {{< ref "/attack_detection.md" >}} ).
+The platform should have a heuristic for detecting whether an app has
+been compromised or is malicious.
- The points described as a "probable attack" and "potential attack"
above may be used as input into this heuristic.
@@ -612,8 +612,7 @@ been compromised or is malicious]( {{< ref "/attack_detection.md" >}} ).
- If this heuristic considers the app to be unlikely to be
compromised, the platform should allow it to run unhindered.
- *Non-requirement:* The exact design of this heuristic is outside the
- scope of this document, and will be covered by a separate [Attack
- detection]( {{< ref "/attack_detection.md" >}} ) design.
+ scope of this document, and will be covered by a separate design.
## Recommendations
diff --git a/content/designs/attack_detection.md b/content/designs/attack_detection.md
deleted file mode 100644
index 8ad26cf80..000000000
--- a/content/designs/attack_detection.md
+++ /dev/null
@@ -1,28 +0,0 @@
-+++
-date = "2015-12-18"
-weight = 100
-
-title = "Attack detection"
-
-aliases = [
- "/old-wiki/Attack_detection"
-]
-+++
-
-{{% notice warning %}}
-This concept is an old work in progress.
-{{% /notice %}}
-
-The platform should have a heuristic for detecting whether an app-bundle
-has been compromised or is malicious. This design document, which has
-not yet been written, will collect the various possible inputs to this
-heuristic, and the various actions that might be taken as a result of
-the heuristic deciding that an app-bundle's behaviour is potentially or
-probably malicious.
-
- - [Egress filtering]( {{< ref "/egress_filtering.md" >}} ) is a potential
- input: if an application attempts to carry out Internet connections
- that are not allowed, this is suspicious behaviour.
- - [Egress filtering]( {{< ref "/egress_filtering.md" >}} ) is a potential
- action: if an application is detected to be malicious, its Internet
- connectivity could be limited or cut off.
diff --git a/content/designs/clutter.md b/content/designs/clutter.md
deleted file mode 100644
index 615bd02b7..000000000
--- a/content/designs/clutter.md
+++ /dev/null
@@ -1,462 +0,0 @@
-+++
-title = "Clutter and Multitouch"
-short-description = "Issues with Clutter (obsolete)"
-weight = 100
-toc = true
-aliases = [
- "/old-designs/latest/clutter.html",
- "/old-designs/v2019/clutter.html",
- "/old-designs/v2020/clutter.html",
- "/old-designs/v2021dev3/clutter.html",
-]
-outputs = [ "html", "pdf-in",]
-date = "2016-05-28"
-+++
-
-# Clutter and Multitouch
-
-## Introduction
-
-This document explains Collabora's design about several issues related
-to the main UI toolkit used in Apertis: Clutter.
-
-## Multi-touch
-
-This section describes the support for multi-touch (MT) events and
-gestures in the Apertis middle-ware. It will be explained which
-requirements Collabora will support and the general architecture of MT
-on Linux and X.Org.
-
-When we mention MT in this document, we refer to the ability of
-applications to react to multiple touch event streams at the same time.
-By gestures, we refer to the higher-level abstraction that groups
-individual touch events in a single meaningful event.
-
-At this point of time (Q1 2012), MT and gesture functionality is
-implemented in several consumer products but is only starting to be
-available in frameworks of general availability such as X.Org and HTML.
-As will be explained later, this is reflected in X.Org just being
-released with [MT functionality],
-Clutter not having MT support in a release yet, and the lack of high level gesture support in X.Org-based
-toolkits. In the same vein, MT is not yet standardized in the web. This
-design will discuss the challenges posed by these facts and ways of
-overcoming them.
-
-### The multi-touch stack
-
-For the purposes of this document, the MT stack on X.Org is layered as
-follows:
-
-
-
-#### Compositor
-
-The compositor has to be able to react to gestures that may happen
-anywhere in the display. The X server usually delivers events to the
-window where they happen, so the compositor overrides this behavior by
-telling the X server that it has interest in all events regardless of
-where they happen (specifically, it does so by registering a passive
-grab on the root window).
-
-The compositor will receive all events and decide for each whether it
-should be handled at this level, or let it pass through to the
-application to which the underlying window belongs.
-
-For touch events, this isn't done for individual events but rather for
-touch sequences. A touch sequence is the series of touch events that
-starts when a finger is placed on the screen, and finished when it is
-lifted. Thus, a touch sequence belongs to a single finger, and a gesture
-can be composed by as many touch sequences as fingers are involved.
-
-There is a period of time during which the compositor inspects the touch
-events as they come and decides whether it should handle this particular
-gesture, or if it should be ignored and passed to the application. If
-the compositor decides the later, the events that had been already
-delivered to the compositor will be replayed to the application.
-
-The period of time that the compositor needs to decide whether a gesture
-should be handled by applications should be as small as possible, in
-order to not disrupt the user experience.
-
-An application can tell the X server that it doesn't want to have to
-wait until the compositor has let the touch sequence pass. In that case,
-either the gesture shouldn't cause any visible effects in the UI, or
-should be reverted in case the compositor ends up deciding to handle the
-touch sequence by itself.
-
-#### Applications
-
-Widgets inside applications can react to MT events in a way similar to
-how they react to single-touch events. Additionally, some toolkits
-provide additional functionality that make it easier to react to
-gestures. Widgets can either react to a few predefined gestures (tap,
-panning, pinch, etc.), or they can implement their own gesture
-recognizers by means of the lower level MT events.
-
-#### UI toolkits
-
-As mentioned before, UI toolkits provide API for reacting to MT events
-and usually also functionality related to gestures. Because MT is so new
-to X.Org, UI toolkits based on X.Org don't implement yet everything that
-applications would need regarding MT and gestures, so for now additional
-work needs to happen at the application level.
-
-#### libXi
-
-This library allow toolkits to communicate with the XInput extension in
-the X.Org server. Communication with the X.Org server is asynchronous
-and complex, so having a higher level library simplifies this
-interaction.
-
-#### X.Org server
-
-The X.Org server delivers input events to each application based on the
-coordinates of the event and the placement of the application windows.
-
-#### evdev X.Org input driver
-
-This input driver for X.Org uses udev to discover devices and evdev to
-get input events from the kernel and posts them to the X.Org server.
-
-If it is needed to apply a jitter-reduction filter and it's impossible
-to do so in the kernel device driver, then we recommend to patch the
-evdev X.Org input driver.
-
-#### MTDev
-
-For device drivers that use the legacy MT protocol as opposed to the new
-slots protocol, the X.Org input driver will use libmtdev to translate
-events from the old protocol (type A) to the new one (type B).
-
-> See <http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt>
-
-#### Kernel event driver (evdev)
-
-This kernel module will emit input events in a protocol that the evdev
-X.Org input driver can understand.
-
-#### Kernel device driver
-
-This kernel module is hardware-dependent and will interface with the
-hardware and pass input events to the evdev event driver.
-
-### Requirements
-
-#### Multitouch event handing in Clutter applications
-
-Clutter will have APIs for reacting to multi-touch input events and for
-recognizing gestures.
-
-The Apertis middleware will have the support that Clutter requires to
-provide MT and gestures functionality, as described later in this
-document.
-
-Though it is expected that Clutter will eventually provide support for
-recognizing a few basic gestures such as taps and panning, more advanced
-gestures will have to be implemented outside Clutter. In the Apertis
-case, recognizing additional gestures will have to be done by the
-applications themselves or by the SDK API.
-
-New gestures will be developed using the gesture framework in Clutter,
-regardless of whether the gesture recognition is implemented in the SDK,
-compositor or applications. In other words, new gestures can be
-developed making use of the Clutter API, but the code that implements
-them can belong to applications, compositors or libraries. No
-modifications to Clutter are required to implement new gestures.
-
-#### Full-screen event handing in applications
-
-Applications should be able to handle events anywhere in the screen even
-if their windows don't cover the whole of it. For example, there may be
-windows belonging to the system such as a launcher panel or a status bar
-in the screen, but a gesture that starts in one of the auxiliary windows
-should be handled by the focused application.
-
-#### Multi-touch event handling in Mutter
-
-The compositor based on Mutter will be able to react to multi-touch
-input events and recognize gestures using the same Clutter API as
-applications.
-
-The compositor will be able to register for MT sequences before
-applications get them, so it can claim ownership over them in case a
-system-wide gesture is detected. Even then, applications will be able to
-get all events that happen in their windows though care needs to be
-taken in case the compositor ends up claiming ownership.
-
-#### Multitouch event handing in web applications
-
-Although there are no approved specifications yet on how browsers should
-expose MT events to web content, some browsers have started already to
-provide experimental APIs and some websites are using them. Most notable
-are the Safari browser on iOS and websites that target specifically
-iPhone and iPad devices, though nowadays other WebKit-based browsers
-implement MT events and more websites are starting to use them.
-
-A [spec][w3-touch-spec] is being drafted by the W3C on base on the WebKit
-implementation, but attention must be paid to the fact that because it's
-still a draft, it may change in ways that are incompatible with WebKit's
-implementation and the later may not always be in sync with the spec.
-
-#### Support two separate touchscreens
-
-The Apertis middleware will be able to drive two screens, each with
-multi-touch support.
-
-#### Support out-of-screen touch events
-
-The reactive area of the touchscreen may extend past the display and the
-user will be able to interact with out-of-screen UI elements.
-
-#### Actors with bigger reactive area
-
-So the UI is more tolerant to erratic touch events (caused for example
-by a bumpy road), some actors will be reactive past the boundaries of
-their representation in the screen.
-
-### Approach
-
-#### Multitouch event handing in Clutter applications
-
-MT support in X.Org is very recent, so Collabora will have to update
-several components (mainly belonging to X) in the stack because Precise
-is not going to ship with the versions that are needed.
-
-Clutter 1.8 had support for single-touch gestures. In 1.10, support for
-multi-touch event handling landed, and it is expected that for 1.12
-(August 2012), support for multi-touch gestures will be added. It's also
-planned to have support for rotation and pinch gestures in
-[Clutter 1.12].
-
-#### Full-screen event handing in applications
-
-In order for applications to be able to handle events anywhere in the
-screen even if their windows do not cover the whole of it, applications
-will have to set grabs on the other visible windows, even if they don't
-belong to the application process.
-
-So in the case that the currently-focused application is displayed along
-with a launcher panel and a status bar, the application process should
-set a grab on those windows for the events that it is interested in.
-When another application becomes focused, the first one releases the
-grab and the second takes it.
-
-In order to make sure that the second application takes the grab as soon
-as possible, it should try calling XIGrabTouchBegin repeatedly until it
-stops failing with BadAccess (this will happen once the previously
-focused application has removed its grab).
-
-So the compositor can still handle system-level gestures as explained in
-2.3.3, it will have to set a grab on an invisible window that is the
-parent of each additional window.
-
-This is so complex because this scenario is a bit removed from the
-design of event delivery in X. In Wayland, as the compositor is also the
-display server and has total control over event delivery, it could
-redirect events to application windows instead of to the panels.
-
-#### Multi-touch event handling in Mutter
-
-Current releases of Mutter use XLib for event management, which doesn't
-support multi-touch. To Collabora's knowledge, there aren't as of yet
-any Mutter-based products that make use of system-wide multi-touch
-gestures.
-
-> See <https://wiki.gnome.org/GnomeOS/Design/Whiteboards/Touchscreen#Mutter_problems>
-
-Collabora has [modified][tomeu-multitouch]
-Mutter to allow plugins to register for touch events and to pass them to Clutter so subclasses of
-ClutterGestureAction can be used.
-
-Though applications are able to start receiving MT events even before
-the compositor rejects ownership, Collabora recommends that applications
-don't do that and instead that all efforts are directed towards having
-the compositor recognize gestures as fast as possible.
-
-Otherwise, it will be very hard to avoid glitches in the user experience
-when the compositor decides to handle a gesture and the application
-already started to react to it.
-
-By limiting system-wide gestures to those with 4 or 5 fingers as iOS 5
-does (what Apple calls *multitasking gestures*), the compositor should
-be able to decide whether to take ownership of a MT sequence with a
-minimal delay and without applications having to do anything on their
-side. Gestures with less than 4 fingers will be considered as intended
-for applications and the compositor will decline ownership immediately.
-
-This diagram illustrates how the different components interact when
-handling touch events:
-
-
-
-If there is a window that gets placed on top of the others
-(specifically, the “busy†indicator animation) and it shouldn't get any
-events, it can be marked as such with the XShapeCombineRegion call,
-passing an empty region and the ShapeInput destKind.
-
-> See <http://article.gmane.org/gmane.comp.kde.devel.kwin/19992>
-
-This way, any events that the compositor doesn't intercept will be delivered to the
-currently-focused application.
-
-#### Multi-touch event handing in web applications
-
-Collabora will implement the port specific bits of MT in WebKit-Clutter
-to ensure that it has state-of-the-art WebKit MT support, but won't be
-changing the behavior of the generic WebKit implementation nor working
-on the specification level.
-
-Collabora won't be implementing any high-level gesture support because
-they are far from being specified and its support in browsers is very
-experimental.
-
-#### Support two separate touchscreens
-
-There is support in X.Org for arbitrarily matching input devices to
-screens, though the configuration [isn't straightforward][xorg-transfo-matrix].
-Collabora will test the simultaneous support of 2 touch-screens and produce
-documentation about how to configure X.Org in this regard during the
-development phase of the project.
-
-#### Support out-of-screen touch events
-
-Regarding out-of-screen events support, we propose writing a daemon that
-listens for events from the touchscreen kernel driver and that, based on
-its configuration, translates those to key presses for special key codes
-that correspond to each button.
-
-As the X evdev driver will also get those events, it has to be
-configured to ignore touch events outside the screen area.
-
-In the SDK, a wrapper around Xephyr will be provided that synthesizes
-key events when buttons around the Xephyr screen are pressed, simulating
-the ones in the real hardware.
-
-#### Actors with bigger reactive area
-
-Clutter actors tell the Clutter framework in which area of the screen
-they are sensitive to pointer events. This area usually matches the area
-that the actor uses to display itself, but the actor could choose to
-mark a bigger area as its reactive area.
-
-Though the Clutter maintainer has recommended this approach, he warns
-that the optimization that culls actors based on their paint volumes
-might get in the way in this case.
-
-Collabora will verify that this works and communicate with the upstream
-community in case any problem is discovered.
-
-### Risks
-
-The [DDX] driver provided by the hardware vendor should support
-having a frame-buffer that is bigger than the actual display resolution,
-for the out-of-screen touch events.
-
-## Smooth panning
-
-This section proposes an improvement to the kinetic scrolling
-functionality in Mx so that panning is smooth even when the input
-device's resolution is very low. This is going to affect only to Clutter
-applications that use MxKineticScrollView as the container of scrollable
-areas.
-
-The problem with input devices with low resolution is that as the finger
-moves during panning, the motion events received by the application are
-similarly low-resolution (i.e., occurring infrequently). Given that Mx
-currently updates the position in the scrolled view to match the
-position of the finger, the panning movement appears "jumpy".
-
-### Requirements
-
-When panning, the position in the scrolled view will smoothly
-interpolate to the last finger position, instead of jumping there
-straight away. The visual effect would be that of the scroll position
-lagging slightly behind the finger. The lower the resolution of the
-touch screen, the bigger the lag.
-
-### Approach
-
-Collabora will rewrite the part of the [MxKineticScrollView]
-widget that tracks the finger position when panning, ideally using the function
-[mx_adjustment_interpolate] to animate the movement along the path between
-the current position and the finger position. The time function ([ClutterAlpha])
-used in the interpolation animation will be configurable, as well as the speed at which the scrolling position will
-follow the finger.
-
-### Risks
-
-Upstream could decide to reject this feature when it is proposed for
-inclusion because of the substantial added complexity to a widget
-(MxKineticScrollView) that is already pretty complex. However,
-preliminary discussions with the Mx maintainers show that they are
-interested in gaining this functionality.
-
-Another risk is Intel not funding all the work in Clutter that it has
-committed to. In that case, Collabora may need to do the work.
-
-## Documentation
-
-The following items have been identified for future documentation work
-later in the project:
-
- - Add a section to the Clutter Cookbook about implementing a
- ClutterGestureAction subclass.
-
- - Best practices about MT gestures in user experience, both
- system-wide and application gestures. Compare these guidelines with
- the equivalent ones in iOS and Android.
-
- - Best practices about performance with Clutter and Mx (including how
- to write containers which are responsive independently of the number
- of children and how to drag actors across the screen).
-
- - Best practices about using and writing reusable UI components
- (including Mx widgets), and explicitly these subjects (to be
- specified further at a later stage):
-
- - Panning actors
-
- - Finger moves outside the “active area†of an actor (e.g., moving button of timeline in video very fast)
-
- - Snap forward/backward to final position
-
- - Expand/shrink of groups (sliding)
-
- - Best practices about writing applications in which functionality and
- UI are separate, so derivatives can be written by replacing the UI
- and without having to modify the rest of the application.
-
-### Design notes
-
-The following items have been identified for future investigation and
-design work later in the project and are thus not addressed in this
-design:
-
- - Support two separate touchscreens
-
- - Support out-of-screen touch events
-
- - Implement jitter reduction (there already has an algorithm), taking
- into account that the input driver may be a binary blob
-
- - Implement zoom via pitch gestures in Google Earth without having
- access to its source
- code
-
-[MT functionality]: http://lists.x.org/archives/xorg-announce/2012-March/001846.html
-
-[w3-touch-spec]: http://dvcs.w3.org/hg/webevents/raw-file/tip/touchevents.html
-
-[Clutter 1.12]: http://wiki.clutter-project.org/wiki/ClutterRoadMap#1.12
-
-[tomeu-multitouch]: http://blog.tomeuvizoso.net/2012/09/multi-touch-gestures-in-gnome-shell.html
-
-[xorg-transfo-matrix]: http://www.x.org/wiki/XInputCoordinateTransformationMatrixUsage
-
-[DDX]: http://dri.freedesktop.org/wiki/DDX
-
-[MxKineticScrollView]: http://docs.clutter-project.org/docs/mx/stable/MxKineticScrollView.html
-
-[mx_adjustment_interpolate]: http://docs.clutter-project.org/docs/mx/stable/MxAdjustment.html#mx-adjustment-interpolate
-
-[ClutterAlpha]: http://developer.gnome.org/clutter/stable/ClutterAlpha.html
diff --git a/content/designs/list.md b/content/designs/list.md
deleted file mode 100644
index 0a9c2ffa9..000000000
--- a/content/designs/list.md
+++ /dev/null
@@ -1,1210 +0,0 @@
-+++
-title = "List design"
-short-description = "Architecture and API design for the list widgets in Apertis (unimplemented)"
-weight = 100
-toc = true
-aliases = [
- "/old-designs/latest/list.html",
- "/old-designs/v2019/list.html",
- "/old-designs/v2020/list.html",
- "/old-designs/v2021dev3/list.html",
-]
-outputs = [ "html", "pdf-in",]
-date = "2016-11-24"
-+++
-
-# List design
-
-The goal of this list design document is to establish an appropriate
-architecture and API design for the list widgets in the Apertis
-platform.
-
-Historically, the roller widget has provided a list widget on a cylinder
-with no conceptual beginning or end and is manipulated naturally by the
-user. For non-cylindrical lists there was a separate widget with a
-different API and different usage. The goal is to consolidate list
-operations into a base class and be able to use the same simple API to
-use both cylindrical lists and non-cylindrical lists.
-
-
-
-The above shows an example of the roller widget in use inside the music
-application. There are multiple roller widgets for showing album,
-artist, and song. Although they are manipulated independently, their
-contents are linked.
-
-## Terminology and concepts
-
-### Vehicle
-
-For the purposes of this document, a *vehicle* may be a car, car
-trailer, motorbike, bus, truck tractor, truck trailer, agricultural
-tractor, or agricultural trailer, amongst other things.
-
-### System
-
-The *system* is the infotainment computer in its entirety in place
-inside the vehicle.
-
-### User
-
-The *user* is the person using the system, be it the driver of the
-vehicle or a passenger in the vehicle.
-
-### Widget
-
-A *widget* is a reusable part of the user interface which can be changed
-depending on location and function.
-
-### User interface
-
-The *user interface* is the group of all widgets in place in a certain
-layout to represent a specific use-case.
-
-### Roller
-
-The *roller* is a list widget named after a cylinder which revolves
-around its central horizontal axis. As a result of being a cylinder it
-has no specific start and finish and appears endless.
-
-### Application author
-
-The *application author* is the developer tasked with writing an
-application using the widgets described in this document. They cannot
-modify the variant or the user interface library.
-
-### Variant
-
-A *variant* is a customised version of the system by a particular system
-integrator. Usually variants are personalised with particular colour
-schemes and logos and potentially different widget behaviour.
-
-## Use cases
-
-A variety of use cases for list design are given below.
-
-### Common API
-
-An application author wants to add a list widget to their application.
-At that moment it is not known whether a simple list widget or a roller
-widget will suit the application better. Said application author doesn't
-want to have a high overhead in migrating code from one widget to
-another.
-
-### MVC separation
-
-A group of application authors wants to be able to split the work
-involved in developing their application into teams such that, adhering
-to the interfaces provided, they can develop the different parts of the
-application and easily put them together at the end.
-
-### Data backend agnosticity
-
-An application author wishes to display data stored in a database, and
-does not want to duplicate this data in an intermediary data structure
-in order to do so.
-
-### Kinetic scrolling
-
-The user wants to be able to scroll lists using their finger in such a
-way that the visual response of the list is as expected. Additionally,
-the system integrator wants the user to have visual feedback when the
-start or end of a list is reached by the list bouncing up and back down
-(the *elastic effect*). However, another system integrator wants to
-disable this effect.
-
-The user expectations include the following:
-
- - The user expects the scroll to only occur after a natural threshold
- of movement (as opposed to a tap), for the list to continue
- scrolling after having removed their finger, and for the rate of
- scroll to decrease with time.
-
- - The user expects to be able to stop a scroll by tapping and holding
- the scrolling area.
-
- - The user expects a flick gesture to re-accelerate a scroll without
- any visible stops in the animation.
-
- - The user expects video elements to continue playing during a scroll.
-
- - When there are not enough items to fill the entire height of the
- list area the user expects a scroll to occur but using the elastic
- effect fall back to the centre.
-
- - The user expects a horizontal scroll gesture to not also scroll in
- the vertical direction.
-
-### Roller focus handling
-
-In the roller widget, the user wants the concept of focus to be
-highlighted by the list scrolling such that the focused row is in the
-vertical centre.
-
-Additionally, the user wants to be able to easily focus another
-unfocused visible item in the list simply by pressing it.
-
-### Animations
-
-The user wants to have a smooth and natural experience in using either
-list widget. If the scrolling stops half-way into an item and it is
-required that one item is focused (see[roller focus handling]( {{< ref "#roller-focus-handling" >}} )), they want
-the list to bounce a small scroll to focus said item.
-
-### Item launching
-
-An application author wants to be able to perform some
-application-specific behaviour in response to the selecting of an item
-in the list. However, they want to provide some confirmation before
-launching an item in a list. They want the two step process to be:
-
-1. The desired item is focused by scrolling to it or tapping on it.
-
-2. The focused item is tapped again which confirms the intention to
- launch it.
-
-### Header and footer
-
-The application author wants to add a header to the column to make it
-clear exactly what is in said column. (An example can be seen in
- [List design]( {{< ref "#list-design" >}} ) in the music application.)
-
-Another system integrator wants the column names to be shown above the
-widget in a footer instead of a header.
-
-### Roller rollover
-
-In the roller widget, by definition, the user wants to scroll from the
-last item in the list back to the first without having to go all the way
-back up.
-
-Additionally, the user wants the wrap around to be made more visually
-obvious with increased resistance when scrolling past the fold between
-end and start again.
-
-### Widget size
-
-The application author wants any list widget to expand into space
-allocated to it by its layout manager. If there are not enough items in
-the list to fill all available space said application author wants the
-remaining space to be blank, but still used by the list widget.
-
-### Click activation
-
-A system integrator wants to choose between single click and double
-click activation (see[item launching]( {{< ref "#item-launching" >}} )) for use in the list widgets. This
-is only expected once the item has already been focused (see also[roller focus handling]( {{< ref "#roller-focus-handling" >}} )).
-
-The decision of single or double click is given to the system integrator
-instead of the application author in order to retain a consistent user
-experience.
-
-### Consistent focus
-
-The user focuses an item in the list and a new item is added. The user
-expects the new item not to change the scroll position of the list and
-more importantly not to change the currently focused row.
-
-### Focus animation
-
-An application author wants an item in the list to be able to perform an
-animation after being focused.
-
-### Mutable list
-
-An application author wants to be able to change the contents of a list
-shown in the user interface after having created the widget and shown it
-in the user interface.
-
-### UI customisation
-
-A system integrator wants to change the look and feel of a list widget
-without having to change any of the application code.
-
-### Blur effect
-
-A system integrator wants items in the list to be slightly blurred when
-scrolling fast to exaggerate the scrolling effect. Another system
-integrator wants to disable this blur.
-
-### Scrollbar
-
-A system integrator wants a scrollbar to be visible for controlling the
-scrolling of the list. Another system integrator doesn't want the
-scrollbar visible.
-
-### Hardware scroll
-
-A system integrator wants to use hardware buttons to facilitate moving
-the focus up and down the list. The system integrator wants the list to
-scroll in pages and for the focus to remain in order. For example, a
-list contains items A, B, C, and D. When the *down* hardware button down
-is pressed, the page moves down to show items E, F, G, and H, and the
-focus moves to item E as it is the first on the page.
-
-### On-demand item resource loading
-
-The music application lists hundreds of albums but the application
-author doesn't want the album art thumbnail to be loaded for every item
-immediately as it would take too long and slow the system down. Instead,
-said application author wants album art thumbnail to load only once
-visible and have a placeholder picture in place until then.
-
-### Scroll bubbles
-
-A system integrator wants [bubbles] to appear when scrolling and
-disappear when scrolling has stopped.
-
-### Item headers
-
-An application author wants to display items in a list but have a
-logical separation into sections. For example, in a music application,
-listing all tracks of an artist and separating by album.
-
-Another application author wants said headers to stick to the top of the
-widget so they are always visible, even if the first item has been
-scrolled past and is no longer visible.
-
-### List with tens of thousands of items
-
-An application author wants to display a list containing thousands
-of items, but does not want to incur the initial cost of instantiating
-all the items when creating the list.
-
-
-### Flow layout
-
-An application author wants the list widget to render as a grid with
-multiple items on the same line. The following video shows such a grid layout.
-
-<video width="640" height="480" controls>
- <source src="/images/album_cover_roller.mp4" type="video/mp4">
- <source src="/images/album_cover_roller.ogv" type="video/ogg">
-</video>
-
-### Concurrent presentation of the same model in different list widgets
-
-An application author wants to present the same model in two side-by-side
-list widgets, possibly with different filtering or sorting.
-
-## Non-use cases
-
-A variety of non-use cases for the list design are given below.
-
-### Tree views
-
-An application author wants to show the filesystem hierarchy in their
-application. They understand that multi-dimension models (or trees)
-where items can be children of other items are not supported by the
-Apertis list widgets (hence the name list).
-
-### List widget without a backing model
-
-An application wants to display a list of items in the list widget,
-but does not wish to create a model and pass it to the list widget,
-and would rather use helper functions in the list widget, such as
-`list_add_item(List *list, ListItem *item)`.
-
-Such an interface is not considered necessary, at least for this
-version of the design document, because we want to encourage use of models
-so that the UI views themselves can be rearranged more easily.
-
-If, in the future, such an interface was considered desirable, its
-API should be similar to the [`GtkListBox`] API, such as
-`gtk_list_box_row_changed()`.
-
-### Sticky header and footer
-
-An application developer wants an actor to stick to the top or
-the bottom of the list widget, and always be visible regardless
-of scrolling.
-
-This is best handled as a separate actor, sharing a common parent
-with the list widget.
-
-## Requirements
-
-### Common API
-
-There should be a common API between both list widgets (see[common api]( {{< ref "#common-api" >}} )).
-Changing from a list widget to a roller widget or the other way around
-should involve only trivial changes to the code leading to a change in
-behaviour.
-
-### MVC separation
-
-The separation between components that use the list widgets should be
-functional and enable application authors and system integrators to swap
-out parts of applications easily and quickly (see[mvc separation]( {{< ref "#mvc-separation" >}} )).
-
-The implementation of the model should be of no impact to the
-functionality of the widget. As a result the widget should only refer to
-the model using an interface which all models can implement.
-
-### Data backend agnosticity
-
-The widget should not require application authors to store their backing
-model in any particular way.
-
-### Kinetic scrolling
-
-Both list widgets should support kinetic scrolling from user inputs (see[kinetic scrolling]( {{< ref "#kinetic-scrolling" >}} )). That is, when the user scrolls using their finger,
-he or she can *flick* the list up or down and the scroll will continue
-after the finger is released and gradually slow down. This animation
-should feel natural to the user as if he or she is moving a wheel up or
-down, with minimal friction. The animation should also be easily stopped
-by tapping once.
-
-#### Elastic effect
-
-In the list widget with a defined start and finish, on trying to scroll
-there should be visual feedback that the start or finish of the list has
-been reached. This visual feedback should be accomplished using the
-*elastic effect*. That is, when the bottom is reached and further
-downward scrolling is attempted, an empty space slowly appears with
-resistance, and pops back when the user releases their finger.
-
-This is not necessary on the roller widget because the list loops and
-there is no defined start and finish to the list.
-
-It should be easy to turn this feature off as it may be undesired by the
-system integrator (see[kinetic scrolling]( {{< ref "#kinetic-scrolling" >}} )).
-
-### Item focus
-
-In both list and roller widgets there should be a concept of focus which
-only one item has at any one point. How to display which item has focus
-depends on the widget.
-
-### Roller focus handling
-
-In the roller widget the focused item should always be in the vertical
-centre of the widget (see[roller focus handling]( {{< ref "#roller-focus-handling" >}} )). The focused item
-should visually change and even expand if necessary to demonstrate its
-focused state (see also[focus animation]( {{< ref "#focus-animation" >}} )).
-
-Changing which item is focused should be possible by clicking on another
-item in the list.
-
-### Animations
-
-It should be possible to add animations to widgets to allow for moving
-the current scroll location of the list up or down (see[animations]( {{< ref "#animations" >}} )).
-This should be customisable by the system integrator and application
-author depending on the application in question but should retain the
-general look and feel across the entire system.
-
-### Item launching
-
-Focused items (see [Item focus]( {{< ref "#item-focus" >}} )) should be able to be launched using
-widget-specific bindings (clicks or touches) (see [Click activation]( {{< ref "#click-activation" >}} )).
-
-### Header and footer
-
-It should be possible to add a header to a list to provide more context
-as to what the information is showing (see[header and footer]( {{< ref "#header-and-footer" >}} ) and the
-screenshot in [List design]( {{< ref "#list-design" >}} )). This should be customisable by the
-application author and should be consistent across the entire system.
-
-### Roller rollover
-
-The rollover of the two list widgets should be different and
-customisable by the system integrator (see[roller rollover]( {{< ref "#roller-rollover" >}} ) and[ui customisation]( {{< ref "#ui-customisation" >}} )).
-
-The roller widget should roll over from the end of the list back to the
-beginning again, like a cylinder would (see [List design]( {{< ref "#list-design" >}} ) and [Roller]( {{< ref "#roller" >}} )).
-Additionally the system integrator should be able to customise whether
-they want extra resistance in going back to the beginning. This is
-visual feedback to ensure the user knows they are returning to the
-beginning of the list.
-
-The non-roller list widget should not have a rollover and should have a
-well-defined start and finish, with visual effects as appropriate (see
- [Elastic effect]( {{< ref "#elastic-effect" >}} )).
-
-### Widget size
-
-The list widgets should expand to fill out all space that has been
-provided to them (see[widget size]( {{< ref "#widget-size" >}} )). They should fill any space not
-required with a blank colour, specified by the variant UI customisation
-(see[ui customisation]( {{< ref "#ui-customisation" >}} )).
-
-### Consistent focus
-
-The focus of items in a list should remain consistent despite
-modification of the list contents (see[consistent focus]( {{< ref "#consistent-focus" >}} )). Adding items
-before or after the currently focused item shouldn't change its focused
-state.
-
-### Focus animation
-
-The application author and system integrator should be able to specify
-whether there is an animation in selecting an item in a list (see[focus animation]( {{< ref "#focus-animation" >}} ) and[ui customisation]( {{< ref "#ui-customisation" >}} )). This could mean expanding an item to
-make the item focused larger vertically and even display extra controls
-which were previously hidden under the fold.
-
-During this animation, input should not be possible.
-
-### Mutable list
-
-The items shown in the list widgets and their content should update
-dynamically when the model backing the widget is updated (see[mutable list]( {{< ref "#mutable-list" >}} )). This should require no extra effort on the part of the
-application author.
-
-### UI customisation
-
-Both list widgets should be visibly customisable in the same way the
-rest of the system is and should honour UI customisations made by the
-system integrator (see[ui customisation]( {{< ref "#ui-customisation" >}} )). In this way, the list widgets
-should use CSS (see the UI Customisation Design document) for styling.
-
-### Blur effect
-
-The list widget should support slightly blurring list items only when
-scrolling (see[blur effect]( {{< ref "#blur-effect" >}} )). It should be easily to disable this feature
-by another system integrator who doesn't want the blur.
-
-### Scrollbar
-
-The list widget should support showing and hiding a scrollbar as
-necessary (see[scrollbar]( {{< ref "#scrollbar" >}} )). It should be easy to disable this feature by
-another system integrator who doesn't want to display a scrollbar.
-
-### Hardware scroll
-
-The list widget should support scrolling using hardware buttons and
-therefore always have one item focused [hardware scroll]( {{< ref "#hardware-scroll" >}} )). Hardware
-button callbacks should use the [adjustments][mx-scrollable] on the list widget to
-change the subset of visible items and the appropriate list widget
-function for moving the focus to the next item. Hardware button signals
-are generated as described in the Hardkeys Design.
-
-### On-demand item resource loading
-
-Items in the list need to know when they are visible (and not past the
-current scroll area) so they know when to load expensive resources, such
-as thumbnails from disk (see [On-demand item resource loading]( {{< ref "#on-demand-item-resource-loading" >}} )).
-
-### Scroll bubbles
-
-The scrollbar (see also[scrollbar]( {{< ref "#scrollbar" >}} )) should support showing bubbles to
-show the scroll position (see[scroll bubbles]( {{< ref "#scroll-bubbles" >}} )). It should be possible to
-disable the bubble and change its appearance when necessary.
-
-### Item headers
-
-It should be possible to add separating headers to sets of items in the
-list widgets (see[item headers]( {{< ref "#item-headers" >}} )). Said headers should also be sticky if
-specified.
-
-### Lazy list model
-
-It should be possible to provide a ‘lazy list store’ to the widget,
-in which items would be created on demand, when they need to be
-displayed to the user.
-
-This model could make memory usage and instantiation performance independent
-of the number of items in the model.
-
-See [List with tens of thousands of items]( {{< ref "#list-with-tens-of-thousands-of-items" >}} )
-
-### Flow layout
-
-It should be possible for *n* items, each of the same width and height, to be
-packed in the same row of the list, where *n* is calculated as the floor of
-the list width divided by the item width. There is no need for the programmer
-to set *n* manually.
-
-### Reusable model
-
-The underlying model should not have to be duplicated in order to present it
-in multiple list widgets at the same time.
-
-See [Concurrent presentation of the same model in different list widgets]( {{< ref "#concurrent-presentation-of-the-same-model-in-different-list-widgets" >}} )
-
-## Approach
-
-### Adapter interface
-
-As required by[data backend agnosticity1]( {{< ref "#data-backend-agnosticity1" >}} ), the backing data model format
-should not be imposed by the list widget upon the application developer.
-
-As such, an ‘adapter’ is required, similar to Android's [`ListAdapter`], this
-adapter will make the bridge between the list widget and the data that backs
-the list, by formatting data from the underlying model as list item widgets
-for rendering.
-
-The following diagram illustrates how this adapter helps decoupling the list
-widget from the underlying model.
-
-
-
-> In the above example, we assume a program that simply displays a list widget
-> exposing items stored in a database, and an adapter that stores strong
-> references to the created list items, and will eventually cache them all
-> if the list widget is fully scrolled down by the user. This is as opposed to
-> the approach presented in [Lazy list model]( {{< ref "#lazy-list-model" >}} ) where memory usage is also
-> taken into account.
->
-> The ‘cursor’ is a representation of whatever database access API is in use,
-> as most databases use cursor-based APIs for reading.
-
-An interface for this adapter (the contents of the list widgets) is
-required such that it can be swapped out easily where necessary
-(see[mvc separation]( {{< ref "#mvc-separation" >}} ), [Lazy list model]( {{< ref "#lazy-list-model" >}} )).
-
-GLib recently (since version 2.44) added an interface for this very
-task. [`GListModel`] is an implementation-agnostic interface for
-representing lists in a single dimension. It does not support tree
-models (see [Tree views]( {{< ref "#tree-views" >}} )) and contains everything required for the
-requirements specified in this document.
-
-It should be noted that `GListModel`, which is for arbitrary containers, is
-entirely unrelated to the `GList` data structure, which is for doubly linked
-lists.
-
-In addition to functions for accessing the contents of the adapter, there is
-also an `items-changed` signal for notifying the view (the list widget and list
-item widgets it contains; see[mvc separation]( {{< ref "#mvc-separation" >}} ))
-that it should re-render as a result of something changing in the adapter.
-
-### GtkListBox
-
-[`GtkListBox`] is a GTK+ widget added in 3.10 as a replacement for the
-very complicated [`GtkTreeView`] widget. `GtkTreeView` is used for
-displaying complex trees with customisable cell renderers, but more
-often lists are used instead of trees.
-
-`GtkListBox` doesn't have a separate model backing it (but one can be
-used), and each item is a `GtkListBoxRow` (which is in turn a `GtkWidget`).
-This makes using the widget and modifying its contents especially easy
-using the [`GtkContainer`] functions. Items can be activated (see[item launching]( {{< ref "#item-launching" >}} ) or selected (see [Item focus]( {{< ref "#item-focus" >}} )).
-
-`GtkListBox` has been used in many GNOME applications since its addition
-and has shown that its API is sufficient for most simple use cases, with
-a limited number of items.
-
-However `GtkListBox` is not scalable, as its interface requires that all its
-rows be instantiated at initialisation, in order for example to add headers
-to sections, and still be able to scroll accurately to any random position
-in the list (random access).
-
-As such, its API is only of a limited interest to us, particularly when it
-comes to[item headers]( {{< ref "#item-headers" >}} ) or[filtering]( {{< ref "#filtering" >}} ).
-
-### GtkFlowBox
-
-[GtkFlowBox] is a GTK+ widget added in 3.12 as a complement to `GtkListBox`.
-Its API takes a similar approach to that of `GtkListBox`: it doesn't have a
-separate model backing it – but one can be used – and each item is a
-`GtkFlowBoxChild` which contains the content for that item.
-
-As with `GtkListBox`, its API is interesting to us for its approach to
-reflowing children; see [Column layout]( {{< ref "#column-layout" >}} ).
-
-### Widget size
-
-The list widgets should expand to fill space assigned to them (see[widget size]( {{< ref "#widget-size" >}} )). This means that when there are too few items to fill space
-the remaining space should be filled appropriately, but when there are
-more items than can be shown at one time the list should be put into a
-scrolling container.
-
-In Clutter, actors are made to expand to fill the space they have been
-assigned by setting the `x-expand` and `y-expand` properties on
-`ClutterActor`. For example:
-
-``` c
-/* this actor will expand into horizontal space, but not into vertical
- * space, allocated to it. */
-clutter_actor_set_x_expand (first_actor, TRUE);
-clutter_actor_set_y_expand (first_actor, FALSE);
-
-/* this actor will expand into vertical space, but not into horizontal
- * space, allocated to it. */
-clutter_actor_set_x_expand (second_actor, FALSE);
-clutter_actor_set_y_expand (second_actor, TRUE);
-
-/* this actor will stretch to fill all allocated space, the
- * default behaviour. */
-clutter_actor_set_x_align (third_actor, CLUTTER_ACTOR_ALIGN_FILL);
-
-/* this actor will be centered inside the allocation. */
-clutter_actor_set_x_align (fourth_actor, CLUTTER_ACTOR_ALIGN_CENTER);
-```
-
-More details can be found in the [`ClutterActor`] documentation.
-
-The list item widgets (as described in[adaptermodel implementation]( {{< ref "#adaptermodel-implementation" >}} )) are packed
-by the list widget and so application authors have no control over their
-expanding or alignment.
-
-A suitable scrolling container to put a list widget into is the
-[`MxKineticScrollView`] as it provides kinetic scrolling (see[kinetic scrolling]( {{< ref "#kinetic-scrolling" >}} )
-and [Elastic effect]( {{< ref "#elastic-effect" >}} )) using touch events. Additionally, the
-`MxKineticScrollView` should be put into an `MxScrollView` to get a
-scrollbar where appropriate (see[scrollbar]( {{< ref "#scrollbar" >}} )).
-
-For support of `MxKineticScrollView` the list widgets should implement the
-`MxScrollable` interface, which allows getting and setting the
-adjustments, and is necessary in showing a viewport into the interface
-
-The exact dimensions in pixels for the widget shouldn't be specified by
-the application author as it means changes to the appearance desired by
-a system integrator are much more difficult to achieve.
-
-### Adapter/Model implementation
-
-As highlighted before (in [Adapter interface]( {{< ref "#adapter-interface" >}} )), the list widget should
-make no assumption about how the backing data is stored. An adapter data
-structure should be provided, making the bridge between the backing data
-and the list widget, by returning list item actors for any given position.
-
-The `GListModel` interface requires all its contained items to be
-[`GObject`s with the same `GType`][GListModel-desc].
-
-It is suggested that the items themselves are all instances of a new
-`ListItem` class, which will inherit from `ClutterActor`, and implement
-selection and activation logic.
-
-[`GListStore`] is an object in GLib which implements `GListModel`. It
-provides functions for inserting and appending items to the model but no
-more. For small lists, it is suggested to either use `GListStore` directly or
-implement a thin subclass to give more type safety and better-adapted function
-signatures.
-
-In these simple cases, `GListStore` will act as both the adapter *and* the
-backing model, as it is storing `ListItem` widgets. For more complicated use
-cases (where the same data source is being used by multiple list widgets), the
-adapter and backing model must be separated, and hence `GListStore` is not
-appropriate as the adapter in those cases. See [Decoupled model]( {{< ref "#decoupled-model" >}} ).
-
-### Decoupled model
-
-As shown in [Adapter interface]( {{< ref "#adapter-interface" >}} ), the list widget will not directly
-interact with the underlying data model, but through an ‘adapter’.
-
-The following diagram shows how the same underlying model may be queried
-by two different list widgets, and their corresponding adapters.
-
-
-
-> List widgets are the outermost boxes in the diagram; the adapters are the
-> next boxes inwards; and the middle box is the shared data model (a database).
->
-> The ‘cursors’ in the above diagram are a representation of whatever database
-> access API is in use, as most databases use cursor-based APIs for reading.
-
-### Lazy object creation
-
-`GListModel` allows an implementation to create items lazily (only create
-or update items on screen and next to be displayed when a scroll is
-initiated) for performance reasons. This is recommended for applications
-with a very large number of items, so a new ListItem isn't required for
-every single item in the list at initialisation.
-
-`GListStore` does not support lazy object creation so an alternative model
-will need to be implemented by applications which need to deal with
-huge models.
-
-An example for this is provided in [Alternative list adapter]( {{< ref "#alternative-list-adapter" >}} ).
-
-### High-level helpers
-
-Higher-level API should be provided in order to facilitate common usage
-scenarios, in the form of an adapter implementation.
-
-This adapter should be instantiatable from various common data models, through
-constructors such as: `list_adapter_new_from_g_list_model` or
-`list_adapter_new_from_g_list`.
-
-This default adapter should automatically generate an appropriate UI for
-the individual objects contained in the data model, with the only requirement
-that they all be instances of the same GObject subclass. This requirement
-should be clearly documented, as it won't be possible to enforce it at
-instantiation time for certain data models, such as `GList`, without iterating
-on all its nodes, thus forbidding the generic adapter from adopting a lazy
-loading strategy.
-
-The default behaviour of the adapter should be to provide a UI for all the
-properties exposed by the objects (provided it knows how to handle them),
-but much like the [Django admin site][django-admin-fields], it should be easy
-for the user to modify which of these properties are displayed, and the
-order in which they should be displayed, using a `set_fields()` method. The
-suggested `set_fields()` API would take a non-empty ordered list of property
-names for the properties of the objects in the model which the adapter should
-display. For example, if the model contains objects which represent music
-artists, and each of those objects has `name`, `genre` and `photo` properties,
-the adapter would try to create row widgets which display all three
-properties. If `set_fields (['name', 'genre'])` were called on the adapter, it
-would instead try to only display the name and genre for the artist (name first,
-genre second), and not their photo. The layout algorithm used for presenting
-these properties generically in the UI is not prescribed here.
-
-This generic adapter should expose virtual methods to allow potential
-subclasses to provide their own list item widgets for properties that may or
-may not be handled by the default implementation, and to provide their own list
-item widgets for each of the GObjects in the model. These are represented by
-`create_view_for_property()` and `create_view_for_object()` on the
- [API diagram]( {{< ref "#api-diagram" >}} ).
-
-The adapter should use weak references on the created list items, as
-examplified in [Alternative list adapter]( {{< ref "#alternative-list-adapter" >}} ).
-
-Filtering and sorting should be implemented by this adapter, with the option
-for the user to provide implementations of the sorting and filtering methods,
-and to trigger the sorting and filtering of the adapter. It should be clearly
-documented that these operations may be expensive, as the adapter will have
-no other option than iterating over the whole model.
-
-If developers want to use the list widget with an underlying model that
-allows more efficient sorting and filtering (for example a database), they
-should implement their own adapter.
-
-Refer to the [API diagram]( {{< ref "#api-diagram" >}} ) for a more formal view of the proposed API,
-and to the [Generic adapter]( {{< ref "#generic-adapter" >}} ) section for a practical usage example.
-
-### UI customisation
-
-The list and list item widgets should be `ApertisWidget` subclasses (which
-are in turn `ClutterActor`s) to take advantage of the `GtkApertisStylable`
-mixin that `ApertisWidget` uses. This adds support for styling the widget
-using CSS and [other style providers][GtkStyleProvider] which can be customised by
-system integrators.
-
-As the list item widgets are customisable widgets, they can appear any
-way the application author wants. This means that it is up to the
-application author to decide on theming decisions. Apertis-provided list
-item widgets will clearly document the CSS classes that affect their
-appearance.
-
-### Sorting
-
-Sorting the model is built into the `GListStore`. When adding a new item
-to the adapter `g_list_store_insert_sorted` is used with the third
-argument pointing to a function to help sort the model. All items can be
-sorted at once using the `g_list_store_sort` function, passing in the
-same or different sorting function.
-
-When using an [Alternative list adapter]( {{< ref "#alternative-list-adapter" >}} ), sorting will need to be
-implemented on a case-by-case basis.
-
-### Filtering
-
-As with `GtkListBox` when bound to a model, filtering should be implemented
-by updating the contents of the adapter.
-
-The list widget will be connected to the adapter, and will update itself
-appropriately when notified of changes.
-
-An example of this is shown in [the next section]( {{< ref "#filtering1" >}} ), the following
-diagram illustrates the filtering process.
-
-
-
-> The ‘cursors’ in the above diagram are a representation of whatever database
-> access API is in use, as most databases use cursor-based APIs for reading.
-
-### Header and footer
-
-The header should be a regular `ApertisWidget`, passed to the list widget as a
-`header` property. It will be rendered above the body of the list widget.
-Similarly, an `ApertisWidget` passed to a `footer` property will be rendered
-below the body of the list widget. Using arbitrary widgets means the header’s
-appearance is easily customisable. Passing them to the list widget means that
-the list widget can set the widgets’ width to match that of the list.
-
-Applications can set either, both, or neither, of the `header` and `footer`
-properties. If both are set, both a header and a footer are rendered, and the
-application may use different widgets in each.
-
-### Selections
-
-As with `GtkListBox`, it should be possible to select either one or many
-items in the list (see [Item focus]( {{< ref "#item-focus" >}} )). The application author can decide
-what is the behaviour of the list in question using the “selection
-modeâ€. The values for the selection mode are none (no items can be
-selected), single (at most one item can be selected), and multiple (any
-number of items can be selected). A multiple selection example can be found
-in the [Multiple selection]( {{< ref "#multiple-selection" >}} ) section.
-
-The `ListItem` object has a read-write property for determining it can be
-selected or not. An example that sets this property can be found
-in the [Non-selectable items]( {{< ref "#non-selectable-items" >}} ) section.
-
-The selection signals exposed by the list widget will be identical to those
-exposed by `GtkListBox`, namely `item-selected` when an item is focused,
-`item-activated` when the item is subsequently activated, and in the case
-of multiple selection, the `selected-items-changed` signal will give the user
-the full picture of the current items selected by the user, by being emitted
-every time the current selection changes, and passing an updated list of
-selected list items to potential callback functions.
-
-### Item headers
-
-Item headers are widgets used to separate items into logical groups (for
-example, when showing tracks of an artist, they could be grouped in
-albums with the album name as the item header).
-
-Due to the requirement for lazy initialisation, the solution proposed
-by `GtkListBox` cannot be adopted here, as it implies that all the list
-items need to be instantiated ahead of time.
-
-Our approach here is similar to [the solution][ListAdapter-separators] used
-with Android's `ListAdapter`: as the adapter is decoupled from the data model,
-and returns the actors that should be placed at a given position in the list,
-it may also account for such headers, which should be returned as unselectable
-`ListItem`s at specific positions in the adapter.
-
-We make no assumptions as to how implementations may choose to associate
-a selected list item with the data model: in the simple case, the index
-of a list item may be directly usable to access the backing object it
-represents, if the backing data is stored in an array, and no item header
-is inserted in the adapter.
-
-In other cases, where for example the backing data is stored in a database,
-or item headers are inserted and offset the indices of the following items,
-implementations may choose to store a reference to the backing object using
-`g_object_set_qdata` or an external mechanism such as a `GHashTable`.
-
-An example of item headers is shown in [the following section][Header items].
-
-### Sticky item headers
-
-As required for [Lazy list model]( {{< ref "#lazy-list-model" >}} ), when the list widget is scrolled to
-a random point, items surrounding the viewport may not be created yet.
-
-It is proposed that a simple API be exposed to let application developers
-specify the sticky item at any point in the scrolling process, named
-`list_set_sticky_func`.
-
-The implementation will, upon scrolling the list widget, pass this function
-the index of the top-most visible item, and expect it to return the `ListItem`
-that should be stickied (or `NULL`).
-
-### Blur effect
-
-Given the `MxKineticScrollView` container does the actual scrolling, it is
-the best place to implement the desired blur effect (see[blur effect]( {{< ref "#blur-effect" >}} )).
-Additionally, implementing it in the container means it can be
-implemented once instead of in every widget that needs to have a blur
-effect.
-
-### On-demand item resource loading
-
-By default, list items should assume they are not in view and should not
-perform expensive operations until they have been signalled by the list
-widget that they are in view (see [On-demand item resource loading]( {{< ref "#on-demand-item-resource-loading" >}} )). For
-example, a music application might have a long list of albums and each
-item has the album cover showing. Instead of loading every single album
-cover when creating the list, each list item should use a default dummy
-picture in its place. When the user scrolls the list, revealing
-previously hidden items, the album cover should be loaded and the
-default dummy picture replaced with the newly loaded picture.
-
-The list widget should have a way of determining the item from given
-co-ordinates so that it can signal to said item when it comes into view
-after a scroll event. The list item object should only perform expensive
-operations when it has come into view, by reading and monitoring a
-property on itself. Once visible an item will not return to the not
-visible state.
-
-### Scroll bubbles
-
-The bubble displayed when scrolling to indicate in which category the
-scroll is showing (see[scroll bubbles]( {{< ref "#scroll-bubbles" >}} )) should be added to `MxScrollBar` as
-that is the widget that controls changing the scroll position.
-
-### Roller subclass
-
-The roller widget should be implemented as a subclass of the list widget.
-
-The roller widget will implement the `MxScrollable` interface, setting
-appropriate increment values on its adjustments, in order to ensure the
-currently-focused row will always be aligned with the middle after scrolling.
-
-As the roller subclass will implement [rollover]( {{< ref "#roller-rollover" >}} ), the
-elastic effect when reaching the bottom of the list will not be used.
-
-In addition, it will also, in its `init` method, use a `ClutterEffect` in
-order to render itself as a cylinder (or ideally, as a [hexagonal prism]).
-
-### Column layout
-
-By default, the list widget will display as many items as fit per row, given
-the list’s width and the configured item width. Properties will be provided for:
- * A `row-spacing` property, setting the blank space between adjacent rows.
- * A `column-spacing` property, setting the blank space between adjacent
- columns.
- * An `item-width` property, setting the width of all columns.
- * An `item-height` property, setting the height of all rows.
-
-Note that `GtkFlowBox` supports reflowing children of different sizes; in this
-design, we only consider children of equal sizes, which simplifies the API. It
-is equivalent to considering a `GtkFlowBox` with its `homogeneous` property set
-to true.
-
-So, for example, to display items in a single column (one item per row), set the
-`item-width` to equal the list’s width. To implement a grid layout where some
-items may be missing and gaps should be left for them, implement a custom row
-widget which displays its own children in a grid; and display one such row
-widget per row of the list.
-
-We suggest the default value for `item-width` is to track the list’s width, so
-that the list uses a single column unless otherwise specified.
-
-### Focus animation
-
-A `use-animations` property will be exposed on the list items. Upon activation,
-an item with this property set to `True` will be animated to cover the whole
-width and height allocated to the list widget.
-
-Application developers may connect to the `item-activated` signal in order to
-update the contents of the item, as shown in [Item activation]( {{< ref "#item-activation" >}} ).
-
-Once the set of possible and valuable animations has become clearer, API
-may be exposed to give more control to system integrators and application
-developers.
-
-### Item launching
-
-In the roller subclass, the `item-activated` signal should only be emitted
-for actors in the currently focused row. This will ensure that only items
-that were scrolled to can be activated.
-
-### API diagram
-
-
-
-Signals are shown with a hash beforehand (for example, `#item-activated`),
-with arguments listed afterwards. Properties are shown with a plus sign
-beforehand and without getters or setters (`get_model()`, `set_model()`)
-for brevity.
-
-## Example API usage
-
-### Basic usage
-
-The following example creates a model, creates item actors for each
-artist available on the system, and adds them to the model. The exact
-API is purely an example but the approach to the API is to note.
-
-As a simple example, this avoids creating a separate adapter and model, and
-instead creates a model which contains the list row widgets. In more complex
-examples, where data from the model is being used by multiple list widgets,
-the model and adapter are separate, and the entries in the model are not
-necessarily widget objects. See [Generic adapter] for such an example.
-
-{{ ../examples/sample-list-api-usage-basic.c }}
-
-The object created by `create_sample_artist_item` is an instance of
-`ClutterActor` (or an instance of a subclass) which defines how the item
-will display in the list. In that case, it is as simple as packing in a
-`ClutterText` to display the name of the artist as a string.
-More likely it would use a `ClutterBoxLayout` layout manager to pack
-different `ClutterActor`s into a horizontal line showing properties of the
-artist.
-
-### Item activation
-
-The following example creates a list widget using the function defined
-in the previous section and connects to the `item-activated` signal to
-change the list item actor.
-
-{{ ../examples/sample-list-api-usage-item-activated.c }}
-
-### Filtering
-
-The following example shows how to filter the list store bound to the list
-widget created using the function implemented in [Basic usage]( {{< ref "#basic-usage" >}} )
-to only display items with a specific property.
-
-{{ ../examples/sample-list-api-usage-filtering.c }}
-
-### Multiple selection
-
-The following example sets the selection mode to allow multiple items to
-be simultaneously selected.
-
-{{ ../examples/sample-list-api-usage-selection.c }}
-
-### Non-selectable items
-
-The following example makes half the items in a list impossible to select.
-
-{{ ../examples/sample-list-api-usage-non-selectable-items.c }}
-
-### Header items
-
-The following example adds alphabetical header items to the list.
-
-{{ ../examples/sample-list-api-usage-header-items.c }}
-
-### On-demand item resource loading
-
-The following example shows how on-demand item resource loading could be
-implemented, using the model created in the first listing:
-
-{{ ../examples/sample-list-api-usage-resource-loading.c }}
-
-### Generic adapter
-
-The following example shows how developers may take advantage of the proposed
-generic adapter.
-
-{{ ../examples/sample-list-adapter-api-usage.c }}
-
-### Alternative list adapter
-
-Authors of applications do not necessarily need to use a `GListStore` as their
-adapter class. Instead they can implement the `GListModel` interface, and
-pass it as the adapter for the list widget.
-
-In the following example, we define and implement an adapter to optimise
-both initialisation performance by creating `MyArtistItem`s only when required,
-and memory usage by letting the `List` widget assume ownership of the created
-items.
-
-{{ ../examples/alternative_list_model.c }}
-
-## Requirements
-
-This design fulfils the following requirements:
-
- -[common api1]( {{< ref "#common-api1" >}} ) — the list widget and roller widget have the same
- API and any roller-specific roller API is in its own class.
-
- -[mvc separation1]( {{< ref "#mvc-separation1" >}} ) — `GListModel` is used as an adapter to the backing
- data, which storage format is not imposed to the user. The list widget
- and item widgets are separate objects.
-
- -[data backend agnosticity1]( {{< ref "#data-backend-agnosticity1" >}} ) — Applications provide list items through
- an adapter, no requirement is made as to the storage format.
-
- -[kinetic scrolling1]( {{< ref "#kinetic-scrolling1" >}} ) — use `MxKineticScrollView`.
-
- - [Elastic effect]( {{< ref "#elastic-effect" >}} ) — use `MxKineticScrollView`.
-
- - [Item focus]( {{< ref "#item-focus" >}} ) — list items can be selected ( [Selections]( {{< ref "#selections" >}} )).
-
- -[roller focus handling1]( {{< ref "#roller-focus-handling1" >}} ) — this roller-specific selecting
- behaviour can be added to the roller's class.
-
- -[animations1]( {{< ref "#animations1" >}} ) — use `MxKineticScrollView`.
-
- -[item launching1]( {{< ref "#item-launching1" >}} ) — the item-activated signal on the list widget
- will signal when an item is activated.
-
- -[header and footer1]( {{< ref "#header-and-footer1" >}} ) — `ApertisWidget`s can be set as header or footer
- [header and footer2]( {{< ref "#header-and-footer2" >}} )).
-
- -[roller rollover1]( {{< ref "#roller-rollover1" >}} ) — this roller-specific rollover behaviour can
- be added to the roller's class.
-
- -[widget size1]( {{< ref "#widget-size1" >}} ) — use `ClutterLayoutManager` and the `ClutterActor`
- properties [widget size2]( {{< ref "#widget-size2" >}} )).
-
- -[consistent focus1]( {{< ref "#consistent-focus1" >}} ) — the API asserts a consistent focus and
- ensures the implementation behaves when the model changes.
-
- -[focus animation1]( {{< ref "#focus-animation1" >}} ) — items are `ClutterActor`s which can animate
- using regular Clutter API.
-
- -[mutable list1]( {{< ref "#mutable-list1" >}} ) — use `GListStore`.
-
- -[ui customisation1]( {{< ref "#ui-customisation1" >}} ) — subclass `ApertisWidget` and use the
- `GtkStyleProvider`s.
-
- -[blur effect1]( {{< ref "#blur-effect1" >}} ) — add a `motion-blur` property to
- `MxKineticScrollView` and use that [blur effect2]( {{< ref "#blur-effect2" >}} )).
-
- -[scrollbar1]( {{< ref "#scrollbar1" >}} ) — use the `scroll-visibility` property on the
- `MxScrollView` container.
-
- -[hardware scroll1]( {{< ref "#hardware-scroll1" >}} ) — use the adjustment on the list widget to
- scroll down a page, and use the appropriate function to move the
- selection on.
-
- - [On-demand item resource loading1]( {{< ref "#on-demand-item-resource-loading1" >}} ) — ensure list widget can look
- up the item based on co-ordinates, and add a property to the list
- item object to denote whether it’s in view, which the list widget
- updates.
-
- -[scroll bubbles1]( {{< ref "#scroll-bubbles1" >}} ) — add support for overlay actors to
- `MxScrollBar`.
-
- -[item headers1]( {{< ref "#item-headers1" >}} ) — Added as regular `ListItem`s in the adapter, a
- `list_set_sticky_func` API is exposed.
-
- - [Lazy list model]( {{< ref "#lazy-list-model" >}} ) — see [Alternative list adapter]( {{< ref "#alternative-list-adapter" >}} ), for an example
- of how application developers may implement their own model.
-
- - [Flow layout]( {{< ref "#flow-layout" >}} ) — The number of columns is calculated by dividing the
- list width by the specified item width. Padding between the resulting
- columns and rows may be specified using `row-spacing` and `column-spacing`
- properties.
-
-## Summary of recommendations
-
-As discussed in the above sections, we recommend:
-
- - Write a list widget partially based on `GtkListBox`, which subclasses
- `ApertisWidget`.
-
- - Write a list item widget partially based on `GtkListBoxRow` which also
- subclasses ApertisWidget.
-
- - Add a `motion-blur` property to `MxKineticScrollView`.
-
- - Expose a sticky item callback registration method.
-
- - Add support for overlay actors to `MxScrollBar`.
-
- - Write a Roller widget as a list widget subclass.
-
- - Ensure new widgets are easily customisable using CSS.
-
- - Add demo programs for the new widgets.
-
- - Define unit tests to run manually using the example programs to
- check the widgets work
- correctly.
-
-## Appendix
-
-### Existing roller design
-
-
-
-
-
-[bubbles]: http://i.stack.imgur.com/YyRtC.png
-
-[mx-scrollable]: https://github.com/clutter-project/mx/blob/master/mx/mx-scrollable.h
-
-[`GListModel`]: https://developer.gnome.org/gio/stable/GListModel.html
-
-[`GtkListBox`]: https://developer.gnome.org/gtk3/stable/GtkListBox.html
-
-[`GtkFlowBox`]: https://developer.gnome.org/gtk3/stable/GtkFlowBox.html
-
-[`GtkTreeView`]: https://developer.gnome.org/gtk3/stable/GtkTreeView.html
-
-[`GtkContainer`]: https://developer.gnome.org/gtk3/stable/GtkContainer.html
-
-[`ClutterActor`]: https://developer.gnome.org/clutter/stable/ClutterActor.html
-
-[`MxKineticScrollView`]: https://github.com/clutter-project/mx/blob/master/mx/mx-kinetic-scroll-view.h
-
-[GListModel-desc]: https://developer.gnome.org/gio/stable/GListModel.html#GListModel.description
-
-[`GListStore`]: https://developer.gnome.org/gio/stable/GListStore.html
-
-[GtkStyleProvider]: https://developer.gnome.org/gtk3/stable/GtkStyleProvider.html
-
-[`ListAdapter`]: https://developer.android.com/reference/android/widget/ListAdapter.html
-
-[ListAdapter-separators]: http://stackoverflow.com/questions/18302494/how-to-add-section-separators-dividers-to-a-listview
-
-[hexagonal prism]: http://static.kidspot.com.au/cm_assets/32906/hexagonal-prism_346x210-jpg-20151022203100.jpg~q75,dx330y198u1r1gg,c--.jpg
-
-[django-admin-fields]: https://docs.djangoproject.com/en/1.10/ref/contrib/admin/#django.contrib.admin.ModelAdmin.fields
diff --git a/content/designs/software-development-kit.md b/content/designs/software-development-kit.md
deleted file mode 100644
index 1b4e9b3ad..000000000
--- a/content/designs/software-development-kit.md
+++ /dev/null
@@ -1,469 +0,0 @@
-+++
-title = "SDK"
-short-description = "Software Development Kit purpose and design (partially-implemented, no available app validation tool, usability can be improved)"
-weight = 100
-toc = true
-aliases = [
- "/old-designs/latest/software-development-kit.html",
- "/old-designs/v2019/software-development-kit.html",
- "/old-designs/v2020/software-development-kit.html",
- "/old-designs/v2021dev3/software-development-kit.html",
-]
-outputs = [ "html", "pdf-in",]
-date = "2016-05-28"
-+++
-
-# Software Development Kit
-
-## Definitions
-
-- **Application Binary Interface (ABI) Stability**: the library
- guarantees API stability and further guarantees dependent
- applications and libraries will not require any changes to
- successfully link against any future release. The library may
- add new public symbols freely.
-
-- **Application Programming Interface (API) Stability**: the
- library guarantees to not remove or change any public symbols in
- a way that would require dependent applications or libraries to
- change their source code to successfully compile and link
- against later releases of the library. The library may add new
- public symbols freely. Later releases of the API-stable library
- may include ABI breaks which require dependent applications or
- libraries to be recompiled to successfully link against the
- library. Compare to **ABI Stability**.
-
-- **Backwards compatibility**: the guarantee that a library will
- not change in a way that will require existing dependent
- applications or libraries to change their source code to run
- against future releases of the library. This is a more general
- term than ABI or API stability, so it does not necessarily imply
- ABI stability.
-
-- **Disruptive release**: a release in which backwards
- compatibility is broken. Note that this term is unique to this
- project. In some development contexts, the term “major releaseâ€
- is used instead. However, that term is ambiguous in general.
-
-## Software Development Kit (SDK) Purpose
-
-The primary purpose of the special SDK system image will be to enable
-Apertis application and third-party library development. It will include
-development tools and documentation to make this process as simple as
-possible for developers. And a significant part of this will be the
-ability to run the SDK within the VirtualBox PC emulator. VirtualBox
-runs on ordinary x86 hardware which tends to make development much
-simpler than a process which requires building and running
-in-development software directly on the target hardware which will be of
-significantly lower performance relative to developer computers.
-
-## API/ABI Stability Guarantees
-
-Collabora will carry along open source software components' API and ABI
-stability guarantees into the Apertis Reference SDK API. In most cases,
-this will be a guarantee of complete API and ABI stability for all
-future releases with the same major version. Because these portions of
-Apertis will not be upgraded to later disruptive releases, these
-portions will maintain API and ABI stability at least for each major
-release of Apertis.
-
-The platform software included in the Reference system images will be in
-the form of regular Debian packages and never in the form of
-application-level packages, which are described in the “Apertis
-Supported API†document. Collabora will manage API/ABI stability of the
-platform libraries and prevent conflicts between libraries at this
-level.
-
-See the “Apertis Supported API†document for more details of specific
-components' stability guarantees and the software management of
-platform, core application, and third-party application software.
-
-## Reference System Image Composition
-
-See the document “Apertis Build and Integrationâ€, section “Reference
-System Image Compositionâ€.
-
-## System Image Software Licenses
-
-See the document “Apertis Build and Integration†for details on license
-checking and compliance of software contained in the system images.
-
-## Development Workflow
-
-### Typical Workflow
-
-Most developers working on specific libraries or applications will not
-be strictly dependent upon the exact performance characteristics of the
-device hardware. And even those who are performance-dependent may wish
-to work within the SDK when they aren't strictly tuning performance, as
-it will yield a much shorter development cycle.
-
-For these most-common use cases, a typical workflow will look like:
-
-1. modify source code in Eclipse
-
-2. build (for x86)
-
-3. smoke-test within the Target Simulator
-
-4. return to step 1. if necessary
-
-In order to test this code on the actual device, the code will need to
-be cross-compiled (see the document “Apertis Build and Integration
-Designâ€, section “App cross-compilationâ€). To do so, the developer would
-follow the steps above with:
-
-1. run [Install to target]( {{< ref "#install-to-target" >}} ) Eclipse plugin
-
-2. test package contents on device
-
-3. return to step 1. if necessary
-
-The development workflow for the Reference and derived images themselves
-will be much more low-level and are outside the scope of this document.
-
-### On-device Workflow
-
-Some work, particularly performance tuning and graphics-intense
-application development, will require testing on a target device. The
-workflow [above][Typical workflow] handles this use case, but developing on a target device
-can save the time of copying files from a development machine to the
-device.
-
-This workflow will instead look like:
-
-1. modify source code as needed
-
-2. run [Install to target]( {{< ref "#install-to-target" >}} ) Eclipse plugin
-
-3. test package contents on device
-
-4. if debugging is necessary, either
-
- 1. run [Remote app debugging]( {{< ref "#remote-app-debugging" >}} ) Eclipse plugin; or
-
- 2. open secure shell (ssh) connection to target device for
- multi-process or otherwise-complex debugging scenarios
-
-5. return to step 2. if necessary
-
-### Workflow-simplifying Plugins
-
-Some of the workflow steps [above][Typical worflow] will be simplified by streamlining
-repetitive tasks and automating as much as possible.
-
-#### Install to Target
-
-This Eclipse plugin will automatically:
-
-1. build the cross-architecture Apertis app bundle
-
-2. copy generated ARM package to target
-
-3. Install package
-
-It will use a sysroot staging directory (as described in the document
-“Apertis Build and Integration Designâ€, section “App
-cross-compilationâ€) to build the app bundle and SSH to copy and
-remotely and install it on the target.
-
-App bundle signature validation will be disabled in the Debugging and
-SDK images, so the security system will not interfere with executing
-in-development apps.
-
-#### Remote App Debugging
-
-This Eclipse plugin will connect to a target device over SSH and, using
-information from the project manifest file, execute the application
-within GDB. The user will be able to run GDB commands as with local
-programs and will be able to interact with the application on the device
-hardware itself.
-
-This plugin will be specifically created for single application
-debugging. Developers of multi-process services will need to connect to
-the device manually to configure GDB and other tools appropriately, as
-it would be infeasible to support a wide variety of complex setups in a
-single plugin.
-
-#### Sysroot Updater
-
-This Eclipse plugin will check for a newer sysroot archive. If found,
-the newer archive will be downloaded and installed such that it can be
-used by the [Install to target]( {{< ref "#install-to-target" >}} ) plugin.
-
-## 3D acceleration within VirtualBox
-
-Apertis will depend heavily on the Clutter library for animations in its
-toolkit and for custom animations within applications themselves.
-Clutter requires a working 3D graphics stack in order to function.
-Without direct hardware support, this requires a software OpenGL driver,
-which is historically very slow. Our proposed SDK runtime environment,
-VirtualBox, offers experimental 3D hardware “pass-through†to achieve
-adequate performance. However, at the time of this writing, this support
-is unreliable and works only on very limited host hardware/software
-combinations.
-
-We propose resolving this issue with the new “llvmpipe†software OpenGL
-driver for the Mesa OpenGL implementation. This is the
-community-supported solution to replace the current,
-significantly-slower, “swrast†software driver. Both the upcoming
-versions of Fedora and Ubuntu Linux distributions will rely upon the
-“llvmpipe†driver as a fallback in the case of missing hardware
-support. The latest development version of Ubuntu 12.04, which Collabora
-is developing our Reference system images against, already defaults to
-“llvmpipeâ€. Additionally, the “llvmpipe†driver implements more
-portions of the OpenGL standard (which Clutter relies upon) than the
-“swrast†driver.
-
-In initial testing with an animated Clutter/Clutter-GTK application,
-llvmpipe performance was more than adequate for development purposes. In
-a VirtualBox guest with 2 CPU cores and 3 GiB of RAM, demo applications
-using the Roller widget displayed approximately 20-30 frames per second
-and had very good interactivity with the llvmpipe driver. In comparison,
-the same program running with the swrast driver averaged 4 frames per
-second and had very poor interactivity.
-
-While this approach will not perform as well as a hardware-supported
-implementation, and will vary depending on host machine specifications,
-it will be the most reliable option for a wide variety of VirtualBox
-host operating system, configuration, and hardware combinations.
-
-## Simulating Multi-touch in VirtualBox
-
-Because Apertis will support multi-touch events and most VirtualBox
-hosts will only have single pointing devices, the system will need a way
-to simulate multi-touch events in software. Even with adequate hardware
-on the host system, VirtualBox does not support multiple cursors, so the
-simulating software must be fully-contained within the system images
-themselves.
-
-### Software-based solution
-
-We propose a software-based solution for generating multi-touch events
-within the SDK. This will require a few new, small components, outlined
-below.
-
-In the intended usage, the user would use the [Multi-touch gesture generator]( {{< ref "#multi-touch-gesture-generator" >}} )
-to perform a gesture over an application running in the Target
-Simulator as if interacting with the hardware display(s) in an Apertis
-system. The Gesture Generator will then issue commands through its
-uinput device and the [Uinput Gesture Device Xorg Driver]( {{< ref "#uinput-gesture-device-xorg-driver" >}} ) will use those
-commands to generate native X11 multi-touch events. Applications running
-within the Target Simulator will then interpret those multi-touch events
-as necessary (likely through special events in the Apertis application
-toolkit).
-
-#### Multi-touch Gesture Generator
-
-This will be a very simple user interface with a few widgets for each
-type of gesture to generate. The developer will click on a button in the
-generator to start a gesture, then perform a click-drag anywhere within
-VirtualBox to trigger a set of multi-touch events. The generator will
-draw simple graphics on the screen to indicate the type and magnitude of
-the gesture as the developer drags the mouse cursor.
-
-
-
-We anticipate the need for two gestures commonly used in popular
-multi-touch user interfaces:
-
- - **Pinch/zoom**: the movement of a thumb and forefinger toward
- (zoom-out) or away (zoom-in) from each other. This gesture has a
- magnitude and position. The position allows, e.g., a map application
- to zoom in on the position being pinched rather than requiring a
- separate zoom into the center of the viewable area, then a drag of
- the map.
-
- - Zoom-in: simulated by initiating the pinch/zoom gesture from the
- Gesture Generator, then click-dragging up-right. The distance
- dragged will determine the magnitude of the zoom.
-
- - Zoom-out: the same process as for zoom-in, but in the opposite
- direction
-
- - **Rotate**: the movement of two points around an imaginary center
- point. Can be performed either in a clockwise or counter-clockwise
- direction. This gesture has a magnitude and position. The position
- allows, e.g., a photo in a gallery app to be rotated independent of
- the other photos.
-
- - Clockwise: simulated by initiating the rotate gesture, then
- click-dragging to the right. This can be imagined as drag
- affecting the top of a wheel.
-
- - Counter-clockwise: the same process as for clockwise, but in the
- opposite direction.
-
-Additional gestures could be added during the specification process, if
-necessary.
-
-
-
-Upon the user completing the simulated gesture, the Gesture Generator
-would issue a small number of key or movement events through a special
-uinput device (which we will refer to as the Uinput Gesture Device).
-Uinput is a kernel feature which allows “userland†software (any
-software which runs directly or indirectly on top of the kernel) to
-issue character device actions, such as key presses, releases,
-two-dimensional movement events, and so on. This uinput device will be
-interpreted by the [Uinput Gesture Device Xorg Driver]( {{< ref "#uinput-gesture-device-xorg-driver" >}} ).
-
-#### Uinput Gesture Device Xorg Driver
-
-This component will interpret the input stream from our Uinput Gesture
-Device and generate X11 multi-touch events. These events would, in turn,
-be handled by the windows lying under the events.
-
-#### X11 Multi-touch Event Handling
-
-Windows belonging to applications running within the Target Simulator
-will need to handle multi-touch events as they would single-touch
-events, key presses, and so on. This would require to add support for
-multi-touch events in the Apertis application toolkit for applications
-to simply handle multi-touch events the same as single-touch events.
-
-### Hardware-based solution
-
-An alternative to the software-based solution [above][Software-based solution] would be to use a
-hardware multi-touch pad on the host machine. This is a simpler solution
-requiring less original development though it brings a risk of Windows
-driver issues which would be outside of our control. Because of this, we
-recommend Collabora perform further research before finalizing upon this
-solution if this is preferred over the [Software-based solution]( {{< ref "#software-based-solution" >}} ).
-
-The touch pad hardware would need to be well-supported in Linux but not
-necessarily the host operating system (including Windows) because
-VirtualBox supports USB pass-through. This means that output from the
-touch pad would simply be copied from the host operating system into
-VirtualBox, where Xorg would generate multi-touch events for us.
-
-The best-supported multi-touch device for Linux is Apple's Magic
-Trackpad. This device uses a Bluetooth connection. Many Bluetooth
-receivers act as USB devices, allowing pass-through to VirtualBox. In
-case a host machine does not have a built-in Bluetooth receiver or has a
-Bluetooth receiver but does not route Bluetooth data through USB, an
-inexpensive Bluetooth-to-USB adapter could be used.
-
-Collabora has verified that multi-touch gestures on an Apple Magic
-Trackpad plugged into a Linux host can be properly interpreted within
-Debian running within VirtualBox. This suggests that a hardware-based
-solution is entirely feasible.
-
-#### Hardware Sourcing Risks
-
-Collabora investigated risks associated with selecting a single hardware
-provider for this multi-touch solution. The known risks at this point
-include:
-
-1. Apple has a history of discontinuing product lines with little
- warning
-
-2. As of this writing, there appear to be few alternative multi-touch
- pointing devices which are relatively inexpensive and support
- arbitrary multi-touch movements
-
-In the worst case scenario, Apple could discontinue the Magic Trackpad
-or introduce a new version which does not (immediately) work as expected
-within Linux. With no immediate drop-in replacement for the Magic
-Trackpad, there would not be a replacement to recommend internally and
-to third-party developers using the Apertis SDK.
-
-However, there are several mitigating factors that should make these
-minor risks:
-
-1. Inventory for existing Magic Trackpads would not disappear
- immediately upon discontinuation of the product
-
-2. Discontinuation of a stand-alone multi-touch trackpad entirely is
- very unlikely due to Apple's increasingly-strong integration of
- multi-touch gestures within iOS and Mac OS itself.
-
-3. In case Apple replaces the Magic Trackpad with a Linux-incompatible
- version, there is significant interest within the Linux community to
- fix existing drivers to support the new version in a timely manner.
- For instance, Canonical multi-touch developers use the Magic
- Trackpad for their development and will share Apertis's sourcing
- concerns as well.
-
-4. As an ultimate fallback, [Multi-touch gesture generator]( {{< ref "#multi-touch-gesture-generator" >}} ) can be
- recommended as an alternative source of multi-touch input.
-
-## Third-party Application Validation Tools
-
-### Two-step Application Validation Process
-
-The third-party application process will contain two main validation
-steps which mirror the application submission processes for Android and
-iOS apps. The first, SDK-side validation checks will be performed by a
-tool described below. Developers may perform SDK-side validation as
-often as they like before submitting their application for approval.
-This is meant to automatically catch as many errors in an application as
-soon as possible to meet quality requirements for application review.
-
-The second step of the application validation process is to validate
-that an application meets the app store quality requirements. It is
-recommended to set up a process where new applications automatically get
-run through this same Eclipse plugin as an initial step in review. This
-will guarantee applications meet the latest automated validation checks
-(which may not have been met within the developer's SDK if their Eclipse
-plugin were old). Developers will be able to easily stay up-to-date with
-the validation tool by applying system package updates within the SDK,
-so this difference can be minimized by a small amount of effort on the
-developer's part. Applications which pass this initial check will then
-continue to a manual evaluation process.
-
-### App Validation Tool
-
-To streamline the third-party application submission process (which will
-be detailed in another document), Collabora will provide an Eclipse
-plugin to perform a number of
-
-SDK-side validation checks up on the application in development.
-Collabora proposed checks are:
-
- - **Application contains valid developer signing key** – developers
- must create a certificate to sign their application releases so
- verifying the source of application updates can be guaranteed. This
- check will ensure that the certificate configured for the
- application meets basic requirements on expiration date and other
- criteria.
-
- - **Manifest file is valid** – the application manifest file, which
- will be used in the software management of third-party applications
- on the platform, must meet a number of basic requirements including
- a developer name, application categories, permissions, minimum SDK
- API, and more.
-
- - **Application builds from cleaned source tree** – this step will
- delete files in the source tree which are neither included in the
- project nor belong to the version control system and perform a full
- release build for the ARMHF architecture. Build warnings will be
- permitted but build errors will fail this check.
-
- - **AppArmor profile is valid** – the application's AppArmor profile
- definition must not contain invalid syntax or conflict with the
- Apertis global AppArmor configuration
-
-Third-party application validation will be specified in depth in another
-document.
-
-## General approach to third-party applications
-
-In most cases, third-party applications should not need to explicitly
-validate their access to specific system resources, delegating as much
-as possible to the SDK API or to other parts of the system. Preferably,
-these applications will specify system resource requirements in their
-manifest, such as permissions the application needs to function, network
-requirements, and so on. The main advantages of having these in the
-manifest file are using shared code to perform some of the actual
-run-time resource requests.
-
-Note that this strategy implies a trade-off between how simple it is to
-write an application and how complex the supporting SDK and system
-components need to be to provide that simplicity. That is to say, it
-often makes sense to impose complexity onto applications, in particular
-when it's expected that only a few will have a given requirement or use
-case. This general approach should be kept in mind while designing the
-SDK and any other interfaces the system has with third-party
-applications and their manifests.
-
diff --git a/content/guides/gitlab-based_packaging_workflow.md b/content/guides/gitlab-based_packaging_workflow.md
index c9ea72226..be3026a89 100644
--- a/content/guides/gitlab-based_packaging_workflow.md
+++ b/content/guides/gitlab-based_packaging_workflow.md
@@ -39,7 +39,7 @@ following conventions:
All the instructions below assume an Apertis development enviroment: either
boot the
-[Apertis SDK]( {{< ref "software-development-kit.md" >}} )
+[Apertis SDK]( {{< ref "virtualbox.md" >}} )
or enter the `apertis-*-package-source-builder` Docker container:
APERTIS_RELEASE=v2019pre
diff --git a/content/guides/howtodevelopondevices.md b/content/guides/howtodevelopondevices.md
index be039359a..3200679af 100644
--- a/content/guides/howtodevelopondevices.md
+++ b/content/guides/howtodevelopondevices.md
@@ -99,7 +99,7 @@ You should then be able to SSH in using:
The recommended environment to build platform packages and application bundles
is the
-[Apertis SDK]( {{< ref "software-development-kit.md" >}} ).
+[Apertis SDK]( {{< ref "virtualbox.md" >}} ).
However, it is also possible to build software on the devices directly with the
preparation steps below:
--
GitLab