User:Mgraesslin/Aurorae: Difference between revisions

From KDE TechBase
(bold items)
(Text color for window tabs)
 
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
Aurorae is a theme engine for [[Projects/KWin|KWin]] window decorations. It uses SVG to render the decoration and buttons and there is a simple config file for configuring the theme details.  
Aurorae is a theme engine for [[Projects/KWin|KWin]] window decorations. It uses SVG to render the decoration and buttons and there is a simple config file for configuring the theme details.  


This theme engine uses Plasma technology to render the window decoration. Every detail can be themed by the usage of SVG. The theme engine uses Plasma's FrameSvg, so you can provide SVG files containing borders. This is described in more detail in Plasma's [[Projects/Plasma/Theme|Theme description]].  
This theme engine uses Plasma technology to render the window decoration. Every detail can be themed by the usage of SVG. The theme engine uses Plasma's FrameSvg for the window borders. This is described in more detail in Plasma's [[Projects/Plasma/Theme|Theme description]].  


The theme consists of one folder containing svgz files for decoration and buttons, one KConfig file for the theme details and one metadata.desktop file which you can use to name your theme, author information, etc.  
The theme consists of one folder containing svgz files for decoration and buttons, one KConfig file for the theme details and one metadata.desktop file which is used for theme name, author information, etc.  


Although the engine uses Plasma technology, it isn't Plasma. So it does not know anything about Plasmoids and you will never be able to put Plasmoids into the decoration. That is out of scope of this engine.  
The engine supports ARGB decoration which is enabled by default, so that the theme can draw its own shadows. Nevertheless the themes should take care of the case that no desktop effects are used.


