User:Mgraesslin/Aurorae: Difference between revisions

    From KDE TechBase
    (Metadata.desktop)
    m (maximized windows since 4.5)
    Line 35: Line 35:


    In order to support Fitts' Law all TitleEdge Settings are set to 0. So the buttons will be directly next to the screen edges.
    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.


    = Buttons  =
    = Buttons  =

    Revision as of 16:51, 16 March 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.

    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.

    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
    • 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

    • [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)
      • 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)

    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)
      • 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)

    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.