source: calamares/trunk/fuentes/src/branding/README.md @ 7538

Last change on this file since 7538 was 7538, checked in by kbut, 13 months ago

sync with github

File size: 5.5 KB
Line 
1# Branding directory
2
3Branding components can go here, or they can be installed separately.
4
5A branding component is a subdirectory with a `branding.desc` descriptor
6file, containing brand-specific strings in a key-value structure, plus
7brand-specific images or QML. Such a subdirectory, when placed here, is
8automatically picked up by CMake and made available to Calamares.
9
10It is recommended to package branding separately, so as to avoid
11forking Calamares just for adding some files. Calamares installs
12CMake support macros to help create branding packages. See the
13calamares-branding repository for examples of stand-alone branding.
14
15## Examples
16
17There is one example of a branding component included with Calamares,
18so that it can be run directly from the build directory for testing purposes:
19
20 - `default/` is a sample brand for the Generic Linux distribution. It uses
21   the default Calamares icons and a as start-page splash it provides a
22   tag-cloud view of languages. The slideshow is a basic one with a few
23   slides of text and a single image. No translations are provided.
24
25Since the slideshow can be **any** QML, it is limited only by your designers
26imagination and your QML experience. For straightforward presentations,
27see the documentation below. There are more examples in the *calamares-branding*
28repository.
29
30## Translations
31
32QML files in a branding component can be translated. Translations should
33be placed in a subdirectory `lang/` of the branding component directory.
34Qt translation files are supported (`.ts` sources which get compiled into
35`.qm`). Inside the `lang` subdirectory all translation files must be named
36according to the scheme `calamares-<component name>_<language>.ts`.
37
38Text in your `show.qml` (or whatever *slideshow* is set to in the descriptor
39file) should be enclosed in this form for translations
40
41```
42    text: qsTr("This is an example text.")
43```
44
45## Presentation
46
47The default QML classes provided by Calamares can be used for a simple
48and straightforward "slideshow" presentation with static text and
49pictures. To use the default slideshow classes, start with a `show.qml`
50file with the following content:
51
52```
53import QtQuick 2.5;
54import calamares.slideshow 1.0;
55
56Presentation
57{
58    id: presentation
59}
60```
61
62After the *id*, set properties of the presentation as a whole. These include:
63 - *loopSlides* (default true) When set, clicking past the last slide
64   returns to the very first slide.
65 - *mouseNavigation*, *arrowNavigation*, *keyShortcutsEnabled* (all default
66   true) enable different ways to navigate the slideshow.
67 - *titleColor*, *textColor* change the look of the presentation.
68 - *fontFamily*, *codeFontFamily* change the look of text in the presentation.
69
70After setting properties, you can add elements to the presentation.
71Generally, you will add a few presentation-level elements first,
72then slides.
73 - For visible navigation arrows, add elements of class *ForwardButton* and
74   *BackwardButton*. Set the *source* property of each to a suitable
75   image. See the `fancy/` example. It is recommended to turn off other
76   kinds of navigation when visible navigation is used.
77 - To indicate where the user is, add an element of class *SlideCounter*.
78   This indicates in "n / total" form where the user is in the slideshow.
79 - To automatically advance the presentation (for a fully passive slideshow),
80   add a timer that calls the `goToNextSlide()` function of the presentation.
81   See the `default/` example -- remember to start the timer when the
82   presentation is completely loaded.
83
84After setting the presentation elements, add one or more Slide elements.
85The presentation framework will make a slideshow out of the Slide
86elements, displaying only one at a time. Each slide is an element in itself,
87so you can put whatever visual elements you like in the slide. They have
88standard properties for a boring "static text" slideshow, though:
89 - *title* is text to show as slide title
90 - *centeredText* is displayed in a large-ish font
91 - *writeInText* is displayed by "writing it in" to the slide,
92   one letter at a time.
93 - *content* is a list of things which are displayed as a bulleted list.
94
95The presentation classes can be used to produce a fairly dry slideshow
96for the installation process; it is recommended to experiment with the
97visual effects and classes available in QtQuick.
98
99## Project Layout
100
101A branding component that is created and installed outside of Calamares
102will have a top-level `CMakeLists.txt` that includes some boilerplate
103to find Calamares, and then adds a subdirectory which contains the
104actual branding component.
105
106Adding the subdirectory can be done as follows:
107
108 - If the directory contains files only, and optionally has a single
109   subdirectory lang/ which contains the translation files for the
110   component, then `calamares_add_branding_subdirectory()` can be
111   used, which takes only the name of the subdirectory.
112
113The file layout in a typical branding component repository is:
114
115```
116 /
117 - CMakeLists.txt
118 - componentname/
119   - show.qml
120   - image1.png
121   ...
122   - lang/
123     - calamares-componentname_en.ts
124     - calamares-componentname_de.ts
125     ...
126```
127
128 - If the branding component has many files which are organized into
129   subdirectories, use the SUBDIRECTORIES argument to the CMake function
130   to additionally install files from those subdirectories. For example,
131   if the component places all of its images in an `img/` subdirectory,
132   then call `calamares_add_branding_subdirectory( ... SUBDIRECTORIES img)`.
133   It is a bad idea to include `lang/` in the SUBDIRECTORIES list.
Note: See TracBrowser for help on using the repository browser.