Theming HowTo

From Audacity Wiki
Revision as of 16:07, 9 April 2017 by James (talk | contribs) (Show the theme it produces.)
Jump to: navigation, search
Customised Theming is a feature in experimental builds of Audacity. It is due for substantial change. This page outlines how to use it as it currently exists and how to add images and colors in its current form.

Image Cache

The image cache is shown on the left and the themed Audacity it produces is shown on the right.

{ |- |LightImageCache.png |LightScreenshot.png |}

You can download the theme file and tooltips for it (as an html file) from

  • The icons are reasonably self explanatory.
You can edit the icons and see the changes in Audacity. Note that some images like grabbers are in the ImageCache but not used. Grabbers are drawn by Audacity itself. The pin/unpinned images are present several times for historical reasons.
  • The colours are in the boxes at the foot of the image.
The colours are a bit disorganised, so modifying them is fiddly. You can though give the entire image a green, blue or red cast, or invert the colours, using GIMP and see the effect. The first three blues control the wave colour.

On Windows, place the modified file at:


Note the name does not include 'Light'. In Audacity in Edit->Preferences->Interface choose custom. If you have the file in the correct place each time you click on the preferences dialog OK button the theme will reload from ImageCache.png. It will also be loaded when Audacity starts up.

The Audacity logo in the file is NOT used, and that is intentional.

If you are just modifying the theme you do not need to read on for details of the theme in the source code.

In the code

Developers wanting to add new images and colours rather than change existing ones can do so in Audacity source code.


Add these in AllThemeResources.h with a line like:

   DEFINE_COLOUR( clrHzPlot,               wxColour(140, 60, 190),    wxT("HzPlot") );

Under Windows you may get funny results for existing colors if you add this in the middle of the existing blocks of colors rather than at the end. Either add at the end, or do a clean rebuild. MSVC gets confused by some of the header files like 'macromagic.h' and with precompiled headers turned on doesn't realise it needs to do more recompilation.

  • Or just add a color directly using wxColour( 140,60,190) where you need it. When theming is revised, we'll fix these cases up too.


With the current scheme, adding new images is way more byzantinely complex than it should be.

  • If you can get away with using an inline XPM image instead, that could be easier than trying to use theming. If you do that, when theming is revised we'll fix these cases up then too.

To add an image using theming, before you add an image, try using the theme prefs tab to get a sense of how theme images work. Do this in a debug build. Use 'Save Theme Cache' to save a single png composite of all images. The dialog tells you where it was saved. Have a look at it with an image editor, and with a browser, using the web page that accompanies it. The browser way of examining it gives you tooltip names for the component images. Now also try 'Save Files' to save lots of individual files.

To add a new image add a line like this in AllThemeResources.h:

   DEFINE_IMAGE( bmpUndo, wxImage( 26, 24 ), wxT("Undo"));

And use code that is like existing code for bmpUndo when you need the image. You'll find that the image comes out black. To fix this, do 'Save Files' for the modified application. You'll find there is a new image .png file that is black which has the name of your image. Replace this with what you want. Now do 'Load Files' and 'Save Image Cache'. Check that your new image appears where you'd expect it to in the composite theme cache.

If you now tick 'Load Theme Cache at Startup' the new theme cache will be used from here on. You can go on developing like this until you're happy with the new functionality.

Storing the Image in Source

Use the button 'Output Sourcery' to make a 'C' version of the data file. The file is called 'ThemeAsCeeCode.h'. You could just replace the version in Audacity with this one, and that would work. However, (as of June 24 2008), we have two versions of the theme in the one file, so to preserve the alternative version, which is #ifdeffed out, you need to cut and paste the new values over the existing ones.



Use GIMP . Some other image editors do not support Alpha, and for button images you need it.

Breaking Existing Images

The ThemeCache uses a 'flow' layout for the images, rather like wordwrap. If your new images are added on the end of an existing line, all is well. If however they are too tall for the existing line or cause a new line because they fill up the line, all images after that point will be wrong. Do check the layout of the Imagecache image to ensure the layout is working as intended.