Introduction

Audacity is Themable. That means the images, colours and fonts can be changed at run time, and pre-built combinations can be loaded when the program starts.

A sample of the saved ImageCache is shown here, hover over any part to see its name (if there is no image shown here, you will need to add the image ImageCache.png into the html directory):

ThemeBase provides most of the implementation of Themes. It is destined for Migration of Generic Code To wxWidgets. Theme is Audacity's variant of a class derived from ThemeBase. It contains the Audacity specific list of icons and images and overloads for the required virtual functions. A singleton instance, theTheme is created by Audacity.

Another class, ThemePrefs, provides the GUI for loading and saving theme information.

The Different Ways Theme Images are Stored

Audacity includes a system for loading and saving different icons and colours.

There are three formats:

Images stored combined into one PNG file.
Images stored as individual PNG files.
The PNG file as a file of comma separated numbers.

The first form is the one usually used. It is useful for designers making systematic changes of the images, particularly systematic colour changes. It is also convenient for archives containing many themes and for sharing of themes. However it is inconvenient when there are additions to and removals from the image set used in Audacity, as can happen between versions. A combined PNG made for one version of Audacity may no longer be suitable for the next version.

Storing as individual images solves that problem and makes it easier for a designer to change just one image. In SVN we check in the individual images.

The third form allows Audacity to store the combined PNG in 'C' format for use in the exe. It is only ever used by developers. It is this third form that provides the built in defaults in Audacity.

Attention: The button to save a theme in the 'C' format is only provided in debug builds.

How Audacity Chooses Which Version Of The images To Use? <br>

At the time of writing this document, Audacity also has a deprecated system for its images where they initially start out with contents determined by XPMs built into the program.

The current algorithm for determining which image to use is:

IF loading the theme at start up is disabled, use the XPM defaults.
ELSE if the image cache is available THEN use it.
ELSE use the built in ' ThemeAsCeeCode.h ' defaults.

This is handled in function ThemeBase::LoadThemeAtStartUp(). Once the deprecated XPMs have been removed, we will switch over to using the built in 'ThemeAsCeeCode.h' defaults where we currently use the XPM defaults.

Changing The Colour Scheme

To change the colour scheme:

Run the program and use the 'Save Theme' button on the ThemePrefs panel.
This saves all the images as a single .png file, ImageCache.png.
Use the GIMP to modify the colours in ImageCache.png. Using the colour balance feature provides a nice way to make a systematic change. Note in particular near the end of the image a row of small squares. These are used for colours such as the colours in the waveform.
Use the 'Load Theme' button on the ThemePrefs panel to accept the changes.
Check the 'Load Theme At Startup' check box so that the theme will be loaded next time you start Audacity.

Adding New Images

To add a new image to Audacity, add a blank place holder for the image into the program like so:

IMAGE( bmpSomeNewImage, wxBitmap(64,64), wxT("SomeNewImage") )

wxT

wxT("CloseDown"))

This reserves a 64 x 64 pixel bitmap. You can now refer to it from within the program using bmpSomeNewImage. If you add images on to the end of the list you will generally have the least problems with compatibility of versions.
If you are adding many images, the most efficient packing of images occurs when the images are added in tallest-first order since Audacity starts a new row whenever the height increases.

Having defined the new image, follow these steps:

Compile Audacity in debug mode.
Run the program and use the 'Save Components' button on the ThemePrefs panel. This saves all the images as .png files, including a blank image for your new image.
Replace that .png file with the image you want to use.
Press the 'Load Components' button on the ThemPrefs panel.
Press the 'Save Theme' button on the ThemePrefs panel. You now have a composite .png file that includes your image.
Press the 'Output Sourcery' button on the Theme prefs panel. This generates a new data file, ThemeAsCeeCode.h, which can be used for defaults.
Replace the existing ThemeAsCeeCode.h in the Audacity source code and recompile. You should now have a version of Audacity with the new .png as a built in default.

Audacity will now be using the image.

When you come to check in the updated code into SVN, including ThemeAsCeeCode.h, remember to also add your new .png image into SVN too.

Rescuing Default Images

It is possible to completely screw up the built in default images through using an incorrect ThemeAsCeeCode.h. A correct ThemeAsCeeCode.h can be regenerated as follows:

Retrieve a correct set of images from SVN and place them in the components directory used by Audacity.
Compile Audacity in debug mode.
Use ThemePrefs 'Load Components' to load the correct set of images.
Press the 'Output Sourcery' button on the Theme prefs panel. This generates a corrected ThemeAsCeeCode.h using the images you just loaded.
Replace the existing ThemeAsCeeCode.h in the Audacity source code and recompile.