wxDir Class Reference
[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 to enumerate 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);
    }

Library:  wxBase
Category:  File Handling

Public Member Functions

 wxDir ()
 Default constructor, use Open() afterwards.
 wxDir (const wxString &dir)
 Opens the directory for enumeration, use IsOpened() to test for errors.
 ~wxDir ()
 Destructor cleans up the associated resources.
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.
wxString GetName () const
 Returns the name of the directory itself.
bool GetNext (wxString *filename) const
 Continue enumerating files which satisfy the criteria specified by the last call to GetFirst().
bool HasFiles (const wxString &filespec=wxEmptyString) const
 Returns true if the directory contains any files matching the given filespec.
bool HasSubDirs (const wxString &dirspec=wxEmptyString) const
 Returns true if the directory contains any subdirectories (if a non empty filespec is given, only check for directories matching it).
bool IsOpened () const
 Returns true if the directory was successfully opened by a previous call to Open().
bool Open (const wxString &dir)
 Open the directory for enumerating, returns true on success or false if an error occurred.
size_t Traverse (wxDirTraverser &sink, const wxString &filespec=wxEmptyString, int flags=wxDIR_DEFAULT) const
 Enumerate all files and directories under the given directory recursively calling the element of the provided wxDirTraverser object for each of them.

Static Public Member Functions

static bool Exists (const wxString &dir)
 Test for existence of a directory with the given name.
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.
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).
static wxULongLong GetTotalSize (const wxString &dir, wxArrayString *filesSkipped=NULL)
 Returns the size (in bytes) of all files recursively found in dir or wxInvalidSize in case of error.

List of all members.


Constructor & Destructor Documentation

wxDir::wxDir (  ) 

Default constructor, use Open() afterwards.

wxDir::wxDir ( const wxString dir  ) 

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

wxDir::~wxDir (  ) 

Destructor cleans up the associated resources.

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


Member Function Documentation

static bool wxDir::Exists ( const wxString dir  )  [static]

Test for existence of a directory with the given name.

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()
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 the files.

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.

See also:
Traverse()
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.

wxString wxDir::GetName (  )  const

Returns the name of the directory itself.

The returned string does not have the trailing path separator (slash or backslash).

bool wxDir::GetNext ( wxString filename  )  const

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

static wxULongLong wxDir::GetTotalSize ( const wxString dir,
wxArrayString filesSkipped = NULL 
) [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 can not be read, that file is added to the 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 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()
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.

bool wxDir::HasSubDirs ( const wxString dirspec = wxEmptyString  )  const

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

The hidden subdirectories are taken into account as well.

bool wxDir::IsOpened (  )  const

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

bool wxDir::Open ( const wxString dir  ) 

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

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

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 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.

For each found directory, sink.OnDir() is called and sink.OnFile() is called for every file. Depending on the return value, the enumeration may continue or stop.

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

See also:
GetAllFiles()
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines



wxWidgets logo

[ top ]