Theming HowTo

Theming is a feature in experimental builds of Audacity. It is due for substantial change. This page outlines how to add images and colors in its current form.

Colours

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.

Images

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 program. 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.

Gotchas

Transparency

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.