]> git.saurik.com Git - wxWidgets.git/blob - interface/filefn.h
added back docs for wxWindow::WindowToClientSize, added some missing @since tags
[wxWidgets.git] / interface / filefn.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: filefn.h
3 // Purpose: interface of wxPathList
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxPathList
11 @wxheader{filefn.h}
12
13 The path list is a convenient way of storing a number of directories, and
14 when presented with a filename without a directory, searching for an existing
15 file
16 in those directories.
17
18 Be sure to look also at wxStandardPaths if you only
19 want to search files in some standard paths.
20
21 @library{wxbase}
22 @category{file}
23
24 @see wxArrayString, wxStandardPaths, wxFileName
25 */
26 class wxPathList : public wxArrayString
27 {
28 public:
29 //@{
30 /**
31 Constructs the object calling the Add() function.
32 */
33 wxPathList();
34 wxPathList(const wxArrayString& arr);
35 //@}
36
37 //@{
38 /**
39 The first form adds the given directory to the path list, if the path is not
40 already in the list.
41 If the path cannot be normalized for some reason, it returns @false.
42 The second form just calls the first form on all elements of the given array.
43 The @a path is always considered a directory but no existence checks will be
44 done on it
45 (because if it doesn't exist, it could be created later and thus result a valid
46 path when
47 FindValidPath() is called).
48 @b Note: if the given path is relative, it won't be made absolute before adding
49 it
50 (this is why FindValidPath() may return relative paths).
51 */
52 bool Add(const wxString& path);
53 void Add(const wxArrayString& arr);
54 //@}
55
56 /**
57 Finds the value of the given environment variable, and adds all paths
58 to the path list. Useful for finding files in the @c PATH variable, for
59 example.
60 */
61 void AddEnvList(const wxString& env_variable);
62
63 /**
64 Given a full filename (with path), calls Add() with the path
65 of the file.
66 */
67 bool EnsureFileAccessible(const wxString& filename);
68
69 /**
70 Like FindValidPath() but this function always
71 returns an absolute path (eventually prepending the current working directory
72 to the value returned wxPathList::FindValidPath) or an
73 empty string.
74 */
75 wxString FindAbsoluteValidPath(const wxString& file) const;
76
77 /**
78 Searches the given file in all paths stored in this class.
79 The first path which concatenated to the given string points to an existing
80 file (see @ref wxFile::exists wxFileExists) is returned.
81 If the file wasn't found in any of the stored paths, an empty string is
82 returned.
83 The given string must be a file name, eventually with a path prefix (if the path
84 prefix is absolute, only its name will be searched); i.e. it must not end with
85 a directory separator (see wxFileName::GetPathSeparator)
86 otherwise an assertion will fail.
87 The returned path may be relative to the current working directory.
88 Note in fact that wxPathList can be used to store both relative and absolute
89 paths so that
90 if you Added() relative paths, then the current working directory
91 (see wxGetCwd() and wxSetWorkingDirectory())
92 may affect the value returned by this function!
93 */
94 wxString FindValidPath(const wxString& file) const;
95 };
96
97
98
99 // ============================================================================
100 // Global functions/macros
101 // ============================================================================
102
103 /**
104 This function returns the total number of bytes and number of free bytes on
105 the disk containing the directory @a path (it should exist). Both
106 @a total and @a free parameters may be @NULL if the corresponding
107 information is not needed.
108 */
109 bool wxGetDiskSpace(const wxString& path,
110 wxLongLong total = NULL,
111 wxLongLong free = NULL);
112
113 /**
114 Returns the Windows directory under Windows; on other platforms returns the
115 empty string.
116 */
117 wxString wxGetOSDirectory();
118
119 /**
120 Parses the @e wildCard, returning the number of filters.
121 Returns 0 if none or if there's a problem.
122 The arrays will contain an equal number of items found before the error.
123 On platforms where native dialogs handle only one filter per entry,
124 entries in arrays are automatically adjusted.
125 @a wildCard is in the form:
126
127 @code
128 "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png"
129 @endcode
130 */
131 int wxParseCommonDialogsFilter(const wxString& wildCard,
132 wxArrayString& descriptions,
133 wxArrayString& filters);
134
135 /**
136 This function is deprecated, use wxFileName instead.
137 Converts a Unix to a DOS filename by replacing forward
138 slashes with backslashes.
139 */
140 void wxUnix2DosFilename(wxChar* s);
141
142 /**
143 Returns @true if @a dirname exists and is a directory.
144 */
145 bool wxDirExists(const wxString& dirname);
146
147 /**
148 @b NB: This function is obsolete, please use
149 wxFileName::SplitPath instead.
150 This function splits a full file name into components: the path (including
151 possible disk/drive
152 specification under Windows), the base name and the extension. Any of the
153 output parameters
154 (@e path, @a name or @e ext) may be @NULL if you are not interested in the value
155 of
156 a particular component.
157 wxSplitPath() will correctly handle filenames with both DOS and Unix path
158 separators under
159 Windows, however it will not consider backslashes as path separators under Unix
160 (where backslash
161 is a valid character in a filename).
162 On entry, @a fullname should be non-@NULL (it may be empty though).
163 On return, @a path contains the file path (without the trailing separator), @e
164 name
165 contains the file name and @a ext contains the file extension without leading
166 dot. All
167 three of them may be empty if the corresponding component is. The old contents
168 of the
169 strings pointed to by these parameters will be overwritten in any case (if the
170 pointers
171 are not @NULL).
172 */
173 void wxSplitPath(const wxString& fullname, wxString* path,
174 wxString* name,
175 wxString* ext);
176
177 /**
178 Under Unix this macro changes the current process umask to the given value,
179 unless it is equal to -1 in which case nothing is done, and restores it to
180 the original value on scope exit. It works by declaring a variable which sets
181 umask to @a mask in its constructor and restores it in its destructor.
182 Under other platforms this macro expands to nothing.
183 */
184 #define wxCHANGE_UMASK(int mask) /* implementation is private */
185
186 /**
187 Returns time of last modification of given file.
188 The function returns @c (time_t)-1 if an error occurred (e.g. file not
189 found).
190 */
191 time_t wxFileModificationTime(const wxString& filename);
192
193 //@{
194 /**
195 @b NB: This function is obsolete, please use
196 wxFileName::SplitPath instead.
197 Returns the filename for a full path. The second form returns a pointer to
198 temporary storage that should not be deallocated.
199 */
200 wxString wxFileNameFromPath(const wxString& path);
201 char* wxFileNameFromPath(char* path);
202 //@}
203
204 /**
205 Renames @a file1 to @e file2, returning @true if successful.
206 If @a overwrite parameter is @true (default), the destination file is
207 overwritten if it exists, but if @a overwrite is @false, the functions fails
208 in this case.
209 */
210 bool wxRenameFile(const wxString& file1, const wxString& file2,
211 bool overwrite = true);
212
213 /**
214 Copies @a file1 to @e file2, returning @true if successful. If
215 @a overwrite parameter is @true (default), the destination file is overwritten
216 if it exists, but if @a overwrite is @false, the functions fails in this
217 case.
218 This function supports resources forks under Mac OS.
219 */
220 bool wxCopyFile(const wxString& file1, const wxString& file2,
221 bool overwrite = true);
222
223 /**
224 Returns @true if the file exists and is a plain file.
225 */
226 bool wxFileExists(const wxString& filename);
227
228 /**
229 Returns @true if the @a pattern matches the @e text; if @a dot_special is @true,
230 filenames beginning with a dot are not matched
231 with wildcard characters. See wxIsWild().
232 */
233 bool wxMatchWild(const wxString& pattern, const wxString& text,
234 bool dot_special);
235
236 /**
237 @b NB: This function is deprecated: use wxGetCwd() instead.
238 Copies the current working directory into the buffer if supplied, or
239 copies the working directory into new storage (which you must delete
240 yourself) if the buffer is @NULL.
241 @a sz is the size of the buffer if supplied.
242 */
243 wxString wxGetWorkingDirectory(char* buf = NULL, int sz = 1000);
244
245 /**
246 Returns the directory part of the filename.
247 */
248 wxString wxPathOnly(const wxString& path);
249
250 /**
251 Returns @true if the pattern contains wildcards. See wxMatchWild().
252 */
253 bool wxIsWild(const wxString& pattern);
254
255 /**
256 Returns a string containing the current (or working) directory.
257 */
258 wxString wxGetCwd();
259
260 /**
261 Converts a DOS to a Unix filename by replacing backslashes with forward
262 slashes.
263 */
264 void wxDos2UnixFilename(wxChar* s);
265
266 /**
267 Concatenates @a file1 and @a file2 to @e file3, returning
268 @true if successful.
269 */
270 bool wxConcatFiles(const wxString& file1, const wxString& file2,
271 const wxString& file3);
272
273 /**
274 Removes @e file, returning @true if successful.
275 */
276 bool wxRemoveFile(const wxString& file);
277
278 /**
279 Sets the current working directory, returning @true if the operation succeeded.
280 Under MS Windows, the current drive is also changed if @a dir contains a drive
281 specification.
282 */
283 bool wxSetWorkingDirectory(const wxString& dir);
284
285 /**
286 Makes the directory @e dir, returning @true if successful.
287 @a perm is the access mask for the directory for the systems on which it is
288 supported (Unix) and doesn't have any effect on the other ones.
289 */
290 bool wxMkdir(const wxString& dir, int perm = 0777);
291
292 /**
293 Returns @true if the argument is an absolute filename, i.e. with a slash
294 or drive name at the beginning.
295 */
296 bool wxIsAbsolutePath(const wxString& filename);
297
298 /**
299 Returns the next file that matches the path passed to wxFindFirstFile().
300 See wxFindFirstFile() for an example.
301 */
302 wxString wxFindNextFile();
303
304 /**
305 This function does directory searching; returns the first file
306 that matches the path @e spec, or the empty string. Use wxFindNextFile() to
307 get the next matching file. Neither will report the current directory "." or the
308 parent directory "..".
309 */
310 wxString wxFindFirstFile(const wxString& spec, int flags = 0);
311
312 //@{
313 /**
314 Returns the type of an open file. Possible return values are:
315
316 @code
317 enum wxFileKind
318 {
319 wxFILE_KIND_UNKNOWN,
320 wxFILE_KIND_DISK, // a file supporting seeking to arbitrary offsets
321 wxFILE_KIND_TERMINAL, // a tty
322 wxFILE_KIND_PIPE // a pipe
323 };
324 @endcode
325 */
326 wxFileKind wxGetFileKind(int fd);
327 wxFileKind wxGetFileKind(FILE* fp);
328 //@}
329
330 //@{
331 /**
332 @b NB: These functions are obsolete, please use
333 wxFileName::CreateTempFileName
334 instead.
335 */
336 char* wxGetTempFileName(const wxString& prefix, char* buf = NULL);
337 bool wxGetTempFileName(const wxString& prefix, wxString& buf);
338 //@}
339
340 /**
341 Removes the directory @e dir, returning @true if successful. Does not work under
342 VMS.
343 The @a flags parameter is reserved for future use.
344 Please notice that there is also a wxRmDir() function which simply wraps the
345 standard POSIX rmdir() function and so return an integer error code instead of
346 a boolean value (but otherwise is currently identical to wxRmdir), don't
347 confuse these two functions.
348 */
349 bool wxRmdir(const wxString& dir, int flags = 0);
350