← Back to branch summary

~ubuntu-branches/ubuntu/utopic/kde-workspace/utopic-proposed

« back to all changes in this revision

Viewing changes to kwin/clients/aurorae/theme-description

  • Committer: Bazaar Package Importer
  • Author(s): Michał Zając
  • Date: 2011-07-09 08:31:15 UTC
  • Revision ID: james.westby@ubuntu.com-20110709083115-ohyxn6z93mily9fc
Tags: upstream-4.6.90
Import upstream version 4.6.90

Show diffs side-by-side

added added

removed removed

Lines of Context:
kwin/clients/aurorae/theme-description
 
1
DESCRIPTION OF AURORAE
 
2
======================
 
3
 
 
4
Aurorae is a theme engine for KWin window decorations. It is built against the unstable API of KWin
 
5
in KDE 4.3. Aurorae uses SVG to render the decoration and buttons and there is a simple config file
 
6
for configuring the theme details.
 
7
 
 
8
This theme engine uses Plasma technologie to render the window decoration. Every detail can be
 
9
themed by the usage of SVG. The theme engine uses Plasma's FrameSvg, so you can provide SVG files
 
10
containing borders. This is described in more detail in techbase:
 
11
http://techbase.kde.org/Projects/Plasma/Theme#Backgrounds
 
12
 
 
13
The theme consists of one folder containing svgz files for decoration and buttons, one KConfig file
 
14
for the theme details and one metadata.desktop file which you can use to name your theme, author
 
15
information, etc.
 
16
 
 
17
Although the engine uses Plasma technology, it isn't Plasma. So it does not know anything about
 
18
Plasmoids and you will never be able to put Plasmoids into the decoration. That is out of scope of
 
19
this engine.
 
20
 
 
21
Aurorae uses the features provided by KWin 4.3. So the themes can provide their own decoration
 
22
shadows and it is recommended that your themes provide those. The engine supports ARGB decoration
 
23
which is enabled by default. If you provide a theme using translucency, please make sure, that it
 
24
works without compositing as well.
 
25
 
 
26
Window Decoration
 
27
=================
 
28
The window decoration has to be provided in file "decoration.svgz". This svg has to contain all the
 
29
elements required for a Plasma theme background. The decoration has to use the element prefix
 
30
"decoration".
 
31
 
 
32
If you want to provide a different style for inactive windows you can add it to the same svg. The
 
33
inactive elements must have the element prefix "decoration-inactive". The theme engine tests for
 
34
this prefix and if not provided inactive windows will be rendered with the same style as active
 
35
windows.
 
36
 
 
37
You have to provide a special decoration for opaque mode, that is when compositing is not active.
 
38
This opaque decoration is used for generating the window mask. The element prefix is
 
39
"decoration-opaque" for active and "decoration-opaque-inactive" for inactive windows. The mask is
 
40
generated from the active window.
 
41
 
 
42
Maximized Windows
 
43
-----------------
 
44
In order to better support maximized windows there exists a special frame svg called
 
45
"decoration-maximized". In the same way as for the general decoration you can specify a version for
 
46
inactive, opaque and inactive-opaque. This results in the following names:
 
47
 * decoration-maximized
 
48
 * decoration-maximized-inactive
 
49
 * decoration-maximized-opaque
 
50
 * decoration-maximized-opaque-inactive
 
51
 
 
52
In all cases only the center element will be used. There is no need to specify borders. Please note
 
53
that in case of a window with translucent widgets the center element will be stretched to the size
 
54
of the complete window.
 
55
 
 
56
The following fallback strategy is used: if inactive is not present it falls back to the active.
 
57
If opaque is not present it falls back to the translucent. If none of the maximized elements are
 
58
present the center element of the decoration is used!
 
59
 
 
60
In order to support Fitts' Law all TitleEdge Settings are set to 0. So the buttons will be directly
 
61
next to the screen edges. You have the possibility to overwrite these settins (see below).
 
62
 
 
63
Buttons
 
64
=======
 
65
You have to provide a svgz file for each button your theme should contain. If you do not provide a
 
66
file for a button type the engine will not include that button, so your decoration will miss it.
 
67
There is no fallback to a default theme. The buttons are rendered using Plasma's FrameSvg as well.
 
68
So you have to provide the "center" element. Borders are not supported
 
69
 
 
70
You can provide the following buttons:
 
71
 * close
 
72
 * minimize
 
73
 * maximize
 
74
 * restore
 
75
 * alldesktops
 
76
 * keepabove
 
77
 * keepbelow
 
78
 * shade
 
79
 * resize
 
80
 * help
 
81
 
 
82
Each button can have different states. So a button could be hovered, pressed, deactivated and you
 
83
might want to provide different styles for active and inactive windows. You can use the following
 
84
element prefix to provide styles for the buttons:
 
85
 * active (normal button for active window)
 
86
 * inactive (normal button for inactive window)
 
