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