1/**********************************************************************
2
3  Audacity: A Digital Audio Editor
4
5  CrossPlatform.dox2
6
7  James Crook
8
9  Documents Cross Platform coding issues.
10
11********************************************************************//*
12
13JKC: The examples in this file need to be extracted into a separate file so
14that we can get the comments to show correctly in the output files.
15
16
17/*****************************************************************//*!
18\page CrossPlatform Cross Platform Coding Tips
19\brief Guidelines for making the code compile and work on all supported platforms.
20
21\section PragmaOnce \#pragma once
22
23The following is not supported under gcc 2.x:
24
25\code
26// WRONG
27#pragma once
28\endcode
29
30Instead use the traditional:
31
32\code
33#ifndef __AUDACITY_HEADER_FILE_NAME__
34#define __AUDACITY_HEADER_FILE_NAME__
35
36// your header file contents goes here.
37
38#endif
39\endcode
40
41\section UnicodeStrings Unicode strings
42
43Audacity code is translated, and it may be built in Unicode versions.
44For this reason all strings should be wrapped like this:
45
46\code
47   // for strings which are not translated
48   mMyFirstString = wxT("some untranslated string");
49   // for strings which should be translated
50   mMySecondString = _("some translatable string");
51\endcode
52
53In some cases you need to give hints to a translator about how a
54string should be translated.  Do so as follows:
55
56\dontinclude examples.hh
57
58\skip i18n-hint
59\until "R"
60
61Very long strings can be wrapped across multiple lines, as follows:
62
63\code
64   // For untranslated strings:
65   wxT("This is a long untranslated string ")
66   wxT("which spans several lines ")
67   wxT("and works in Unicode builds too")
68
69   // For translated strings:
70   _("This is a long translated string "
71   wxT("which spans several lines ")
72   wxT("and works in Unicode builds too"))
73\endcode
74
75Notice that in the translated example, all bar the first substring
76are contained within a \p wxT().
77
78\section ConstructorsAsArguments Constructors as Arguments
79
80Don't write code like this:
81
82\code
83   // WRONG
84   // Now call OnSampleRateChange to update the values.
85   OnSampleRateChange( wxCommandEvent() );
86\endcode
87
88Whilst it is fine under MSVC it will cause a problem under gcc as the
89constructor is a temporary object which will be optimised away.
90
91Instead use:
92
93\code
94   // Now call OnSampleRateChange to update the values.
95   wxCommandEvent e;
96   OnSampleRateChange( e );
97\endcode
98
99\section HeaderFiles Header Files
100
101Windows systems are not case sensitive, whilst Linux systems are.
102You therefore need to take care in capitalisation, e.g:
103
104\code
105#include "AttachableScrollBar.h"
106\endcode
107
108\section ClassNamesInClasses Class Names in Classes
109
110Microsoft Visual C++ allows you to write code like this in a header file:
111
112\code
113// WRONG
114class MyClass
115{
116public:
117   int MyClass::SomeFunction();
118   //... other stuff
119\endcode
120
121For portability, the \p 'MyClass::' prefix should be left out.
122
123\section wxStringInFormat Using wxString in Format
124
125Don't write code like this:
126
127\code
128   wxString Message( wxT("Hello" ));
129   // WRONG
130   wxString Temp = wxString::Format(wxT("Your said %s in your message"), Message );
131\endcode
132
133Although MSVC won't complain even in Unicode mode, it generates a warning under gcc.
134Instead you need:
135
136\code
137   wxString Message( wxT("Hello" ));
138   wxString Temp = wxString::Format(wxT("Your said %s in your message"), Message.c_str() );
139\endcode
140
141
142\section ForwardEnums Forward Declared Enums
143
144Microsoft Visual C++ allows you to write code like this in a header file:
145
146\code
147// WRONG
148enum MyEnum;
149\endcode
150
151That is, you can forward declare an enum just as you can forward
152declare a class.  This is not portable.  The alternative is to include
153a header file containing the full enum definition.
154
155\code
156#include "MyEnum.h"
157\endcode
158
159
160
161*//*****************************************************************/
162