Revision 1 as of 2007-09-06 14:32:38

Clear message
  • Immutable Page
  • Info
  • Attachments

The Emerald Window Decorator is a custom window decorator shipped with Compiz Fusion that allows for theming and full composite window decorations with the use of engines. Emerald allows for all sorts of different configurations and layouts of buttons, look, title bars and frames. Emerald Window Decorator is completely independent of any desktop, and you specify your own themes to use for it. The [:Plugins/Decoration:Decoration] plugin must be enabled in order for Emerald Window Decorator to function.

Using Emerald

When launched, Emerald will replace your current window decorator with itself. The default theme is 'Beryl_Default (Beryl Red)', however this will probably change soon. To launch Emerald, use

emerald --replace

To choose a different theme, you will need to use the Emerald Theme Manger, see [:EmeraldThemeManager:Emerald Theme Manager]

Global Configuration

In [:EmeraldThemeManager:Emerald Theme Manager], under Emerald Settings, you can change settings which will apply to emerald itself, and will not vary as you use different themes and engines.

  • Toggling Show Tooltips for buttons shows a tooltip when you hovering over a button on the titlebar, describing what the button does, e.g. Close Window

  • Toggling Use Decoration Cropping will stretch the titlebar as it is being resized, then redraw as you have finished resizing.

  • Toggling Use Button Fade will make the highlight on the buttons fade in and out as you hover on and off them.

  • Toggling Use Button Fade Pulse will make the highlight on the buttons constantly fade in and out as you are hovering over them, giving a 'pulse' effect

  • Button Fade Total Duration controls how long it will take in milliseconds for the buttons to fade in and out

  • Button Fade Step Duration controls how much time there is between each redraw of the fade there is. A high value will produce a smooth fade and a low value will produce a jerky fade

  • Button Pulse Wait Duration controls how much time in milliseconds before the button starts 'pulsing' when you hover over it

  • Titlebar Double-Click Action defines what action takes place when you double-click the titlebar out of the follow

    • Maximise and Restore a window
    • Shade and Unshade a window
    • Minimize a window
  • Button Hover Cursordefines which cursor is used when you hover over a button, a pointing-finger, or the arrow cursor

  • Compiz Decoration Blur Type allows you to choose from the following what part of the decoration is blurred when the [:Plugins/Blur:Blur] plugin is enabled.

    • Only the titlebar
    • The titlebar and the frame

Theme Specs

File Structure

Emerald themes are packaged in the gunzipped tar format and have the extension .emerald appended. Their file structure follows the following format

  • ThemeName

    • buttons.close.png
    • buttons.max.png
    • buttons.min.png
    • buttons.restore.png
    • buttons.stick.png
    • buttons.unstick.png
    • buttons.glow1.png (For Active Windows)
    • buttons.glow2.png (For Inactive Windows)
    • buttons.shade.png
    • buttons.unshade.png
    • buttons.above.png
    • buttons.unabove.png
    • theme.ini
    • theme.screenshot.png

This, of course, excepts the the pixmap engine which needs a few other files too.


Buttons files contain pixmaps which in turn contain the buttons. They are specially structured.

The first 3 buttons make up the button that will be the button for the active window. The 3 buttons are essentially the 3 'stages' of the fade animation, so you can make your buttons animate slightly when they are hovered over. The animation will repeat itself if Use Button Fade Pulse is enabled. The last 3 buttons are used for inactive windows.

==== Theme.INI Structure =====

The theme.ini file contains a certain structure. It reads like this:

  • [theme] : This contains information about your theme such as the suggested widget theme, the version, description and creator. The user will see this information

  • [titlebar] : This contains settings for the titlebar layout, such as the default object layout, titlebar height, font and text color

  • [buttons] : This contains settings for the buttons, such as the layout and whether to use halo / glow

  • [borders] : This contains settings about the size of the borders

  • [shadow] : This contains settings about the size and shape of the shadow, how transparent it is and what color it is

  • [engine] : This contains a string mentioning what engine will be in use

  • [engine_in_use] : This contains engine specific settings, such as what color to use for the titlebars and frames.


Emerald Window Decorator uses Engines to do most of the work in theming the window borders. Below is a list of engines, a description of their settings and a description of the engine itself.

_Note that this section still has yet to be written_

Legacy Engine

TruGlass Engine

Line Engine

VRunner Engine

Oxygen Engine

Zootreeves Engine

Pixmap Engine