Unity window button theme specification?

Question

I'm trying to track down the specification of Unity window button themes. By this I mean the specification specific to Unity, (/usr/share/themes/Radiance/unity), not the gtk or metacity specifications (/usr/share/themes/Radiance/metacity-1 or /usr/share/themes/Radiance/gtk-x.0).

The only themes I've found that appear to use this specification are the Radiance and Ambiance ones (in package light-themes).

Upon looking in /usr/share/themes/(Ambiance|Radiance)/unity, I see the images:

• role.png
• role_focusstate_state.png

where

• role is one of close, maximize, minimize or unmaximize;
• focusstate is focused or unfocused;
• state is normal, prelight or pressed.

Is there some specification on how to create a unity window theme? Which of the above files is required at minimum? when each is used?

(For example, is the close.png ever used if close_[focusstate]_[state].png exists for all focus states and states already? If so, when? If not, why is close.png included with Ambiance/Radiance, which appear to cover all focus states and all states already?)

Answer 1

I've done a bit more digging, and I suspect that:

• unity uses the metacity theme (metacity-1 subfolder) for all window decorations;
• unity uses the unity subfolder to draw window buttons in the top unity panel only (when a window is maximized and the titlebar has been hidden (?))

(I don't currently have Unity available to me to test).

The relevant bug: https://bugs.launchpad.net/unity/+bug/740232

In particular, comment 22:

This has been fixed. Check /usr/share/themes/ambiance/unity, you'll find buttons there which are loaded into panel. So, yes Unity window control buttons are now themable.

The relevant code (3/Jun/2013): http://bazaar.launchpad.net/~unity-team/unity/trunk/view/3355/unity-shared/PanelStyle.cpp#L197

I do not believe there is any documentation.

However, reading the relevant code (above) it seems like

• The window button types are CLOSE, MINIMIZE, UNMAXIMIZE, MAXIMIZE
• The window button states are NORMAL, PRELIGHT, PRESSED, DISABLED, UNFOCUSED, UNFOCUSED_PRELIGHT, UNFOCUSED_PRESSED

These seem much the same as metacity.

To find the image corresponding to the button with type type and state state, we look up unity/<type_><state_>.png, where:

• type_ is:
  • 'close' for type CLOSE;
  • 'minimize' for type MINIMIZE;
  • 'maximize' for type MAXIMIZE;
  • 'unmaximize' for type UNMAXIMIZE.
• state_ is:
  • '' (nothing) for state NORMAL (a button on the active window);
  • '_focused_prelight' for state PRELIGHT (a button on the active window that is being hovered over);
  • '_focused_pressed' for state PRESSED (a button on the active window that is being pressed);
  • '_unfocused' for state DISABLED; (??)
  • '_unfocused' for state UNFOCUSED (a button on an unfocused window);
  • '_unfocused_prelight' for state UNFOCUSED_PRELIGHT(a button on an unfocused window that is being hovered over);
  • '_unfocused_pressed' for state UNFOCUSED_PRESSED (a button on an unfocused window that is being pressed).

Hence note that of the images in the unity subfolder of (say) Ambiance, <role>_focused_normal.png is not used, even though it's provided in the package (??).

If the image for a particular (type, state) is not found, it looks like some sort of default button is drawn (rather than using one of the existing images).