75df855adf
Furthermore the SVG is only scaled to the region of the maximzed title rect and not to the complete size of the window. Theme description updated with a complete section on maximized windows. Yeah I know I should move that to techbase. FEATURE: 224226 svn path=/trunk/KDE/kdebase/workspace/; revision=1100406
163 lines
8.2 KiB
Text
163 lines
8.2 KiB
Text
DESCRIPTION OF AURORAE
|
|
======================
|
|
|
|
Aurorae is a theme engine for KWin window decorations. It is built against the unstable API of KWin
|
|
in KDE 4.3. Aurorae 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 technologie 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 techbase:
|
|
http://techbase.kde.org/Projects/Plasma/Theme#Backgrounds
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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".
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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:
|
|
* 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. You have the possibility to overwrite these settins (see below).
|
|
|
|
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
|
|
|
|
You can provide the following buttons:
|
|
* close
|
|
* minimize
|
|
* maximize
|
|
* restore
|
|
* alldesktops
|
|
* keepabove
|
|
* keepbelow
|
|
* shade
|
|
* resize
|
|
* help
|
|
|
|
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:
|
|
* 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)
|
|
|
|
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.
|
|
|
|
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]
|
|
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 (see http://api.kde.org/4.x-api/kdebase-workspace-apidocs/kwin/lib/html/classKCommonDecoration.html#7932f74c28432ad8de232f1c6e8751ce)
|
|
BorderLeft=5
|
|
BorderRight=5
|
|
BorderBottom=5
|
|
TitleEdgeTop=5
|
|
TitleEdgeBottom=5
|
|
TitleEdgeLeft=5
|
|
TitleEdgeRight=5
|
|
TitleEdgeTopMaximized=0
|
|
TitleEdgeBottomMaximized=0
|
|
TitleEdgeLeftMaximized=0
|
|
TitleEdgeRightMaximized=0
|
|
TitleBorderLeft=5
|
|
TitleBorderRight=5
|
|
TitleHeight=20
|
|
ButtonWidth=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=20
|
|
ButtonSpacing=5
|
|
ButtonMarginTop=0
|
|
ExplicitButtonSpacer=10
|
|
PaddingTop=0 # Padding added to provide shadows
|
|
PaddingBottom=0 # Padding added to provide shadows
|
|
PaddingRight=0 # Padding added to provide shadows
|
|
PaddingLeft=0 # Padding added to provide shadows
|
|
|
|
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.
|