Aurorae uses the features provided by KWin 4.3. So the themes can provide their own decoration shadows and it is recommended that your themes provide those. The engine supports ARGB decoration which is enabled by default. If you provide a theme using translucency, please make sure, that it works without compositing as well.
= Aurorae Designer =
With [http://kde-apps.org/content/show.php/AuroraeDesigner?content=122763 Aurorae Designer] there exists a special tool to design Aurorae themes. It is recommended to designers to use this tool. It helps to identify common pitfalls and provides an easy way to change settings and test if the theme contains all required elements.
 
The code of Aurorae Designer is developed in parallel to Aurorae, so Aurorae Designer might contain features which will be present in a future release of Aurorae, which is bound to the release schedule of the Software Compilation


= Window Decoration  =
= Window Decoration  =


The window decoration has to be provided in file "decoration.svgz". This svg has to contain all the elements required for a Plasma theme background. The decoration has to use the element prefix "decoration".  
The window decoration has to be provided in file '''decoration.svgz'''. This svg has to contain all the elements required for a Plasma theme background. The decoration has to use the element prefix ''decoration''.
 
A different style for inactive windows can be provided in the same svg. The inactive elements must have the element prefix ''decoration-inactive''. The theme engine tests for this prefix and if not provided inactive windows will be rendered with the same style as active windows.  


If you want to provide a different style for inactive windows you can add it to the same svg. The inactive elements must have the element prefix "decoration-inactive". The theme engine tests for this prefix and if not provided inactive windows will be rendered with the same style as active windows.  
A special decoration for opaque mode, that is when compositing is not active, has to be provided. This opaque decoration is used for generating the window mask. The element prefix is ''decoration-opaque'' for active and ''decoration-opaque-inactive'' for inactive windows. The mask is generated from the frame svg for active window only.


You have to provide a special decoration for opaque mode, that is when compositing is not active. This opaque decoration is used for generating the window mask. The element prefix is "decoration-opaque" for active and "decoration-opaque-inactive" for inactive windows. The mask is generated from the active window.  
To summarize the following elements are supported:
* '''decoration:''' This at least has to be provided
* '''decoration-inactive:''' If not provided ''decoration'' is used
* '''decoration-opaque:''' Required to generate the window mask. If not provided ''decoration'' is used.
* '''decoration-opaque-inactive:''' If not provided either ''decoration-opaque'', ''decoration-inactive'' or ''decoration'' is used.


= Maximized Windows  =
== Maximized Windows  ==


In order to better support maximized windows there exists a special frame svg called "decoration-maximized". In the same way as for the general decoration you can specify a version for inactive, opaque and inactive-opaque. This results in the following names:  
In order to better support maximized windows there exists a special frame svg called ''decoration-maximized''. In the same way as for the general decoration a version for inactive, opaque and inactive-opaque can be specified. This results in the following names:  


*'''decoration-maximized'''
*'''decoration-maximized'''  
*'''decoration-maximized-inactive'''
*'''decoration-maximized-inactive'''  
*'''decoration-maximized-opaque'''
*'''decoration-maximized-opaque'''  
*'''decoration-maximized-opaque-inactive'''
*'''decoration-maximized-opaque-inactive'''


Line 30: Line 39:
The following fallback strategy is used: if inactive is not present it falls back to the active. If opaque is not present it falls back to the translucent. If none of the maximized elements are present the center element of the decoration is used!  
The following fallback strategy is used: if inactive is not present it falls back to the active. If opaque is not present it falls back to the translucent. If none of the maximized elements are present the center element of the decoration is used!  


In order to support Fitts' Law all TitleEdge Settings are set to 0. So the buttons will be directly next to the screen edges. You have the possibility to overwrite these settings (see below).  
In order to support Fitts' Law all TitleEdge Settings are set to 0. So the buttons will be directly next to the screen edges.
 
The support for maximized windows exists since KDE SC 4.5.
 
== Window Tabs ==
Aurorae supports KWin's window tabs for all themes by default. The theme has the possibility to influence the look of the tabs in the decoration by providing additional elements. If the theme does not provide these elements Aurorae paints a line between the tabs with the text color of an unfocused tab.
 
The following FrameSvg elements are added for tabs:
*'''tab-active-focused''': element for the focused (selected) tab in the active window
*'''tab-active-unfocused''': element for all unfocused (unselected) tabs in the active window
*'''tab-inactive-focused''': element for the focused (selected) tab in inactive windows
*'''tab-inactive-unfocused''': element for all unfocused (unselected) tabs in inactive windows
 
A theme has to provide both focused and unfocused elements. The elements for inactive windows are optional. The elements for active windows are used if the inactive are not present. If the inactive are present both focused and unfocused elements are required. All elements may have full border supports.
 
The support for window tabs exists since KDE SC 4.5.
 
== Inner Borders ==
Aurorae supports inner borders, that is a border at the margin to the window. While it would be possible to add inner borders directly in the decoration element, the inner borders are to be preferred as those support the configurable border sizes.
 
For inner borders the decoration svg file can include two additional FrameSvgs: '''innerborder''' and '''innerborder-inactive'''.  If the inactive element is not present the active element is used for inactive windows.
 
These frames must include the border elements. Only the border elements will be visible, the center element is not visible. For performance reasons the center element should be a simple rect and for support of decoration behind windows it should be completely translucent.
 
{{Box|Maximized windows and inner borders|
Inner borders are not shown for maximized windows. If a maximized window should show an inner border it is recommeded to directly add it to the maximized element.
|100%}}
The support for inner borders exists since KDE SC 4.5.
 
== Button Groups ==
An Aurorae decoration may include elements to be painted behind the button groups. This is intended for cases when the buttons share a common background. it should be preferred over custom editing of each button as this will result in a bad visual experience for explicit spacers or if the user changes the order of buttons.
 
The following elements are supported:
*'''buttongroup-left'''
*'''buttongroup-left-inactive'''
*'''buttongroup-right'''
*'''buttongroup-right-inactive'''
 
If the inactive element is not provided, the element for active is used for the inactive decoration, too. Left and right are independent and there is no fallback to the other element. For decorations on left or right window side the meaning becomes top and bottom.


= Buttons  =
= Buttons  =


You have to provide a svgz file for each button your theme should contain. If you do not provide a file for a button type the engine will not include that button, so your decoration will miss it. There is no fallback to a default theme. The buttons are rendered using Plasma's FrameSvg as well. So you have to provide the "center" element. Borders are not supported  
A svgz file has to be provided for each button. If the theme does not provide a file for a button type the engine will not include that button, so the decoration will miss it. There is no fallback to a default theme. The buttons are rendered using Plasma's FrameSvg just like the decoration. Each button has to provide the "center" element. Borders are not supported  


You can provide the following buttons:  
The following buttons are supported:
*'''close'''
*'''close:''' closes the window
*'''minimize'''
*'''minimize:''' minimizes the window
*'''maximize'''
*'''maximize:''' maximizes the window; replaces the ''restore'' button when not maximized
*'''restore'''
*'''restore:''' restores the window from maximized state; replaces the ''maximize'' button when maximized
*'''alldesktops'''
*'''alldesktops:''' window on all desktops (also known as "sticky")
*'''keepabove'''
*'''keepabove:''' keep window above other windows
*'''keepbelow'''
*'''keepbelow:''' keep window below other windows
*'''shade'''
*'''shade:''' shade the window
*'''help'''
*'''help:''' show help information


Each button can have different states. So a button could be hovered, pressed, deactivated and you might want to provide different styles for active and inactive windows. You can use the following element prefix to provide styles for the buttons:  
Each button can have different states. So a button could be hovered, pressed, deactivated and the theme might want to provide different styles for active and inactive windows. The following element prefixes can be used to provide styles for the buttons:  


*'''active:''' normal button for active window
*'''active:''' normal button for active window  
*'''inactive:''' normal button for inactive window
*'''inactive:''' normal button for inactive window  
*'''hover:''' hover state for active window
*'''hover:''' hover state for active window  
*'''hover-inactive:''' hover state for inactive window
*'''hover-inactive:''' hover state for inactive window  
*'''pressed:''' button is pressed
*'''pressed:''' button is pressed  
*'''pressed-inactive:''' pressed inactive button
*'''pressed-inactive:''' pressed inactive button  
*'''deactivated:''' button cannot be clicked, e.g. window cannot be closed
*'''deactivated:''' button cannot be clicked, e.g. window cannot be closed  
*'''deactivated-inactive:''' same for inactive windows
*'''deactivated-inactive:''' same for inactive windows


You have at least to provide the active element. All other elements are optional and the active element is always used as a fallback. If you provide the inactive element, this is used as a fallback for the inactive window. That is, if you provide a hover element, but none for inactive, the inactive window will not have a hover effect. Same is true for pressed and deactivated. Reasonable that means if you provide a deactivated and an inactive element you want to provide a deactivated-inactive element as well.  
At least the active element has to be provided. All other elements are optional and the active element is always used as a fallback. If the theme provides the inactive element, this is used as a fallback for the inactive states. That is, if the theme provides a hover element, but none for inactive, the inactive window will not have a hover effect. Same is true for pressed and deactivated.
 
The buttons ''alldesktops'', ''keepabove'', ''keepbelow'' and ''shade'' are toggle buttons. When clicking on them they will stay in state ''pressed(-inactive)''. By clicking them again they will change back to ''(in)active''.
 
All of those elements have to be put into one svgz file for a button type. The name of the file is the one listed above. E.g. the svg file for the close button has to be named: '''close.svgz'''.


= Configuration file  =
= Configuration file  =


The configuration file is a normal KConfig file. You have to give it the name of your decoration with suffix "rc". So if your theme has the name "deco", your config file will be named "decorc". The following section shows the possible options with their default values.  
The configuration file is a normal KConfig file. You have to give it the name of your decoration with suffix "rc". So if your theme has the name "deco", your config file will be named "decorc". The following section shows the possible options with their default values.  
<pre>[General]
TitleAlignment=Left # vorizontal alignment of window title
TitleVerticalAlignment=Center # vertical alignment of window title
Animation=0 # animation duration in msec when hovering a button and on active/inactive change
ActiveTextColor=0,0,0,255 # title text color of active window
InactiveTextColor=0,0,0,255 # title text color of inactive window
UseTextShadow=false # Draw Shadow behind title text
ActiveTextShadowColor=255,255,255,255 # Shadow text color of active window
InactiveTextShadowColor=255,255,255,255 # Shadow text color of active window
TextShadowOffsetX=0 # Offset of shadow in x direction
TextShadowOffsetY=0 # Offset of shadow in y direction
HaloActive=false # Draw halo behing title of active window (since 4.5)
HaloInactive=false # Draw halo behing title of inactive window (since 4.5)
LeftButtons=MS # buttons in left button group (see http://api.kde.org/4.x-api/kdebase-workspace-apidocs/kwin/lib/html/classKDecorationOptions.html#8ad12d76c93c5f1a12ea07b30f92d2fa)
RightButtons=HIA__X # buttons in right button group
Shadow=true # decoration provides shadows: you have to add padding


[Layout] # uses Layout Manager http://api.kde.org/4.x-api/kdebase-workspace-apidocs/kwin/lib/html/classKCommonDecoration.html#7932f74c28432ad8de232f1c6e8751ce
==General==
BorderLeft=5  
*'''[General]'''
BorderRight=5  
**'''TitleAlignment:''' horizontal alignment of window title (Default: ''Left'')
BorderBottom=5  
**'''TitleVerticalAlignment:''' vertical alignment of window title (Default: ''Center'')
TitleEdgeTop=5  
**'''Animation:''' animation duration in msec when hovering a button and on active/inactive change (Default: ''0'')
TitleEdgeBottom=5  
**'''ActiveTextColor:''' title text color of active window (Default: ''0,0,0,255'')
TitleEdgeLeft=5  
**'''InactiveTextColor:''' title text color of inactive window (Default: ''0,0,0,255'')
TitleEdgeRight=5  
**'''ActiveFocusedTabColor:''' title text color of focused tab of active window (Default: depends on ActiveTextColor)
TitleEdgeTopMaximized=0  
**'''ActiveUnfocusedTabColor:''' title text color of unfocused tab of active window (Default: depends on InactiveTextColor)
TitleEdgeBottomMaximized=0  
**'''InactiveFocusedTabColor:''' title text color of focused tab of inactive window (Default: depends on InactiveTextColor)
TitleEdgeLeftMaximized=0  
**'''InactiveUnfocusedTabColor:''' title text color of unfocused tab of inactive window (Default: depends on InactiveTextColor)
TitleEdgeRightMaximized=0  
**'''UseTextShadow:''' Draw Shadow behind title text (Default: ''false'')
TitleBorderLeft=5  
**'''ActiveTextShadowColor:''' Shadow text color of active window (Default: ''255,255,255,255'')
TitleBorderRight=5  
**'''InactiveTextShadowColor:''' Shadow text color of active window (Default: ''255,255,255,255'')
TitleHeight=20  
**'''TextShadowOffsetX:''' Offset of shadow in x direction (Default: ''0'')
ButtonWidth=20  
**'''TextShadowOffsetY:''' Offset of shadow in y direction (Default: ''0'')
ButtonWidthMinimize=? # optional - default depends on ButtonWidth  
**'''HaloActive:''' Draw halo behing title of active window (Default: ''false''; since 4.5)
ButtonWidthMaximizeRestore=? # optional - default depends on ButtonWidth  
**'''HaloInactive:''' Draw halo behing title of inactive window (Default: ''false'', since 4.5)
ButtonWidthClose=? # optional - default depends on ButtonWidth  
**'''LeftButtons:''' buttons in left button group (Default: see [http://api.kde.org/4.x-api/kdebase-workspace-apidocs/kwin/lib/html/classKDecorationOptions.html#8ad12d76c93c5f1a12ea07b30f92d2fa KWin defaults])
ButtonWidthAlldesktops=? # optional - default depends on ButtonWidth  
**'''RightButtons:''' buttons in right button group
ButtonWidthKeepabove=? # optional - default depends on ButtonWidth  
**'''Shadow:''' decoration provides shadows: padding values have to be added (Default: ''true'')
ButtonWidthKeepbelow=? # optional - default depends on ButtonWidth  
**'''DecorationPositon:''' decoration on top (0), left (1), right (2) or bottom (Default: ''0'')
ButtonWidthShade=? # optional - default depends on ButtonWidth  
==Layout==
ButtonWidthHelp=? # optional - default depends on ButtonWidth  
The layout is based on the [http://api.kde.org/4.x-api/kdebase-workspace-apidocs/kwin/lib/html/classKCommonDecoration.html#7932f74c28432ad8de232f1c6e8751ce layout metric] used by KCommonDecoration. The following diagrams illustrate which configuration value influences which part of the decoration. The available configuration options and their default values are listed below.
ButtonWidthMenu=? # optional - default depends on ButtonWidth  
 
ButtonHeight=20  
===Window===
ButtonSpacing=5  
<pre> ___________________________________________________________________
ButtonMarginTop=0  
|                PaddingTop                                        |
ExplicitButtonSpacer=10  
|  _______________________________________________________________  |
PaddingTop=0 # Padding added to provide shadows  
| |              TitleEdgeTop                                    | |
PaddingBottom=0 # Padding added to provide shadows  
| |_______________________________________________________________| |
PaddingRight=0 # Padding added to provide shadows  
| | TitleEdgeLeft |  [title]                    | TitleEdgeRight | |
PaddingLeft=0 # Padding added to provide shadows</pre>
| |_______________|______________________________|________________| |
| |              TitleEdgeBottom                                  | |
| |_______________________________________________________________| |
| | |                                                          | | |
|PaddingLeft                                            PaddingRight|
| | |                                                          | | |
| |BorderLeft                                         BorderRight| |
| |_|___________________________________________________________|_| |
| |              BorderBottom                                    | |
| |_______________________________________________________________| |
|                PaddingBottom                                      |
|___________________________________________________________________|</pre>
 
===Title===
<pre> __________________________________________________________________________
| ButtonMarginTop            |            |              ButtonMarginTop |
|_____________________________|            |______________________________|
| [Buttons] | TitleBorderLeft | TitleHeight | TitleBorderRight | [Buttons] |
|___________|_________________|_____________|__________________|___________|</pre>
 
===Buttons===
<pre> _____________________________________________________________________________________________
| button | spacing | button | spacing | explicit spacer | spacing | ...    | spacing | button |
|________|_________|________|_________|_________________|_________|________|_________|________|</pre>
 
===Configuration===
*'''[Layout]'''
**'''BorderLeft:''' (Default: ''5'')
**'''BorderRight:''' (Default: ''5'')
**'''BorderBottom:''' (Default: ''5'')
**'''BorderTop:''' Only required for decorations on left, right or bottom (Default: ''0'')
**'''TitleEdgeTop:''' (Default: ''5'')
**'''TitleEdgeBottom:''' (Default: ''5'')
**'''TitleEdgeLeft:''' (Default: ''5'')
**'''TitleEdgeRight:''' (Default: ''5'')
**'''TitleEdgeTopMaximized:''' As above for maximized windows (Default: ''0'')
**'''TitleEdgeBottomMaximized:''' As above for maximized windows (Default: ''0'')
**'''TitleEdgeLeftMaximized:''' As above for maximized windows (Default: ''0'')
**'''TitleEdgeRightMaximized:''' As above for maximized windows (Default: ''0'')
**'''TitleBorderLeft:''' (Default: ''5'')
**'''TitleBorderRight:''' (Default: ''5'')
**'''TitleHeight:''' (Default: ''20'')
**'''ButtonWidth:''' (Default: ''20'')
**'''ButtonWidthMinimize:''' optional - default depends on ButtonWidth  
**'''ButtonWidthMaximizeRestore:''' optional - default depends on ButtonWidth  
**'''ButtonWidthClose:''' optional - default depends on ButtonWidth  
**'''ButtonWidthAlldesktops:''' optional - default depends on ButtonWidth  
**'''ButtonWidthKeepabove:''' optional - default depends on ButtonWidth  
**'''ButtonWidthKeepbelow:''' optional - default depends on ButtonWidth  
**'''ButtonWidthShade:''' optional - default depends on ButtonWidth  
**'''ButtonWidthHelp:''' optional - default depends on ButtonWidth  
**'''ButtonWidthMenu:''' optional - default depends on ButtonWidth  
**'''ButtonHeight:''' (Default: ''20'')
**'''ButtonSpacing:''' (Default: ''5'')
**'''ButtonMarginTop:''' (Default: ''0'')
**'''ExplicitButtonSpacer:''' (Default: ''10'')
**'''PaddingTop:''' Padding added to provide shadows (Default: ''0'')
**'''PaddingBottom:''' Padding added to provide shadows (Default: ''0'')
**'''PaddingRight:''' Padding added to provide shadows (Default: ''0'')
**'''PaddingLeft:''' Padding added to provide shadows (Default: ''0'')
 
{{Box|Notes on Border and Button sizes|
The user can change border and button sizes in the settings dialog. The defaults are the settings specified in the configuration file. The configurable border size influences the right, left and bottom borders, the button size influences both the size of all buttons and the title height.
 
It is important to remember that the buttons have to be scalable to correctly support this feature and that the borders may extend into the center element if the border size is changed.
|100%}}
 
= Decoration Position =
Aurorae can put the decoration handles, that is the title bar including caption and buttons, on any side of the window. By default it is placed at the top of the window. To change this behaviour the setting ''DecorationPosition'' in General settings and ''BorderTop'' in Layout settings have to be specified. Some of the layout options change their meaning. E.g. ''ButtonMarginTop'' becomes a ''"ButtonMarginLeft"'', in general layout settings were only a top exists are changed, if all exists like TitleEdge the meaning is unchanged.
 
{{Box|Window shading|
A shaded window will always have the decoration on the top. So the layout is transformed to be painted on the top again.
|100%}}
 
= Metadata =
The theme must contain a file '''metadata.desktop''' for additional information like name, author, licence, etc. Those data is shown in the about dialog of the theme. The file is mandatory as the engine uses it to locate the theme. The format follows the [http://standards.freedesktop.org/desktop-entry-spec/latest/index.html Desktop Entry Specification] and the following entries are read by Aurorae:
 
* '''[Desktop Entry]'''
** '''Name:''' The name of the theme used in theme selection
** '''Comment:''' A comment for the theme e.g. "Aurorae Theme inspired by Oxygen decoration"
** '''X-KDE-PluginInfo-Author:''' The name of the author used in the about dialog
** '''X-KDE-PluginInfo-Email:''' The author's email address used in the about dialog
** '''X-KDE-PluginInfo-Website:''' The webseite of the theme
** '''X-KDE-PluginInfo-Version:''' Version of the theme
** '''X-KDE-PluginInfo-License:''' The license of the theme e.g. GPL_V2
 
= Packaging  =
= Packaging  =


All theme files (decoration, buttons, metadata.desktop and configuration file) have to be stored in one directory with the name of the theme (this has to be identical to the one used for the config file). You have to create a tar.gz archive from that directory. This archive is the theme, which can be installed in the kcm for window decorations.
All theme files (decoration, buttons, metadata.desktop and configuration file) have to be stored in one directory with the name of the theme (this has to be identical to the one used for the config file). You have to create a tar.gz archive from that directory. This archive is the theme, which can be installed in the kcm for window decorations.

Latest revision as of 09:25, 9 May 2010

Aurorae is a theme engine for KWin window decorations. It uses SVG to render the decoration and buttons and there is a simple config file for configuring the theme details.

This theme engine uses Plasma technology to render the window decoration. Every detail can be themed by the usage of SVG. The theme engine uses Plasma's FrameSvg for the window borders. This is described in more detail in Plasma's Theme description.

The theme consists of one folder containing svgz files for decoration and buttons, one KConfig file for the theme details and one metadata.desktop file which is used for theme name, author information, etc.

The engine supports ARGB decoration which is enabled by default, so that the theme can draw its own shadows. Nevertheless the themes should take care of the case that no desktop effects are used.

Aurorae Designer

With Aurorae Designer there exists a special tool to design Aurorae themes. It is recommended to designers to use this tool. It helps to identify common pitfalls and provides an easy way to change settings and test if the theme contains all required elements.

The code of Aurorae Designer is developed in parallel to Aurorae, so Aurorae Designer might contain features which will be present in a future release of Aurorae, which is bound to the release schedule of the Software Compilation

Window Decoration

The window decoration has to be provided in file decoration.svgz. This svg has to contain all the elements required for a Plasma theme background. The decoration has to use the element prefix decoration.

A different style for inactive windows can be provided in the same svg. The inactive elements must have the element prefix decoration-inactive. The theme engine tests for this prefix and if not provided inactive windows will be rendered with the same style as active windows.

A special decoration for opaque mode, that is when compositing is not active, has to be provided. This opaque decoration is used for generating the window mask. The element prefix is decoration-opaque for active and decoration-opaque-inactive for inactive windows. The mask is generated from the frame svg for active window only.

To summarize the following elements are supported:

  • decoration: This at least has to be provided
  • decoration-inactive: If not provided decoration is used
  • decoration-opaque: Required to generate the window mask. If not provided decoration is used.
  • decoration-opaque-inactive: If not provided either decoration-opaque, decoration-inactive or decoration is used.

Maximized Windows

In order to better support maximized windows there exists a special frame svg called decoration-maximized. In the same way as for the general decoration a version for inactive, opaque and inactive-opaque can be specified. This results in the following names:

  • decoration-maximized
  • decoration-maximized-inactive
  • decoration-maximized-opaque
  • decoration-maximized-opaque-inactive

In all cases only the center element will be used. There is no need to specify borders. Please note that in case of a window with translucent widgets the center element will be stretched to the size of the complete window.

The following fallback strategy is used: if inactive is not present it falls back to the active. If opaque is not present it falls back to the translucent. If none of the maximized elements are present the center element of the decoration is used!

In order to support Fitts' Law all TitleEdge Settings are set to 0. So the buttons will be directly next to the screen edges.

The support for maximized windows exists since KDE SC 4.5.

Window Tabs

Aurorae supports KWin's window tabs for all themes by default. The theme has the possibility to influence the look of the tabs in the decoration by providing additional elements. If the theme does not provide these elements Aurorae paints a line between the tabs with the text color of an unfocused tab.

The following FrameSvg elements are added for tabs:

  • tab-active-focused: element for the focused (selected) tab in the active window
  • tab-active-unfocused: element for all unfocused (unselected) tabs in the active window
  • tab-inactive-focused: element for the focused (selected) tab in inactive windows
  • tab-inactive-unfocused: element for all unfocused (unselected) tabs in inactive windows

A theme has to provide both focused and unfocused elements. The elements for inactive windows are optional. The elements for active windows are used if the inactive are not present. If the inactive are present both focused and unfocused elements are required. All elements may have full border supports.

The support for window tabs exists since KDE SC 4.5.

Inner Borders

Aurorae supports inner borders, that is a border at the margin to the window. While it would be possible to add inner borders directly in the decoration element, the inner borders are to be preferred as those support the configurable border sizes.

For inner borders the decoration svg file can include two additional FrameSvgs: innerborder and innerborder-inactive. If the inactive element is not present the active element is used for inactive windows.

These frames must include the border elements. Only the border elements will be visible, the center element is not visible. For performance reasons the center element should be a simple rect and for support of decoration behind windows it should be completely translucent.

100%

Inner borders are not shown for maximized windows. If a maximized window should show an inner border it is recommeded to directly add it to the maximized element.

Maximized windows and inner borders

The support for inner borders exists since KDE SC 4.5.

Button Groups

An Aurorae decoration may include elements to be painted behind the button groups. This is intended for cases when the buttons share a common background. it should be preferred over custom editing of each button as this will result in a bad visual experience for explicit spacers or if the user changes the order of buttons.

The following elements are supported:

  • buttongroup-left
  • buttongroup-left-inactive
  • buttongroup-right
  • buttongroup-right-inactive

If the inactive element is not provided, the element for active is used for the inactive decoration, too. Left and right are independent and there is no fallback to the other element. For decorations on left or right window side the meaning becomes top and bottom.

Buttons

A svgz file has to be provided for each button. If the theme does not provide a file for a button type the engine will not include that button, so the decoration will miss it. There is no fallback to a default theme. The buttons are rendered using Plasma's FrameSvg just like the decoration. Each button has to provide the "center" element. Borders are not supported

The following buttons are supported:

  • close: closes the window
  • minimize: minimizes the window
  • maximize: maximizes the window; replaces the restore button when not maximized
  • restore: restores the window from maximized state; replaces the maximize button when maximized
  • alldesktops: window on all desktops (also known as "sticky")
  • keepabove: keep window above other windows
  • keepbelow: keep window below other windows
  • shade: shade the window
  • help: show help information

Each button can have different states. So a button could be hovered, pressed, deactivated and the theme might want to provide different styles for active and inactive windows. The following element prefixes can be used to provide styles for the buttons:

  • active: normal button for active window
  • inactive: normal button for inactive window
  • hover: hover state for active window
  • hover-inactive: hover state for inactive window
  • pressed: button is pressed
  • pressed-inactive: pressed inactive button
  • deactivated: button cannot be clicked, e.g. window cannot be closed
  • deactivated-inactive: same for inactive windows

At least the active element has to be provided. All other elements are optional and the active element is always used as a fallback. If the theme provides the inactive element, this is used as a fallback for the inactive states. That is, if the theme provides a hover element, but none for inactive, the inactive window will not have a hover effect. Same is true for pressed and deactivated.

The buttons alldesktops, keepabove, keepbelow and shade are toggle buttons. When clicking on them they will stay in state pressed(-inactive). By clicking them again they will change back to (in)active.

All of those elements have to be put into one svgz file for a button type. The name of the file is the one listed above. E.g. the svg file for the close button has to be named: close.svgz.

Configuration file

The configuration file is a normal KConfig file. You have to give it the name of your decoration with suffix "rc". So if your theme has the name "deco", your config file will be named "decorc". The following section shows the possible options with their default values.

General

  • [General]
    • TitleAlignment: horizontal alignment of window title (Default: Left)
    • TitleVerticalAlignment: vertical alignment of window title (Default: Center)
    • Animation: animation duration in msec when hovering a button and on active/inactive change (Default: 0)
    • ActiveTextColor: title text color of active window (Default: 0,0,0,255)
    • InactiveTextColor: title text color of inactive window (Default: 0,0,0,255)
    • ActiveFocusedTabColor: title text color of focused tab of active window (Default: depends on ActiveTextColor)
    • ActiveUnfocusedTabColor: title text color of unfocused tab of active window (Default: depends on InactiveTextColor)
    • InactiveFocusedTabColor: title text color of focused tab of inactive window (Default: depends on InactiveTextColor)
    • InactiveUnfocusedTabColor: title text color of unfocused tab of inactive window (Default: depends on InactiveTextColor)
    • UseTextShadow: Draw Shadow behind title text (Default: false)
    • ActiveTextShadowColor: Shadow text color of active window (Default: 255,255,255,255)
    • InactiveTextShadowColor: Shadow text color of active window (Default: 255,255,255,255)
    • TextShadowOffsetX: Offset of shadow in x direction (Default: 0)
    • TextShadowOffsetY: Offset of shadow in y direction (Default: 0)
    • HaloActive: Draw halo behing title of active window (Default: false; since 4.5)
    • HaloInactive: Draw halo behing title of inactive window (Default: false, since 4.5)
    • LeftButtons: buttons in left button group (Default: see KWin defaults)
    • RightButtons: buttons in right button group
    • Shadow: decoration provides shadows: padding values have to be added (Default: true)
    • DecorationPositon: decoration on top (0), left (1), right (2) or bottom (Default: 0)

Layout

The layout is based on the layout metric used by KCommonDecoration. The following diagrams illustrate which configuration value influences which part of the decoration. The available configuration options and their default values are listed below.

Window

 ___________________________________________________________________
|                 PaddingTop                                        |
|  _______________________________________________________________  |
| |              TitleEdgeTop                                     | |
| |_______________________________________________________________| |
| | TitleEdgeLeft |   [title]                    | TitleEdgeRight | |
| |_______________|______________________________|________________| |
| |              TitleEdgeBottom                                  | |
| |_______________________________________________________________| |
| | |                                                           | | |
|PaddingLeft                                            PaddingRight|
| | |                                                           | | |
| |BorderLeft                                          BorderRight| |
| |_|___________________________________________________________|_| |
| |              BorderBottom                                     | |
| |_______________________________________________________________| |
|                PaddingBottom                                      |
|___________________________________________________________________|

Title

 __________________________________________________________________________
| ButtonMarginTop             |             |              ButtonMarginTop |
|_____________________________|             |______________________________|
| [Buttons] | TitleBorderLeft | TitleHeight | TitleBorderRight | [Buttons] |
|___________|_________________|_____________|__________________|___________|

Buttons

 _____________________________________________________________________________________________
| button | spacing | button | spacing | explicit spacer | spacing | ...    | spacing | button |
|________|_________|________|_________|_________________|_________|________|_________|________|

Configuration

  • [Layout]
    • BorderLeft: (Default: 5)
    • BorderRight: (Default: 5)
    • BorderBottom: (Default: 5)
    • BorderTop: Only required for decorations on left, right or bottom (Default: 0)
    • TitleEdgeTop: (Default: 5)
    • TitleEdgeBottom: (Default: 5)
    • TitleEdgeLeft: (Default: 5)
    • TitleEdgeRight: (Default: 5)
    • TitleEdgeTopMaximized: As above for maximized windows (Default: 0)
    • TitleEdgeBottomMaximized: As above for maximized windows (Default: 0)
    • TitleEdgeLeftMaximized: As above for maximized windows (Default: 0)
    • TitleEdgeRightMaximized: As above for maximized windows (Default: 0)
    • TitleBorderLeft: (Default: 5)
    • TitleBorderRight: (Default: 5)
    • TitleHeight: (Default: 20)
    • ButtonWidth: (Default: 20)
    • ButtonWidthMinimize: optional - default depends on ButtonWidth
    • ButtonWidthMaximizeRestore: optional - default depends on ButtonWidth
    • ButtonWidthClose: optional - default depends on ButtonWidth
    • ButtonWidthAlldesktops: optional - default depends on ButtonWidth
    • ButtonWidthKeepabove: optional - default depends on ButtonWidth
    • ButtonWidthKeepbelow: optional - default depends on ButtonWidth
    • ButtonWidthShade: optional - default depends on ButtonWidth
    • ButtonWidthHelp: optional - default depends on ButtonWidth
    • ButtonWidthMenu: optional - default depends on ButtonWidth
    • ButtonHeight: (Default: 20)
    • ButtonSpacing: (Default: 5)
    • ButtonMarginTop: (Default: 0)
    • ExplicitButtonSpacer: (Default: 10)
    • PaddingTop: Padding added to provide shadows (Default: 0)
    • PaddingBottom: Padding added to provide shadows (Default: 0)
    • PaddingRight: Padding added to provide shadows (Default: 0)
    • PaddingLeft: Padding added to provide shadows (Default: 0)
100%

The user can change border and button sizes in the settings dialog. The defaults are the settings specified in the configuration file. The configurable border size influences the right, left and bottom borders, the button size influences both the size of all buttons and the title height.

It is important to remember that the buttons have to be scalable to correctly support this feature and that the borders may extend into the center element if the border size is changed.

Notes on Border and Button sizes


Decoration Position

Aurorae can put the decoration handles, that is the title bar including caption and buttons, on any side of the window. By default it is placed at the top of the window. To change this behaviour the setting DecorationPosition in General settings and BorderTop in Layout settings have to be specified. Some of the layout options change their meaning. E.g. ButtonMarginTop becomes a "ButtonMarginLeft", in general layout settings were only a top exists are changed, if all exists like TitleEdge the meaning is unchanged.

100%

A shaded window will always have the decoration on the top. So the layout is transformed to be painted on the top again.

Window shading


Metadata

The theme must contain a file metadata.desktop for additional information like name, author, licence, etc. Those data is shown in the about dialog of the theme. The file is mandatory as the engine uses it to locate the theme. The format follows the Desktop Entry Specification and the following entries are read by Aurorae:

  • [Desktop Entry]
    • Name: The name of the theme used in theme selection
    • Comment: A comment for the theme e.g. "Aurorae Theme inspired by Oxygen decoration"
    • X-KDE-PluginInfo-Author: The name of the author used in the about dialog
    • X-KDE-PluginInfo-Email: The author's email address used in the about dialog
    • X-KDE-PluginInfo-Website: The webseite of the theme
    • X-KDE-PluginInfo-Version: Version of the theme
    • X-KDE-PluginInfo-License: The license of the theme e.g. GPL_V2

Packaging

All theme files (decoration, buttons, metadata.desktop and configuration file) have to be stored in one directory with the name of the theme (this has to be identical to the one used for the config file). You have to create a tar.gz archive from that directory. This archive is the theme, which can be installed in the kcm for window decorations.

Retrieved from "https://techbase.kde.org/index.php?title=User:Mgraesslin/Aurorae&oldid=51072"