style-colors.md 5.74 KB
Newer Older
Carl Schwan's avatar
Carl Schwan committed
1
2
3
---
title: "Colors and Themes in Kirigami"
linkTitle: "Colors "
Carl Schwan's avatar
Carl Schwan committed
4
5
weight: 101
group: style
Carl Schwan's avatar
Carl Schwan committed
6
description: >
Yuri Chornoivan's avatar
Yuri Chornoivan committed
7
  Make your app follow your user color scheme
8
9
aliases:
  - /docs/kirigami/style-colors/
Carl Schwan's avatar
Carl Schwan committed
10
11
12
13
14
15
---

Kirigami has a color palette that follow the system colors, to better integrate 
on the platform it is running on (i.e. Plasma Desktop, Plasma Mobile, 
GNOME, Android, etc.).

Carl Schwan's avatar
Carl Schwan committed
16
17
All of Kirigami's QML components and
all the Qt Quick Controls 2 QML components will already 
Carl Schwan's avatar
Carl Schwan committed
18
19
20
21
follow this palette by default, so usually no custom coloring should be needed 
at all for those controls.

Primitive components such as `Rectangle` should always be colored with the 
22
color palette provided by Kirigami via the [`Theme`](docs:kirigami2;Kirigami::PlatformTheme) attached property.
Carl Schwan's avatar
Carl Schwan committed
23
24
25
26
27

Hardcoded colors in QML, such as `#32b2fa` or `red` should usually be 
avoided; if it is really necessary to have elements with custom colors, it should 
be an area where only custom colors are used (usually in the content area 
of the app, and never in the chrome such as toolbars or dialogs), for instance 
Carl Schwan's avatar
Carl Schwan committed
28
a hardcoded `black` foreground cannot be used over a 
Carl Schwan's avatar
Carl Schwan committed
29
`Kirigami.Theme.backgroundColor` background, because if the platform uses a 
Carl Schwan's avatar
Carl Schwan committed
30
dark color scheme the result will look poor contrasting black over almost black.
Carl Schwan's avatar
Carl Schwan committed
31
32
33

## Theme

Carl Schwan's avatar
Carl Schwan committed
34
For more information about the Kirigami Theme class, see the [API docs](docs:kirigami2;Kirigami::PlatformTheme)
Carl Schwan's avatar
Carl Schwan committed
35
36

`Kirigami.Theme` is an attached property, therefore is available to use in 
Carl Schwan's avatar
Carl Schwan committed
37
any QML item. It contains as properties all the colors available in the 
Carl Schwan's avatar
Carl Schwan committed
38
39
40
41
42
palette, and what 
palette to use, as the `colorSet` property.

Example:

Carl Schwan's avatar
Carl Schwan committed
43
```qml
Carl Schwan's avatar
Carl Schwan committed
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
import QtQuick 2.11
import org.kde.kirigami 2.9 as Kirigami

Rectangle {
    color: Kirigami.Theme.backgroundColor
}
```

<!-- TODO
screenshot of a qml file with an annotated UI showing all the 
available color
-->

## Color Set

Carl Schwan's avatar
Carl Schwan committed
59
Depending on where a control is located, it should use a different color set: for 
Carl Schwan's avatar
Carl Schwan committed
60
61
62
63
instance, (with the Breeze light color theme) in itemviews, the normal 
background is almost white, while in other regions, such as toolbars or 
dialogs, the normal background color is gray.

Carl Schwan's avatar
Carl Schwan committed
64
65
If you set a color set for an item, all of its child items (recursively)
 will inherit it automatically (unless the property `inherit` has 
Carl Schwan's avatar
Carl Schwan committed
66
67
explicitly been set to `false`, which should always be done when the developer 
wants to force a specific color set) so it is easy to change colors for an 
Carl Schwan's avatar
Carl Schwan committed
68
entire hierarchy of items without touching any of the items themselves.
Carl Schwan's avatar
Carl Schwan committed
69
70
71
72
73
74
75

