/**********************************************************************

  Audacity: A Digital Audio Editor

  CrossPlatform.dox2

  James Crook

  Documents Cross Platform coding issues.

********************************************************************//*

JKC: The examples in this file need to be extracted into a separate file so
that we can get the comments to show correctly in the output files.


/*****************************************************************//*! 
\page CrossPlatform Cross Platform Coding Tips
\brief Guidelines for making the code compile and work on all supported platforms.

\section PragmaOnce \#pragma once

The following is not supported under gcc 2.x:

\code
// WRONG
#pragma once
\endcode

Instead use the traditional:

\code
#ifndef __AUDACITY_HEADER_FILE_NAME__
#define __AUDACITY_HEADER_FILE_NAME__

// your header file contents goes here.

#endif
\endcode

\section UnicodeStrings Unicode strings

Audacity code is translated, and it may be built in Unicode versions.  
For this reason all strings should be wrapped like this:

\code
   // for strings which are not translated
   mMyFirstString = wxT("some untranslated string");
   // for strings which should be translated
   mMySecondString = _("some translatable string");
\endcode

In some cases you need to give hints to a translator about how a 
string should be translated.  Do so as follows:

\dontinclude examples.hh

\skip i18n-hint
\until "R"

Very long strings can be wrapped across multiple lines, as follows:

\code
   // For untranslated strings:
   wxT("This is a long untranslated string ")
   wxT("which spans several lines ")
   wxT("and works in Unicode builds too")

   // For translated strings:
   _("This is a long translated string "
   wxT("which spans several lines ")
   wxT("and works in Unicode builds too"))
\endcode

Notice that in the translated example, all bar the first substring
are contained within a \p wxT().

\section ConstructorsAsArguments Constructors as Arguments

Don't write code like this:

\code
   // WRONG
   // Now call OnSampleRateChange to update the values.
   OnSampleRateChange( wxCommandEvent() );
\endcode

Whilst it is fine under MSVC it will cause a problem under gcc as the 
constructor is a temporary object which will be optimised away.  

Instead use:

\code
   // Now call OnSampleRateChange to update the values.
   wxCommandEvent e;
   OnSampleRateChange( e );
\endcode

\section HeaderFiles Header Files

Windows systems are not case sensitive, whilst Linux systems are.
You therefore need to take care in capitalisation, e.g:

\code
#include "AttachableScrollBar.h"
\endcode

\section ClassNamesInClasses Class Names in Classes

Microsoft Visual C++ allows you to write code like this in a header file:

\code
// WRONG
class MyClass 
{
public:
   int MyClass::SomeFunction();
   //... other stuff
\endcode

For portability, the \p 'MyClass::' prefix should be left out. 

\section wxStringInFormat Using wxString in Format

Don't write code like this:

\code
   wxString Message( wxT("Hello" )); 
   // WRONG
   wxString Temp = wxString::Format(wxT("Your said %s in your message"), Message );
\endcode

Although MSVC won't complain even in Unicode mode, it generates a warning under gcc.
Instead you need:

\code
   wxString Message( wxT("Hello" )); 
   wxString Temp = wxString::Format(wxT("Your said %s in your message"), Message.c_str() );
\endcode
   
   
\section ForwardEnums Forward Declared Enums

Microsoft Visual C++ allows you to write code like this in a header file:

\code
// WRONG
enum MyEnum;
\endcode

That is, you can forward declare an enum just as you can forward 
declare a class.  This is not portable.  The alternative is to include
a header file containing the full enum definition.

\code
#include "MyEnum.h"
\endcode



*//*****************************************************************/