Unusual Header Files

From Audacity Wiki
Jump to: navigation, search
Most header files (.h files) in Audacity source code contain class declarations for classes which are defined in the corresponding C++ files (.cpp). This page describes several unusual header files that do not fit this pattern.


AudacityHeaders.h

This file is for 'precompiled headers' . This is a technique for speeding up compilation. Many source files are using the same wxWidgets resources and key Audacity features. Most modern C compilers can compile faster in this case, provided they have exactly the same header files included in exactly the same order.

AudacityHeaders.h has the header files we want in the right order. Our build system forces it to be included as the first include file in all main Audacity .cpp source files. As a result these .cpp files build more quickly.

  • Windows Specific Details: The relevant MSVC setting is in Project->Audacity_Properties->Configuration_Properties->C/C++->Advanced->Force_Includes, which is set to AudacityHeaders.h. This ensures that the main Audacity .cpp files include this include. In addition in Project->Audacity_Properties->Configuration_Properties->C/C++->Precompiled_Headers we use the precompiled header file (.pch)file, except for the special source file, AudacityHeaders.cpp where we create it.
  • Linux Specific Details:


ThemeAsCeeCode.h

This is an auto-generated binary file containing an encoded .png image file for theming. This is necessary to build the .png into the source code. The current version contains two variants of the .png file, selected by a #define.


AllThemeResources.h

This file declares shared theme resources such as images and colors. Files which need a themable color or image should include this file. In addition Theme.cpp includes this include file in a different way (making use of the MacroMagic.h header file to modify several #defines). In this mode AllThemeResources.h provides declaration of the theme images and colors, though the actual values of the images and colors come from the ThemeAsCeeCode.h file.


Warning icon Add Images and Colours the Old Way for Now: The AllThemeResources.h theming system is under review. It suffers from several limitations. Images are of a fixed size. Features like 'gradient fills' aren't represented. It's not easy to add to either. It's likely theming will be upgraded to a system based on XRS (wxWidgets XRC with zip compression and binary encoding into a .h file) and using a tool such as wxFormBuilder to edit the themes. That requires some extension to wxFormBuilder. Until such time, new colors and new xpm images can be added in the 'old way'. When the new theming system is developed existing xpms and colors will be added to it.


Experimental.h

This file is used to enable and disable experimental features which are under development.

Each new experimental feature has an associated #define, e.g. #define EXPERIMENTAL_SMART_HELP. When enabled the feature is present in Audacity. When the #define is commented out, the feature should be absent.

Experimental.h was started as a response to the cost of maintaining diverging versions of Audacity.

An extract from an Experimental.h:

// This experimental feature is a notebook that adds
// a tabbed divider to the project.
#define EXPERIMENTAL_NOTEBOOK

Guidelines for using Experimental.h

  • Don't delete #define SPECIAL_THINGY from Experimental.h while an #ifdef SPECIAL_THINGY still exists in the code somewhere. Instead just comment it out. Otherwise things like EXPERIMENTAL_FTP could get left hanging, forgotten, in the code.
  • If you add #define SPECIAL_THINGY to Experimental.h, and associated #ifdef SPECIAL_THINGY to files, please add comments to Experimental.h to say why they are there and what (if anything) they are dependent on.
  • If you intend to delete the last #define SPECIAL_THINGY from Experimental.h, and associated #ifdef SPECIAL_THINGY from a file, please discuss on Audacity-devel first. It may be that other people do not share your view on how ready-for-prime-time the feature actually is.

In some cases developers group several #defines together and place them under a 'master' #define in Experimental.h. This can be a bit confusing, so if you do this, please add a comment saying why the features have been grouped.