`Kirigami.Theme` supports 5 different color sets:

* View: Color set for item views, usually the lightest of all
  (in light color themes)
* Window: **Default** Color set for windows and "chrome" areas
* Button: Color set used by buttons
Carl Schwan's avatar
Carl Schwan committed
76
* Selection: Color set used by selected areas
Carl Schwan's avatar
Carl Schwan committed
77
78
* Tooltip: Color set used by tooltips
* Complementary: Color set meant to be complementary to Window: usually
Carl Schwan's avatar
Carl Schwan committed
79
  is dark even in light themes. May be used for "emphasis" in small
Carl Schwan's avatar
Carl Schwan committed
80
81
82
83
  areas of the application

Example:

Carl Schwan's avatar
Carl Schwan committed
84
```qml
Carl Schwan's avatar
Carl Schwan committed
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
import QtQuick 2.11
import QtQuick.Controls 2.2 as Controls
import org.kde.kirigami 2.9 as Kirigami

// The comments assume the system uses the Breeze Light color theme 
...
Rectangle {
    // A gray color will be used, as the default color set is Window
    color: Kirigami.Theme.backgroundColor

    Controls.Label {
        // The text will be near-black, as is defined in the Window 
        // color set
        text: i18n("hello")
    }

    Rectangle {
        ...
        // Use the set for ItemViews
        Kirigami.Theme.colorSet: Kirigami.Theme.View  

        // Do not inherit from the parent
        Kirigami.Theme.inherit: false

        // This will be a near-white color
        color: Kirigami.Theme.backgroundColor

        Rectangle {
            ...
            // This will be a near-white color too, as the colorSet 
            // is inherited from the parent and will be View
            color: Kirigami.Theme.backgroundColor

            Controls.Label {
                // The text will be near-black, as is defined in the View 
                // color set
                text: i18n("hello")
            }
        }
        Rectangle {
            ...
            // Use the Complementary set
            Kirigami.Theme.colorSet: Kirigami.Theme.Complementary  

            // Do not inherit from the parent
            Kirigami.Theme.inherit: false

            // This will be near-black as in the Complementary color set 
            // the background color is dark.
            color: Kirigami.Theme.backgroundColor  

            Controls.Label {
                // The text will be near-white, as is defined in the 
                // Complementary color set
                text: i18n("hello")
            }
        }
    }
}
```

Some components such as Labels will automatically inherit by default the color 
set, some other components have a fixed color set, for instance Buttons 
Carl Schwan's avatar
Carl Schwan committed
148
149
are fixed to the `Button` color set. If it's desired for the button to inherit 
the parent color set, the `inherit` property should be explicitly set to `true`:
Carl Schwan's avatar
Carl Schwan committed
150

Carl Schwan's avatar
Carl Schwan committed
151
```qml
Carl Schwan's avatar
Carl Schwan committed
152
153
154
155
156
157
158
159
160
161
import QtQuick 2.11
import QtQuick.Controls 2.2 as Controls
import org.kde.kirigami 2.9 as Kirigami

Controls.Button {
    Kirigami.Theme.inherit: true
    text: i18n("ok")
}
```

Carl Schwan's avatar
Carl Schwan committed
162
![Screenshot of a comparison between a button that inherits and one that does not](buttonsinherit.png)
Carl Schwan's avatar
Carl Schwan committed
163
164
165

## Using Custom Colors

Yuri Chornoivan's avatar
Yuri Chornoivan committed
166
Although it's discouraged to use hardcoded colors, Kirigami offers a more 
Carl Schwan's avatar
Carl Schwan committed
167
168
169
170
maintainable way to assign a custom hardcoded palette to an item and all its 
children, that will allow to define such custom colors in one place and one 
only:

171
{{< readfile file="/content/docs/use/kirigami/style-colors/CustomColors.qml" highlight="qml" >}}
Carl Schwan's avatar
Carl Schwan committed
172
173

![Screenshot showing the code above with qmlscene, we can see two rectangles with two different colors](customcolors.png)