Difference between revisions of "Theming HowTo"
Galeandrews (talk | contribs) (add link for GIMP, fix a typo) |
m |
||
| (21 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
| − | {{ | + | {{deprecated|https://github.com/audacity/audacity/wiki/Creating-custom-themes}} |
| + | {{Advice| | ||
| + | '''''Custom''''' themes (user defined themes) are possible but NOT officially supported in Audacity 2.2.0. Please consider this page, and theme support in Audacity, as a "work in progress".}} | ||
| + | {{intro|Customised Theming is a feature of Audacity 2.2.0 and later and also some earlier experimental builds of Audacity. This page ''outlines'' how to use it as it currently exists and how to add images and colors in its current form. Note that the layout of the ImageCache is likely to change in future.|2=}} | ||
| − | == | + | ==Image Cache== |
| + | The image cache is shown on the left and the themed Audacity it produces is shown on the right.<br><br><br> | ||
| + | |||
| + | {| | ||
| + | |- | ||
| + | |[[File:LightImageCache.png]] | ||
| + | |[[File:LightScreenshot.png]] | ||
| + | |} | ||
| + | |||
| + | |||
| + | <br><br>You can download the theme's .png file and tooltips for it (as an htm file): [[Media:Theme.zip|Theme.zip]]. But beware - those examples were made a long time ago. Ask active developers for an update. | ||
| + | |||
| + | * The '''icons''' are reasonably self explanatory. | ||
| + | :: You can edit the icons and see the changes in Audacity. Note that a few images like grabbers are are not in the cache and are drawn by Audacity itself. | ||
| + | * The '''colors''' are in the boxes at the foot of the image. | ||
| + | :: The colors are a bit disorganized, so modifying them is fiddly. If you open the html files, then there is a tooltip for each color and image. Using GIMP or another image editor, you can for example give the entire image a green, blue or red cast, or invert the colors. | ||
| + | :: The first three blues control the wave color. | ||
| + | |||
| + | Create a folder called "Theme" (without the quotes) in [https://manual.audacityteam.org/man/preferences.html#stored Audacity's folder for application data] then place your modified .png file in there. Your modified file must be named ImageCache.png (otherwise it won't be found by Audacity. | ||
| + | |||
| + | |||
| + | In Audacity, in {{menu|Edit->Preferences->Interface}}, choose "Custom". If you have the file correctly named and 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. | ||
| + | |||
| + | |||
| + | ''If you are just modifying the theme you do not need to read on for details of the theme in the source code.'' | ||
| + | |||
| + | {{ednote|1= These are old instructions about converting old themes to newer ones. | ||
| + | |||
| + | ==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=== | ||
| + | {{ednote|'''Peter 10Apr17:''' I left the code-looking stuff here with "COLOUR ..." and wxColour ..." as I was unsure what to do about these, unsure about what is the correct form - otherwise I changed "colour" to the US "color" throughout. <br> | ||
| + | *'''James 10Apr17:''' Yes, leave as is in code - or the code won't work. | ||
| + | **'''Peter 10Apr17:''' that was my uneducated guess ;-)) }} | ||
Add these in AllThemeResources.h with a line like: | Add these in AllThemeResources.h with a line like: | ||
| Line 10: | Line 63: | ||
</pre> | </pre> | ||
| − | + | 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. | |
| − | * Or just add a | + | * Either add at the end of the colours |
| + | * Or just add a color directly using <code>wxColour( 140,60,190)</code> where you need it. When theming is revised, we'll fix these cases up too. | ||
| − | ==Images== | + | ===Images=== |
With the current scheme, adding new images is way more byzantinely complex than it should be. | With the current scheme, adding new images is way more byzantinely complex than it should be. | ||
| Line 20: | Line 74: | ||
* 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. | * 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 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. |
| + | |||
| + | You will need to define EXPERIMENTAL_THEME_PREFS in Experimental.h to get the extra theme prefs page in preferences. | ||
| + | |||
| + | 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: | To add a new image add a line like this in AllThemeResources.h: | ||
| Line 28: | Line 86: | ||
</pre> | </pre> | ||
| − | 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 | + | 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. | 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. | ||
<blockquote> | <blockquote> | ||
| − | ==Storing the Image in Source== | + | ===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 | + | Use the button 'Output Sourcery' to make a 'C' version of the data file. The file is called 'ThemeAsCeeCode.h'. You may be replacing one of our existing theme caches, such as HiContrastThemeAsCeeCode.h, or, if you are building a new theme into audacity, updating Theme.cpp so that it adds the new option and includes your new .h file. |
| + | |||
</blockquote> | </blockquote> | ||
| − | ==Gotchas== | + | ===Gotchas=== |
| − | ===Transparency=== | + | ====Transparency==== |
Use {{external|[http://www.gimp.org/Gimp GIMP]}}. Some other image editors do not support Alpha, and for button images you need it. | Use {{external|[http://www.gimp.org/Gimp GIMP]}}. Some other image editors do not support Alpha, and for button images you need it. | ||
| − | ===Breaking Existing Images=== | + | ====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. | 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. | ||
| − | [[Category:For Developers]] | + | [[Category:For Developers]][[Category:Graphics]] |
Latest revision as of 15:46, 28 November 2022
|
This page has been deprecated. Newer information can be found here: https://github.com/audacity/audacity/wiki/Creating-custom-themes |
| The information on this page are likely out-of-date and will not be updated in the forseeable future. It may be removed at any time. |
|
|
Custom themes (user defined themes) are possible but NOT officially supported in Audacity 2.2.0. Please consider this page, and theme support in Audacity, as a "work in progress". |
| Customised Theming is a feature of Audacity 2.2.0 and later and also some earlier experimental builds of Audacity. This page outlines how to use it as it currently exists and how to add images and colors in its current form. Note that the layout of the ImageCache is likely to change in future.
|
Contents
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. But beware - those examples were made a long time ago. Ask active developers for an update.
- The icons are reasonably self explanatory.
- You can edit the icons and see the changes in Audacity. Note that a few images like grabbers are are not in the cache and are drawn by Audacity itself.
- The colors are in the boxes at the foot of the image.
- The colors are a bit disorganized, so modifying them is fiddly. If you open the html files, then there is a tooltip for each color and image. Using GIMP or another image editor, you can for example give the entire image a green, blue or red cast, or invert the colors.
- 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. Your modified file must be named ImageCache.png (otherwise it won't be found by Audacity.
In Audacity, in , choose "Custom". If you have the file correctly named and 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.
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
In the code
Developers wanting to add new images and colors rather than change existing ones can do so in Audacity source code.
Colors
- James 10Apr17: Yes, leave as is in code - or the code won't work.
- Peter 10Apr17: that was my uneducated guess ;-))
Add these in AllThemeResources.h with a line like:
DEFINE_COLOUR( clrHzPlot, wxColour(140, 60, 190), wxT("HzPlot") );
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 of the colours
- 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.
You will need to define EXPERIMENTAL_THEME_PREFS in Experimental.h to get the extra theme prefs page in preferences.
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 may be replacing one of our existing theme caches, such as HiContrastThemeAsCeeCode.h, or, if you are building a new theme into audacity, updating Theme.cpp so that it adds the new option and includes your new .h file.
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.
