162 lines
3.8 KiB
Plaintext
162 lines
3.8 KiB
Plaintext
/**********************************************************************
|
|
|
|
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
|
|
|
|
|
|
|
|
*//*****************************************************************/
|