calamares/src/branding

Branding directory

Branding components can go here, or they can be installed separately.

A branding component is a subdirectory with a branding.desc descriptor file, containing brand-specific strings in a key-value structure, plus brand-specific images or QML. Such a subdirectory, when placed here, is automatically picked up by CMake and made available to Calamares.

It is recommended to package branding separately, so as to avoid 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, so that it can be run directly from the build directory for testing purposes:

• default/ is a sample brand for the Generic Linux distribution. It uses the default Calamares icons and a as start-page splash it provides a tag-cloud view of languages. The slideshow is a basic one with a few slides of text and a single image. Translations (done by hand, not via the usual mechanism of Calamares translations) in English, Arabic, Dutch and French are available.

Since the slideshow can be any QML, it is limited only by your designers imagination and your QML experience. For straightforward presentations, see the documentation below. There are more examples in the [calamares-branding][1] 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 asynchronously, 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 be placed in a subdirectory lang/ of the branding component directory. Qt translation files are supported (.ts sources which get compiled into .qm). Inside the lang subdirectory all translation files must be named according to the scheme calamares-<component name>_<language>.ts.

The example branding component, called default, therefore has translation files names calamares-default_nl.ts (similar for other languages than Dutch).

Text in your show.qml (or whatever slideshow is set to in the descriptor file) should be enclosed in this form for translations

    text: qsTr("This is an example text.")

If you use CMake for preparing branding for packaging, the macro calamares_add_branding_subdirectory()`` (see also *Project Layout*, below) will convert the source .ts` files to their compiled form). If you are packaging the branding by hand, use

    lrelease file_en.ts [file_en_GB.ts ..]

with all the language suffixes to file.

Presentation

The default QML classes provided by Calamares can be used for a simple and straightforward "slideshow" presentation with static text and pictures. To use the default slideshow classes, start with a show.qml file with the following content:

import QtQuick 2.5;
import calamares.slideshow 1.0;

Presentation
{
    id: presentation
}

After the id, set properties of the presentation as a whole. These include:

• loopSlides (default true) When set, clicking past the last slide returns to the very first slide.
• mouseNavigation, arrowNavigation, keyShortcutsEnabled (all default true) enable different ways to navigate the slideshow.
• titleColor, textColor change the look of the presentation.
• fontFamily, codeFontFamily change the look of text in the presentation.

After setting properties, you can add elements to the presentation. Generally, you will add a few presentation-level elements first, then slides.

• For visible navigation arrows, add elements of class ForwardButton and BackwardButton. Set the source property of each to a suitable image. See the fancy/ example in the external branding-examples repository. It is recommended to turn off other kinds of navigation when visible navigation is used.
• To indicate where the user is, add an element of class SlideCounter. This indicates in "n / total" form where the user is in the slideshow.
• To automatically advance the presentation (for a fully passive slideshow), add a timer that calls the goToNextSlide() function of the presentation. See the default/ example -- remember to start the timer when the presentation is completely loaded.

After setting the presentation elements, add one or more Slide elements. The presentation framework will make a slideshow out of the Slide elements, displaying only one at a time. Each slide is an element in itself, so you can put whatever visual elements you like in the slide. They have standard properties for a boring "static text" slideshow, though:

• title is text to show as slide title
• centeredText is displayed in a large-ish font
• writeInText is displayed by "writing it in" to the slide, one letter at a time.
• content is a list of things which are displayed as a bulleted list.

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 will have a top-level CMakeLists.txt that includes some boilerplate to find Calamares, and then adds a subdirectory which contains the actual branding component.

The file layout in a typical branding component repository is:

 /
 - CMakeLists.txt
 - componentname/
   - show.qml
   - image1.png
   ...
   - lang/
     - calamares-componentname_en.ts
     - calamares-componentname_de.ts
     ...

Adding the subdirectory can be done as follows:

• If the directory contains files only, and optionally has a single subdirectory lang/ which contains the translation files for the component, then calamares_add_branding_subdirectory() can be used, which takes only the name of the subdirectory.
• If the branding component has many files which are organized into subdirectories, use the SUBDIRECTORIES argument to the CMake function to additionally install files from those subdirectories. For example, if the component places all of its images in an img/ subdirectory, then call calamares_add_branding_subdirectory( ... SUBDIRECTORIES img). It is a bad idea to include lang/ in the SUBDIRECTORIES list.
• The .ts files from the lang/ subdirectory need be be compiled to .qm files before being installed. The CMake macro's do this automatically. For manual packaging, use lrelease to compile the files.