// Name: dir.h
// Purpose: interface of wxDir and wxDirTraverser
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
/**
- These flags define what kind of filenames are included in the list of files
- enumerated by wxDir::GetFirst() and wxDir::GetNext().
+ These flags affect the behaviour of GetFirst/GetNext() and Traverse(),
+ determining what types are included in the list of items they produce.
*/
enum wxDirFlags
{
wxDIR_HIDDEN = 0x0004, ///< Includes hidden files.
wxDIR_DOTDOT = 0x0008, ///< Includes "." and "..".
- //! Combination of the @c wxDIR_FILES, @c wxDIR_DIRS, @c wxDIR_HIDDEN flags
- //! defined above.
+ /**
+ Don't follow symbolic links during the directory traversal.
+
+ This flag is ignored under systems not supporting symbolic links (i.e.
+ non-Unix ones).
+
+ Notice that this flag is @e not included in wxDIR_DEFAULT and so the
+ default behaviour of wxDir::Traverse() is to follow symbolic links,
+ even if they lead outside of the directory being traversed.
+
+ @since 2.9.5
+ */
+ wxDIR_NO_FOLLOW = 0x0010,
+
+ /**
+ Default directory traversal flags include both files and directories,
+ even hidden.
+
+ Notice that by default wxDIR_NO_FOLLOW is @e not included, meaning that
+ symbolic links are followed by default. If this is not desired, you
+ must pass that flag explicitly.
+ */
wxDIR_DEFAULT = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
};
wxDir(const wxString& dir);
/**
- Destructor cleans up the associated resources. It is not virtual and so
- this class is not meant to be used polymorphically.
+ Destructor cleans up the associated resources by calling Close().
+
+ It is not virtual and so this class is not meant to be used
+ polymorphically.
*/
~wxDir();
+ /**
+ Close the directory.
+
+ The object can't be used after closing it, but Open() may be called
+ again to reopen it later.
+
+ @since 2.9.5
+ */
+ void Close();
+
/**
Test for existence of a directory with the given name.
*/
int flags = wxDIR_DEFAULT) const;
/**
- Returns the name of the directory itself. The returned string does not
- have the trailing path separator (slash or backslash).
+ Returns the name of the directory itself.
+
+ The returned string does not have the trailing path separator (slash or
+ backslash).
+
+ Notice that in spite of this the last character of the returned string
+ can still be the path separator if this directory is the root one.
+ Because of this, don't append ::wxFILE_SEP_PATH to the returned value
+ if you do need a slash-terminated directory name but use
+ GetNameWithSep() instead to avoid having duplicate consecutive slashes.
*/
wxString GetName() const;
+ /**
+ Returns the name of the directory with the path separator appended.
+
+ The last character of the returned string is always ::wxFILE_SEP_PATH
+ unless the string is empty, indicating that this directory is invalid.
+
+ @see GetName()
+
+ @since 2.9.4
+ */
+ wxString GetNameWithSep() const;
+
/**
Continue enumerating files which satisfy the criteria specified by the
last call to GetFirst().
Returns the size (in bytes) of all files recursively found in @c dir or
@c wxInvalidSize in case of error.
- In case it happens that while traversing folders a file's size can not
+ In case it happens that while traversing folders a file's size cannot
be read, that file is added to the @a filesSkipped array, if not @NULL,
and then skipped. This usually happens with some special folders which
are locked by the operating system or by another process. Remember that
static bool Remove(const wxString &dir, int flags = 0);
/**
- Enumerate all files and directories under the given directory
- recursively calling the element of the provided wxDirTraverser object
- for each of them.
-
- More precisely, the function will really recurse into subdirectories if
- @a flags contains ::wxDIR_DIRS flag. It will ignore the files (but
- still possibly recurse into subdirectories) if ::wxDIR_FILES flag is
- given.
- See ::wxDirFlags for the list of the possible flags.
+ Enumerate all files and directories under the given directory.
+
+ If @a flags contains ::wxDIR_DIRS this enumeration is recursive, i.e.
+ all the subdirectories of the given one and the files inside them will
+ be traversed. Otherwise only the files in this directory itself are.
+
+ If @a flags doesn't contain ::wxDIR_FILES then only subdirectories are
+ examined but not normal files. It doesn't make sense to not specify
+ either ::wxDIR_DIRS or ::wxDIR_FILES and usually both of them should be
+ specified, as is the case by default.
For each directory found, @ref wxDirTraverser::OnDir() "sink.OnDir()"
is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called
for every file. Depending on the return value, the enumeration may
- continue or stop.
+ continue or stop. If entering a subdirectory fails, @ref
+ wxDirTraverser::OnOpenError() "sink.OnOpenError()" is called.
The function returns the total number of files found or @c "(size_t)-1"
on error.
+ See ::wxDirFlags for the full list of the possible flags.
+
@see GetAllFiles()
*/
size_t Traverse(wxDirTraverser& sink,
projects / wxWidgets.git / blobdiff