| Version: 3.3.1

Public Member Functions | Static Public Member Functions | List of all members
wxDir Class Reference
Class List by Category » File Handling

`#include <wx/dir.h>`

## Detailed Description

wxDir is a portable equivalent of Unix open/read/closedir functions which allow enumerating of the files in a directory.

wxDir allows enumerating files as well as directories.

wxDir also provides a flexible way to enumerate files recursively using Traverse() or a simpler GetAllFiles() function.

Example of use:

wxDir dir(wxGetCwd());
if ( !dir.IsOpened() )
{
// deal with the error here - wxDir would already log an error message
// explaining the exact reason of the failure
return;
}
puts("Enumerating object files in current directory:");
wxString filename;
bool cont = dir.GetFirst(&filename, filespec, flags);
while ( cont )
{
printf("%s\n", filename.c_str());
cont = dir.GetNext(&filename);
}
wxDir
wxDir is a portable equivalent of Unix open/read/closedir functions which allow enumerating of the fi...
Definition: dir.h:175
wxString
String class for passing textual data to or receiving it from wxWidgets.
Definition: string.h:372
wxString::c_str
wxCStrData c_str() const
Returns a lightweight intermediate class which is in turn implicitly convertible to both const char* ...
wxGetCwd
wxString wxGetCwd()
Returns a string containing the current (or working) directory.

##

Library: wxBase
Category: File Handling

## Public Member Functions
| wxDir ()
| Default constructor, use Open() afterwards. More...
| wxDir (const wxString &dir)
| Opens the directory for enumeration, use IsOpened() to test for errors. More...
| ~wxDir ()
| Destructor cleans up the associated resources by calling Close(). More...
void | Close ()
| Close the directory. More...
bool | GetFirst (wxString *filename, const wxString &filespec=wxEmptyString, int flags=wxDIR_DEFAULT) const
| Start enumerating all files matching filespec (or all files if it is empty) and flags, return true on success. More...
wxString | GetName () const
| Returns the name of the directory itself. More...
wxString | GetNameWithSep () const
| Returns the name of the directory with the path separator appended. More...
bool | GetNext (wxString *filename) const
| Continue enumerating files which satisfy the criteria specified by the last call to GetFirst(). More...
bool | HasFiles (const wxString &filespec=wxEmptyString) const
| Returns true if the directory contains any files matching the given filespec. More...
bool | HasSubDirs (const wxString &dirspec=wxEmptyString) const
| Returns true if the directory contains any subdirectories (if a non empty dirspec is given, only check for directories matching it). More...
bool | IsOpened () const
| Returns true if the directory was successfully opened by a previous call to Open(). More...
bool | Open (const wxString &dir)
| Open the directory for enumerating, returns true on success or false if an error occurred. More...
size_t | Traverse (wxDirTraverser &sink, const wxString &filespec=wxEmptyString, int flags=wxDIR_DEFAULT) const
| Enumerate all files and directories under the given directory. More...

## Static Public Member Functions
static bool | Exists (const wxString &dir)
| Test for existence of a directory with the given name. More...
static wxString | FindFirst (const wxString &dirname, const wxString &filespec, int flags=wxDIR_DEFAULT)
| The function returns the path of the first file matching the given filespec or an empty string if there are no files matching it. More...
static size_t | GetAllFiles (const wxString &dirname, wxArrayString *files, const wxString &filespec=wxEmptyString, int flags=wxDIR_DEFAULT)
| The function appends the names of all the files under directory dirname to the array files (note that its old content is preserved). More...
static wxULongLong | GetTotalSize (const wxString &dir, wxArrayString *filesSkipped=nullptr)
| Returns the size (in bytes) of all files recursively found in `dir` or `wxInvalidSize` in case of error. More...
static bool | Make (const wxString &dir, int perm=wxS_DIR_DEFAULT, int flags=0)
| Creates a directory. More...
static bool | Remove (const wxString &dir, int flags=0)
| Removes a directory. More...

## Constructor & Destructor Documentation

## ◆ wxDir() [1/2]

wxDir::wxDir | ( |  | ) |

Default constructor, use Open() afterwards.

## ◆ wxDir() [2/2]

wxDir::wxDir | ( | const wxString & | dir | ) |

Opens the directory for enumeration, use IsOpened() to test for errors.

## ◆ ~wxDir()

wxDir::~wxDir | ( |  | ) |

Destructor cleans up the associated resources by calling Close().

It is not virtual and so this class is not meant to be used polymorphically.

## Member Function Documentation

## ◆ Close()

void wxDir::Close | ( |  | ) |

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

## ◆ Exists()

static bool wxDir::Exists | ( | const wxString & | dir | ) |
| static

Test for existence of a directory with the given name.

## ◆ FindFirst()

