napcok/calamares
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[branding] Update documentation about API versions

Browse Source
This commit is contained in:
Adriaan de Groot 2019-06-17 12:45:06 +02:00
parent c7d09f06c5
commit bba0b7ce12
1 changed files with 38 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
src/branding/README.md
View File

@ -12,6 +12,7 @@ forking Calamares just for adding some files. Calamares installs
CMake support macros to help create branding packages. See the
calamares-branding repository for examples of stand-alone branding.
## Examples
There is one example of a branding component included with Calamares,
@ -31,6 +32,41 @@ repository.
[1] https://github.com/calamares/calamares-branding
## API Versions
In Calamares versions prior to 3.2.10, the QML slideshow was loaded
synchronously when the installation page is shown. This can lead to
noticeable lag when showing that page. The QML is written start when
it is loaded, by responding to the `onComplete` signal.
Calamares 3.2.10 introduces an API versioning scheme which uses different
loading mechanisms.
- **API version 1** Loads the QML slideshow synchronously, as before.
- The QML can use `onComplete` to start timers, etc. for progress
or animation.
- Translations are supported through `qsTr()` and the language that is
in use when the installation slideshow is loaded, will be used
(once the installation part is running, it can't change anyway).
- **API version 2** Loads the QML slideshow **a**synchronously, on
startup (generally during the requirements-checking phase of Calamares)
so that no compilation lag is seen.
- The QML should **not** use `onComplete`, since the QML is loaded and
instantiated at startup. Instead,
- The QML should provide functions `onActivate()` and `onLeave()` in the
root object of the slideshow. These are called when the slideshow
should start (e.g. becomes visible) and stop.
- Translations are supported through `qsTr()`. However, since the language
can change after the QML is loaded, code should count on the bindings
being re-evaluated on language change. Translation updates (e.g. change
of language) is **only supported** with Qt 5.10 and later.
The setting *slideshowAPI* in `branding.desc` indicates which one to use
for a given branding slideshow. Which API to use is really a function of
the QML. Expect the version 1 API to be deprecated in the course of Calamares 3.3.
## Translations
QML files in a branding component can be translated. Translations should
@ -58,6 +94,7 @@ If you are packaging the branding by hand, use
```
with all the language suffixes to *file*.
## Presentation
The default QML classes provided by Calamares can be used for a simple
@ -113,6 +150,7 @@ The presentation classes can be used to produce a fairly dry slideshow
for the installation process; it is recommended to experiment with the
visual effects and classes available in QtQuick.
## Project Layout
A branding component that is created and installed outside of Calamares