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