static wxString wxDir::FindFirst | ( | const wxString & | dirname,
|  | const wxString & | filespec,
|  | int | flags = `wxDIR_DEFAULT`
| ) |  |
| static

The function returns the path of the first file matching the given filespec or an empty string if there are no files matching it.

The flags parameter may or may not include wxDIR_FILES, the function always behaves as if it were specified. By default, flags includes wxDIR_DIRS and so the function recurses into the subdirectories but if this flag is not specified, the function restricts the search only to the directory dirname itself. See wxDirFlags for the list of the possible flags.

See also
  Traverse()

## ◆ GetAllFiles()

static size_t wxDir::GetAllFiles | ( | const wxString & | dirname,
|  | wxArrayString * | files,
|  | const wxString & | filespec = `wxEmptyString`,
|  | int | flags = `wxDIR_DEFAULT`
| ) |  |
| static

The function appends the names of all the files under directory dirname to the array files (note that its old content is preserved).

Only files matching the filespec are taken, with empty spec matching all non-hidden files (use wxDIR_HIDDEN to include them too).

The flags parameter should always include wxDIR_FILES or the array would be unchanged and should include wxDIR_DIRS flag to recurse into subdirectories (both flags are included in the value by default). See wxDirFlags for the list of the possible flags.

Returns
  Returns the total number of files found while traversing the directory dirname (i.e. the number of entries appended to the files array).

See also
  Traverse()

## ◆ GetFirst()

bool wxDir::GetFirst | ( | wxString * | filename,
|  | const wxString & | filespec = `wxEmptyString`,
|  | int | flags = `wxDIR_DEFAULT`
| ) |  | const

Start enumerating all files matching filespec (or all files if it is empty) and flags, return true on success.

See wxDirFlags for the list of the possible flags.

## ◆ GetName()

wxString wxDir::GetName | ( |  | ) | const

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.

## ◆ GetNameWithSep()

wxString wxDir::GetNameWithSep | ( |  | ) | 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 also
  GetName()

Since
  2.9.4

## ◆ GetNext()

bool wxDir::GetNext | ( | wxString * | filename | ) | const

Continue enumerating files which satisfy the criteria specified by the last call to GetFirst().

## ◆ GetTotalSize()

static wxULongLong wxDir::GetTotalSize | ( | const wxString & | dir,
|  | wxArrayString * | filesSkipped = `nullptr`
| ) |  |
| static

Returns the size (in bytes) of all files recursively found in `dir` or `wxInvalidSize` in case of error.

In case it happens that while traversing folders a file's size cannot be read, that file is added to the filesSkipped array, if not nullptr, and then skipped. This usually happens with some special folders which are locked by the operating system or by another process. Remember that when the size of filesSkipped is not zero, then the returned value is not 100% accurate and, if the skipped files were big, it could be far from real size of the directory.

See also
  wxFileName::GetHumanReadableSize(), wxGetDiskSpace()

## ◆ HasFiles()

bool wxDir::HasFiles | ( | const wxString & | filespec = `wxEmptyString` | ) | const

Returns true if the directory contains any files matching the given filespec.

If filespec is empty, look for any files at all. In any case, even hidden files are taken into account.

## ◆ HasSubDirs()

bool wxDir::HasSubDirs | ( | const wxString & | dirspec = `wxEmptyString` | ) | const

Returns true if the directory contains any subdirectories (if a non empty dirspec is given, only check for directories matching it).

The hidden subdirectories are taken into account as well.

## ◆ IsOpened()

bool wxDir::IsOpened | ( |  | ) | const

Returns true if the directory was successfully opened by a previous call to Open().

## ◆ Make()

static bool wxDir::Make | ( | const wxString & | dir,
|  | int | perm = `wxS_DIR_DEFAULT`,
|  | int | flags = `0`
| ) |  |
| static

Creates a directory.

This is just an alias for wxFileName::Mkdir(); refer to that function for more info.

## ◆ Open()

bool wxDir::Open | ( | const wxString & | dir | ) |

Open the directory for enumerating, returns true on success or false if an error occurred.

## ◆ Remove()

static bool wxDir::Remove | ( | const wxString & | dir,
|  | int | flags = `0`
| ) |  |
| static

Removes a directory.

This is just an alias for wxFileName::Rmdir(); refer to that function for more info.

## ◆ Traverse()

size_t wxDir::Traverse | ( | wxDirTraverser & | sink,
|  | const wxString & | filespec = `wxEmptyString`,
|  | int | flags = `wxDIR_DEFAULT`
| ) |  | const

Enumerate all files and directories under the given directory.

If 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 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, sink.OnDir() is called and sink.OnFile() is called for every file. Depending on the return value, the enumeration may continue or stop. If entering a subdirectory fails, sink.OnOpenError() is called.

The function returns the total number of files found or `"(size_t)-1"` on error.

See wxDirFlags for the full list of the possible flags.

See also
  GetAllFiles()