Difference between revisions of "Theming HowTo"

Revision as of 16:34, 21 April 2017

Image Cache

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

You can download the theme's .png file and tooltips for it (as an htm file): Theme.zip.

• 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 colors are in the boxes at the foot of the image.

The colors 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 colors, using GIMP and see the effect. The first three blues control the wave color.

Create a folder called "Theme" (without the quotes) in Audacity's folder for application data then place your modified .png file in there.

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.

Converting Old Themes

• Choose a version of Audacity the theme worked in.

Compile that Audacity with debug and EXPERIMENTAL_THEMING enabled.

Load Theme Cache, i.e. load ImageCache.png

Save Files i.e. save as separate images.

• Switch to 2.2.0 (also compiled with EXPERIMENTAL_THEMING enabled.)

Load Files i.e. load from separate images.

Save Theme Cache, i.e. save ImageCache.png

You'll then have work to do on colors and new icons on the updated ImageCache.png, but won't be starting from scratch.

In the code

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

Colors

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

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.