87
 * hover (hover state for active window)
 
88
 * hover-inactive (hover state for inactive window)
 
89
 * pressed (button is pressed)
 
90
 * pressed-inactive (pressed inactive button)
 
91
 * deactivated (button cannot be clicked, e.g. window cannot be closed)
 
92
 * deactivated-inactive (same for inactive windows)
 
93
 
 
94
You have at least to provide the active element. All other elements are optional and the active
 
95
element is always used as a fallback. If you provide the inactive element, this is used as a
 
96
fallback for the inactive window. That is, if you provide a hover element, but none for inactive,
 
97
the inactive window will not have a hover effect. Same is true for pressed and deactivated.
 
98
Reasonable that means if you provide a deactivated and an inactive element you want to provide a
 
99
deactivated-inactive element as well.
 
100
 
 
101
Configuration file
 
102
==================
 
103
The configuration file is a normal KConfig file. You have to give it the name of your decoration
 
104
with suffix "rc". So if your theme has the name "deco", your config file will be named "decorc".
 
105
The following section shows the possible options with their default values.
 
106
 
 
107
[General]
 
108
TitleAlignment=Left             # vorizontal alignment of window title
 
109
TitleVerticalAlignment=Center   # vertical alignment of window title
 
110
Animation=0                     # animation duration in msec when hovering a button and on active/inactive change
 
111
ActiveTextColor=0,0,0,255       # title text color of active window
 
112
InactiveTextColor=0,0,0,255     # title text color of inactive window
 
113
UseTextShadow=false             # Draw Shadow behind title text
 
114
ActiveTextShadowColor=255,255,255,255 # Shadow text color of active window
 
115
InactiveTextShadowColor=255,255,255,255 # Shadow text color of active window
 
116
TextShadowOffsetX=0             # Offset of shadow in x direction
 
117
TextShadowOffsetY=0             # Offset of shadow in y direction
 
118
HaloActive=false                # Draw halo behing title of active window (since 4.5)
 
119
HaloInactive=false              # Draw halo behing title of inactive window (since 4.5)
 
120
LeftButtons=MS                  # buttons in left button group (see http://api.kde.org/4.x-api/kdebase-workspace-apidocs/kwin/lib/html/classKDecorationOptions.html#8ad12d76c93c5f1a12ea07b30f92d2fa)
 
121
RightButtons=HIA__X             # buttons in right button group
 
122
Shadow=true                     # decoration provides shadows: you have to add padding
 
123
 
 
124
[Layout]                        # uses Layout Manager (see http://api.kde.org/4.x-api/kdebase-workspace-apidocs/kwin/lib/html/classKCommonDecoration.html#7932f74c28432ad8de232f1c6e8751ce)
 
125
BorderLeft=5
 
126
BorderRight=5
 
127
BorderBottom=5
 
128
TitleEdgeTop=5
 
129
TitleEdgeBottom=5
 
130
TitleEdgeLeft=5
 
131
TitleEdgeRight=5
 
132
TitleEdgeTopMaximized=0
 
133
TitleEdgeBottomMaximized=0
 
134
TitleEdgeLeftMaximized=0
 
135
TitleEdgeRightMaximized=0
 
136
TitleBorderLeft=5
 
137
TitleBorderRight=5
 
138
TitleHeight=20
 
139
ButtonWidth=20
 
140
ButtonWidthMinimize=?           # optional - default depends on ButtonWidth
 
141
ButtonWidthMaximizeRestore=?    # optional - default depends on ButtonWidth
 
142
ButtonWidthClose=?              # optional - default depends on ButtonWidth
 
143
ButtonWidthAlldesktops=?        # optional - default depends on ButtonWidth
 
144
ButtonWidthKeepabove=?          # optional - default depends on ButtonWidth
 
145
ButtonWidthKeepbelow=?          # optional - default depends on ButtonWidth
 
146
ButtonWidthShade=?              # optional - default depends on ButtonWidth
 
147
ButtonWidthHelp=?               # optional - default depends on ButtonWidth
 
148
ButtonWidthMenu=?               # optional - default depends on ButtonWidth
 
149
ButtonHeight=20
 
150
ButtonSpacing=5
 
151
ButtonMarginTop=0
 
152
ExplicitButtonSpacer=10
 
153
PaddingTop=0                    # Padding added to provide shadows
 
154
PaddingBottom=0                 # Padding added to provide shadows
 
155
PaddingRight=0                  # Padding added to provide shadows
 
156
PaddingLeft=0                   # Padding added to provide shadows
 
157
 
 
158
Packaging
 
159
=========
 
160
All theme files (decoration, buttons, metadata.desktop and configuration file) have to be stored in
 
161
one directory with the name of the theme (this has to be identical to the one used for the config
 
162
file). You have to create a tar.gz archive from that directory. This archive is the theme, which
 
163
can be installed in the kcm for window decorations.