Audacity  3.0.3
FileNames.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  FileNames.h
6 
7  James Crook
8 
9 **********************************************************************/
10 
11 #ifndef __AUDACITY_FILE_NAMES__
12 #define __AUDACITY_FILE_NAMES__
13 
14 
15 
16 #include <wx/dir.h> // for wxDIR_FILES
17 #include <wx/string.h> // function return value
18 #include "Identifier.h"
19 #include "Prefs.h"
20 #include <memory>
21 
22 // Please try to support unlimited path length instead of using PLATFORM_MAX_PATH!
23 // Define one constant for maximum path value, so we don't have to do
24 // platform-specific conditionals everywhere we want to check it.
25 #define PLATFORM_MAX_PATH 260 // Play it safe for default, with same value as Windows' MAX_PATH.
26 
27 #ifdef __WXMAC__
28 #undef PLATFORM_MAX_PATH
29 #define PLATFORM_MAX_PATH PATH_MAX
30 #endif
31 
32 #ifdef __WXGTK__
33 // Some systems do not restrict the path length and therefore PATH_MAX is undefined
34 #ifdef PATH_MAX
35 #undef PLATFORM_MAX_PATH
36 #define PLATFORM_MAX_PATH PATH_MAX
37 #endif
38 #endif
39 
40 #ifdef __WXX11__
41 // wxX11 should also get the platform-specific definition of PLATFORM_MAX_PATH, so do not declare here.
42 #endif
43 
44 #ifdef __WXMSW__
45 #undef PLATFORM_MAX_PATH
46 #define PLATFORM_MAX_PATH MAX_PATH
47 #endif
48 
49 class wxFileName;
50 class wxFileNameWrapper;
51 
52 namespace FileNames
53 {
54  // A description of a type of file
55  struct FileType {
56  FileType() = default;
57 
58  FileType( TranslatableString d, FileExtensions e, bool a = false )
59  : description{ std::move( d ) }
60  , extensions( std::move( e ) )
61  , appendExtensions{ a }
62  {}
63 
66  // Whether to extend the displayed description with mention of the
67  // extensions:
68  bool appendExtensions = false;
69  };
70 
71  // Frequently used types
72  extern AUDACITY_DLL_API const FileType
73  AllFiles // *
74  , AudacityProjects // *.aup3
75  , DynamicLibraries // depends on the operating system
76  , TextFiles // *.txt
77  , XMLFiles; // *.xml, *.XML
78 
79  using FileTypes = std::vector< FileType >;
80 
81  // Convert fileTypes into a single string as expected by wxWidgets file
82  // selection dialog
83  AUDACITY_DLL_API wxString FormatWildcard( const FileTypes &fileTypes );
84 
85  // This exists to compensate for bugs in wxCopyFile:
86  AUDACITY_DLL_API bool DoCopyFile(
87  const FilePath& file1, const FilePath& file2, bool overwrite = true);
88 
89  // wxWidgets doesn't have a function to do this: make a hard file-system
90  // link if possible. It might not be, as when the paths are on different
91  // storage devices.
92  AUDACITY_DLL_API
93  bool HardLinkFile( const FilePath& file1, const FilePath& file2);
94 
95  AUDACITY_DLL_API wxString MkDir(const wxString &Str);
96 
97  AUDACITY_DLL_API bool IsMidi(const FilePath &fName);
98 
107  AUDACITY_DLL_API const FilePaths &AudacityPathList();
108  AUDACITY_DLL_API void SetAudacityPathList( FilePaths list );
109 
110  // originally an ExportMultipleDialog method. Append suffix if newName appears in otherNames.
111  AUDACITY_DLL_API void MakeNameUnique(
112  FilePaths &otherNames, wxFileName &newName);
113 
114  AUDACITY_DLL_API wxString LowerCaseAppNameInPath( const wxString & dirIn);
120  AUDACITY_DLL_API FilePath DataDir();
121  AUDACITY_DLL_API FilePath ResourcesDir();
122  AUDACITY_DLL_API FilePath HtmlHelpDir();
123  AUDACITY_DLL_API FilePath HtmlHelpIndexFile(bool quick);
124  AUDACITY_DLL_API FilePath LegacyChainDir();
125  AUDACITY_DLL_API FilePath MacroDir();
126  AUDACITY_DLL_API FilePath NRPDir();
127  AUDACITY_DLL_API FilePath NRPFile();
128  AUDACITY_DLL_API FilePath PluginRegistry();
129  AUDACITY_DLL_API FilePath PluginSettings();
130 
131  AUDACITY_DLL_API FilePath BaseDir();
132  AUDACITY_DLL_API FilePath ModulesDir();
133 
139  AUDACITY_DLL_API FilePath PlugInDir();
140  AUDACITY_DLL_API FilePath ThemeDir();
141  AUDACITY_DLL_API FilePath ThemeComponentsDir();
142  AUDACITY_DLL_API FilePath ThemeCachePng();
143  AUDACITY_DLL_API FilePath ThemeCacheAsCee();
144  AUDACITY_DLL_API FilePath ThemeComponent(const wxString &Str);
145  AUDACITY_DLL_API FilePath ThemeCacheHtm();
146  AUDACITY_DLL_API FilePath ThemeImageDefsAsCee();
147 
148  // Obtain name of loaded module that contains address
149  AUDACITY_DLL_API FilePath PathFromAddr(void *addr);
150 
151  AUDACITY_DLL_API bool IsPathAvailable( const FilePath & Path);
153  (const wxString &preference);
154 
155  // If not None, determines a preference key (for the default path string) to
156  // be read and updated
157  enum class Operation {
158  // _ on None to defeat some macro that is expanding this.
159  _None,
160 
161  // These do not have a specific pathtype
162  Temp,
163  Presets,
164 
165  // These have default/lastused pathtypes
166  Open,
167  Save,
168  Import,
169  Export,
170  MacrosOut
171  };
172 
173  enum class PathType {
174  // _ on None to defeat some macro that is expanding this.
175  _None,
176  User,
177  LastUsed
178  };
179 
180  AUDACITY_DLL_API wxString PreferenceKey(FileNames::Operation op, FileNames::PathType type);
181 
182  AUDACITY_DLL_API FilePath FindDefaultPath(Operation op);
183  AUDACITY_DLL_API void UpdateDefaultPath(Operation op, const FilePath &path);
184 
185  // F is a function taking a wxString, returning wxString
186  template<typename F>
188  (Operation op, const FilePath &defaultPath, F function)
189  {
190  auto path = gPrefs->Read(PreferenceKey(op, PathType::User), defaultPath);
191  if (path.empty())
192  path = FileNames::FindDefaultPath(op);
193  auto result = function(path);
194  FileNames::UpdateDefaultPath(op, ::wxPathOnly(result));
195  return result;
196  }
197 
198  AUDACITY_DLL_API FilePath
199  SelectFile(Operation op, // op matters only when default_path is empty
200  const TranslatableString& message,
201  const FilePath& default_path,
202  const FilePath& default_filename,
203  const FileExtension& default_extension,
204  const FileTypes& fileTypes,
205  int flags,
206  wxWindow *parent);
207 
208  // Useful functions for working with search paths
209  AUDACITY_DLL_API void AddUniquePathToPathList(const FilePath &path,
210  FilePaths &pathList);
211  AUDACITY_DLL_API void AddMultiPathsToPathList(const wxString &multiPathString,
212  FilePaths &pathList);
213  AUDACITY_DLL_API void FindFilesInPathList(const wxString & pattern,
214  const FilePaths & pathList,
215  FilePaths &results,
216  int flags = wxDIR_FILES);
217 
220 #if defined(__WXMSW__)
221  AUDACITY_DLL_API char *VerifyFilename(const wxString &s, bool input = true);
222 #endif
223 
224  // wxString compare function for sorting case, which is needed to load correctly.
225  AUDACITY_DLL_API int CompareNoCase(const wxString& first, const wxString& second);
226 
227  // Create a unique filename using the passed prefix and suffix
228  AUDACITY_DLL_API wxString CreateUniqueName(const wxString &prefix,
229  const wxString &suffix = wxEmptyString);
230 
231  // File extension used for unsaved/temporary project files
232  AUDACITY_DLL_API wxString UnsavedProjectExtension();
233 
234  AUDACITY_DLL_API
235  bool IsOnFATFileSystem(const FilePath &path);
236 
237  AUDACITY_DLL_API
239  wxString AbbreviatePath(const wxFileName &fileName);
240 };
241 
242 // Use this macro to wrap all filenames and pathnames that get
243 // passed directly to a system call, like opening a file, creating
244 // a directory, checking to see that a file exists, etc...
245 #if defined(__WXMSW__)
246 // Note, on Windows we don't define an OSFILENAME() to prevent accidental use.
247 // See VerifyFilename() for an explanation.
248 #define OSINPUT(X) FileNames::VerifyFilename(X, true)
249 #define OSOUTPUT(X) FileNames::VerifyFilename(X, false)
250 #elif defined(__WXMAC__)
251 #define OSFILENAME(X) ((char *) (const char *)(X).fn_str())
252 #define OSINPUT(X) OSFILENAME(X)
253 #define OSOUTPUT(X) OSFILENAME(X)
254 #else
255 #define OSFILENAME(X) ((char *) (const char *)(X).mb_str())
256 #define OSINPUT(X) OSFILENAME(X)
257 #define OSOUTPUT(X) OSFILENAME(X)
258 #endif
259 
260 #endif
FileNames::IsMidi
AUDACITY_DLL_API bool IsMidi(const FilePath &fName)
FilePath
wxString FilePath
Definition: Identifier.h:227
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
FileNames::UnsavedProjectExtension
AUDACITY_DLL_API wxString UnsavedProjectExtension()
FileNames::PluginRegistry
AUDACITY_DLL_API FilePath PluginRegistry()
FileNames::DoCopyFile
AUDACITY_DLL_API bool DoCopyFile(const FilePath &file1, const FilePath &file2, bool overwrite=true)
FileNames::CompareNoCase
AUDACITY_DLL_API int CompareNoCase(const wxString &first, const wxString &second)
Protect against Unicode to multi-byte conversion failures on Windows.
FileNames::FileType::description
TranslatableString description
Definition: FileNames.h:64
wxFileNameWrapper
Definition: wxFileNameWrapper.h:21
gPrefs
FileConfig * gPrefs
Definition: Prefs.cpp:68
FileNames::UpdateDefaultPath
AUDACITY_DLL_API void UpdateDefaultPath(Operation op, const FilePath &path)
FileNames::DataDir
AUDACITY_DLL_API FilePath DataDir()
Audacity user data directory.
FileNames::FileType::FileType
FileType()=default
FileNames::AddUniquePathToPathList
AUDACITY_DLL_API void AddUniquePathToPathList(const FilePath &path, FilePaths &pathList)
FileNames::XMLFiles
AUDACITY_DLL_API const FileType XMLFiles
Definition: FileNames.h:77
FileNames::HardLinkFile
AUDACITY_DLL_API bool HardLinkFile(const FilePath &file1, const FilePath &file2)
FileNames::AudacityPathList
AUDACITY_DLL_API const FilePaths & AudacityPathList()
A list of directories that should be searched for Audacity files (plug-ins, help files,...
FileNames::AllFiles
AUDACITY_DLL_API const FileType AllFiles
Definition: FileNames.h:74
wxArrayStringEx
Extend wxArrayString with move operations and construction and insertion fromstd::initializer_list.
Definition: wxArrayStringEx.h:18
FileNames::AudacityProjects
AUDACITY_DLL_API const FileType AudacityProjects
Definition: FileNames.h:75
FileNames::FindFilesInPathList
AUDACITY_DLL_API void FindFilesInPathList(const wxString &pattern, const FilePaths &pathList, FilePaths &results, int flags=wxDIR_FILES)
FileNames::WithDefaultPath
FilePath WithDefaultPath(Operation op, const FilePath &defaultPath, F function)
Definition: FileNames.h:188
Export
Main class to control the export function.
FileNames::IsPathAvailable
AUDACITY_DLL_API bool IsPathAvailable(const FilePath &Path)
FileNames::BaseDir
AUDACITY_DLL_API FilePath BaseDir()
FileExtension
wxString FileExtension
File extension, not including any leading dot.
Definition: Identifier.h:224
FileNames::MkDir
AUDACITY_DLL_API wxString MkDir(const wxString &Str)
FileNames::ThemeCacheAsCee
AUDACITY_DLL_API FilePath ThemeCacheAsCee()
FileNames::TextFiles
AUDACITY_DLL_API const FileType TextFiles
Definition: FileNames.h:77
FileNames
Definition: FileNames.h:53
FileNames::PathFromAddr
AUDACITY_DLL_API FilePath PathFromAddr(void *addr)
FileNames::LowerCaseAppNameInPath
AUDACITY_DLL_API wxString LowerCaseAppNameInPath(const wxString &dirIn)
FileNames::ThemeComponent
AUDACITY_DLL_API FilePath ThemeComponent(const wxString &Str)
FileNames::AbbreviatePath
AUDACITY_DLL_API wxString AbbreviatePath(const wxFileName &fileName)
Give enough of the path to identify the device. (On Windows, drive letter plus ':')
FileNames::ThemeCacheHtm
AUDACITY_DLL_API FilePath ThemeCacheHtm()
FileNames::ThemeImageDefsAsCee
AUDACITY_DLL_API FilePath ThemeImageDefsAsCee()
Identifier.h
FileNames::FileType::appendExtensions
bool appendExtensions
Definition: FileNames.h:68
FileNames::NRPDir
AUDACITY_DLL_API FilePath NRPDir()
FileNames::PluginSettings
AUDACITY_DLL_API FilePath PluginSettings()
FileNames::ResourcesDir
AUDACITY_DLL_API FilePath ResourcesDir()
FileNames::IsOnFATFileSystem
AUDACITY_DLL_API bool IsOnFATFileSystem(const FilePath &path)
FileNames::PathType
PathType
Definition: FileNames.h:173
FileNames::MakeNameUnique
AUDACITY_DLL_API void MakeNameUnique(FilePaths &otherNames, wxFileName &newName)
anonymous_namespace{Registry.cpp}::Path
std::vector< Identifier > Path
Definition: Registry.cpp:163
FileNames::AddMultiPathsToPathList
AUDACITY_DLL_API void AddMultiPathsToPathList(const wxString &multiPathString, FilePaths &pathList)
FileNames::ThemeComponentsDir
AUDACITY_DLL_API FilePath ThemeComponentsDir()
FileNames::PlugInDir
AUDACITY_DLL_API FilePath PlugInDir()
The user plug-in directory (not a system one)
FileNames::ThemeDir
AUDACITY_DLL_API FilePath ThemeDir()
FileNames::HtmlHelpDir
AUDACITY_DLL_API FilePath HtmlHelpDir()
FileNames::MacroDir
AUDACITY_DLL_API FilePath MacroDir()
FileNames::NRPFile
AUDACITY_DLL_API FilePath NRPFile()
FileNames::SelectFile
AUDACITY_DLL_API FilePath SelectFile(Operation op, const TranslatableString &message, const FilePath &default_path, const FilePath &default_filename, const FileExtension &default_extension, const FileTypes &fileTypes, int flags, wxWindow *parent)
FileNames::DefaultToDocumentsFolder
AUDACITY_DLL_API wxFileNameWrapper DefaultToDocumentsFolder(const wxString &preference)
FileNames::DynamicLibraries
AUDACITY_DLL_API const FileType DynamicLibraries
Definition: FileNames.h:76
FileNames::CreateUniqueName
AUDACITY_DLL_API wxString CreateUniqueName(const wxString &prefix, const wxString &suffix=wxEmptyString)
FileNames::PreferenceKey
AUDACITY_DLL_API wxString PreferenceKey(FileNames::Operation op, FileNames::PathType type)
FileNames::ModulesDir
AUDACITY_DLL_API FilePath ModulesDir()
FileNames::LegacyChainDir
AUDACITY_DLL_API FilePath LegacyChainDir()
FileNames::FileTypes
std::vector< FileType > FileTypes
Definition: FileNames.h:79
FileNames::ThemeCachePng
AUDACITY_DLL_API FilePath ThemeCachePng()
Prefs.h
FileNames::FileType::extensions
FileExtensions extensions
Definition: FileNames.h:65
FileNames::FindDefaultPath
AUDACITY_DLL_API FilePath FindDefaultPath(Operation op)
FileNames::FileType::FileType
FileType(TranslatableString d, FileExtensions e, bool a=false)
Definition: FileNames.h:58
FileNames::SetAudacityPathList
AUDACITY_DLL_API void SetAudacityPathList(FilePaths list)
FileNames::FileType
Definition: FileNames.h:55
FileNames::FormatWildcard
AUDACITY_DLL_API wxString FormatWildcard(const FileTypes &fileTypes)
FileNames::Operation
Operation
Definition: FileNames.h:157
FileNames::HtmlHelpIndexFile
AUDACITY_DLL_API FilePath HtmlHelpIndexFile(bool quick)