[wxWidgets.git] / interface / dir.h

/////////////////////////////////////////////////////////////////////////////
// Name:        dir.h
// Purpose:     documentation for wxDirTraverser class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxDirTraverser
    @wxheader{dir.h}
    
    wxDirTraverser is an abstract interface which must be implemented by objects
    passed to wxDir::Traverse function.
    
    Example of use (this works almost like wxDir::GetAllFiles):
    
    @code
    class wxDirTraverserSimple : public wxDirTraverser
        {
        public:
            wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
    
            virtual wxDirTraverseResult OnFile(const wxString& filename)
            {
                m_files.Add(filename);
                return wxDIR_CONTINUE;
            }
    
            virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
            {
                return wxDIR_CONTINUE;
            }
    
        private:
            wxArrayString& m_files;
        };
    
        // get the names of all files in the array
        wxArrayString files;
        wxDirTraverserSimple traverser(files);
    
        wxDir dir(dirname);
        dir.Traverse(traverser);
    @endcode
    
    @library{wxbase}
    @category{file}
*/
class wxDirTraverser 
{
public:
    /**
        This function is called for each directory. It may return @c wxSIR_STOP 
        to abort traversing completely, @c wxDIR_IGNORE to skip this directory but
        continue with others or @c wxDIR_CONTINUE to enumerate all files and
        subdirectories in this directory.
        
        This is a pure virtual function and must be implemented in the derived class.
    */
    virtual wxDirTraverseResult OnDir(const wxString& dirname);

    /**
        This function is called for each file. It may return @c wxDIR_STOP to abort
        traversing (for example, if the file being searched is found) or 
        @c wxDIR_CONTINUE to proceed.
        
        This is a pure virtual function and must be implemented in the derived class.
    */
    virtual wxDirTraverseResult OnFile(const wxString& filename);

    /**
        This function is called for each directory which we failed to open for
        enumerating. It may return @c wxSIR_STOP to abort traversing completely,
        @c wxDIR_IGNORE to skip this directory but continue with others or 
        @c wxDIR_CONTINUE to retry opening this directory once again.
        
        The base class version always returns @c wxDIR_IGNORE.
    */
    virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname);
};


/**
    @class wxDir
    @wxheader{dir.h}
    
    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 
    wxDir::Traverse or a simpler 
    wxDir::GetAllFiles function.
    
    Example of use:
    
    @code
    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(, filespec, flags);
        while ( cont )
        {
            printf("%s\n", filename.c_str());
    
            cont = dir.GetNext();
        }
    @endcode
    
    @library{wxbase}
    @category{file}
*/
class wxDir 
{
public:
    //@{
    /**
        Opens the directory for enumeration, use IsOpened() 
        to test for errors.
    */
    wxDir();
        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.
    */
    ~wxDir();

    /**
        Test for existence of a directory with the given name
    */
    static bool Exists(const wxString& dir);

    /**
        The function returns the path of the first file matching the given @e filespec
        or an empty string if there are no files matching it.
        
        The @e flags parameter may or may not include @c wxDIR_FILES, the
        function always behaves as if it were specified. By default, @e flags 
        includes @c 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 @e dirname itself.
        
        See also: Traverse()
    */
    static wxString FindFirst(const wxString& dirname,
                              const wxString& filespec,
                              int flags = wxDIR_DEFAULT);

    /**
        The function appends the names of all the files under directory @e dirname 
        to the array @e files (note that its old content is preserved). Only files
        matching the @e filespec are taken, with empty spec matching all the files.
        
        The @e flags parameter should always include @c wxDIR_FILES or the array
        would be unchanged and should include @c wxDIR_DIRS flag to recurse into
        subdirectories (both flags are included in the value by default).
        
        See also: Traverse()
    */
    static size_t GetAllFiles(const wxString& dirname,
                              wxArrayString * files,
                              const wxString& filespec = wxEmptyString,
                              int flags = wxDIR_DEFAULT);

    /**
        Start enumerating all files matching @e filespec (or all files if it is
        empty) and @e flags, return @true on success.
    */
    bool GetFirst(wxString* filename,
                  const wxString& filespec = wxEmptyString,
                  int flags = wxDIR_DEFAULT);

    /**
        Returns the name of the directory itself. The returned string does not have the
        trailing path separator (slash or backslash).
    */
    wxString GetName();

    /**
        Continue enumerating files which satisfy the criteria specified by the last
        call to GetFirst().
    */
    bool GetNext(wxString* filename);

    /**
        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 be read,
        that file is added to the @c 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 @c filesSkipped-GetCount() 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
    */
    static wxULongLong GetTotalSize(const wxString& dir,
                                    wxArrayString* filesSkipped = @NULL);

    /**
        Returns @true if the directory contains any files matching the given 
        @e filespec. If @e filespec is empty, look for any files at all. In any
        case, even hidden files are taken into account.
    */
    bool HasFiles(const wxString& filespec = wxEmptyString);

    /**
        Returns @true if the directory contains any subdirectories (if a non
        empty @e filespec is given, only check for directories matching it).
        The hidden subdirectories are taken into account as well.
    */
    bool HasSubDirs(const wxString& dirspec = wxEmptyString);

    /**
        Returns @true if the directory was successfully opened by a previous call to 
        Open().
    */
    bool IsOpened();

    /**
        Open the directory for enumerating, returns @true on success
        or @false if an error occurred.
    */
    bool Open(const wxString& dir);

    /**
        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 
        @e flags contains @c wxDIR_DIRS flag. It will ignore the files (but
        still possibly recurse into subdirectories) if @c wxDIR_FILES flag is
        given.
        
        For each found directory, @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.
        
        The function returns the total number of files found or @c (size_t)-1 on
        error.
        
        See also: GetAllFiles()
    */
    size_t Traverse(wxDirTraverser& sink,
                    const wxString& filespec = wxEmptyString,
                    int flags = wxDIR_DEFAULT);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: dir.h
	3	// Purpose: documentation for wxDirTraverser class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxDirTraverser
	11	@wxheader{dir.h}
	12
	13	wxDirTraverser is an abstract interface which must be implemented by objects
	14	passed to wxDir::Traverse function.
	15
	16	Example of use (this works almost like wxDir::GetAllFiles):
	17
	18	@code
	19	class wxDirTraverserSimple : public wxDirTraverser
	20	{
	21	public:
	22	wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
	23
	24	virtual wxDirTraverseResult OnFile(const wxString& filename)
	25	{
	26	m_files.Add(filename);
	27	return wxDIR_CONTINUE;
	28	}
	29
	30	virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
	31	{
	32	return wxDIR_CONTINUE;
	33	}
	34
	35	private:
	36	wxArrayString& m_files;
	37	};
	38
	39	// get the names of all files in the array
	40	wxArrayString files;
	41	wxDirTraverserSimple traverser(files);
	42
	43	wxDir dir(dirname);
	44	dir.Traverse(traverser);
	45	@endcode
	46
	47	@library{wxbase}
	48	@category{file}
	49	*/
	50	class wxDirTraverser
	51	{
	52	public:
	53	/**
	54	This function is called for each directory. It may return @c wxSIR_STOP
	55	to abort traversing completely, @c wxDIR_IGNORE to skip this directory but
	56	continue with others or @c wxDIR_CONTINUE to enumerate all files and
	57	subdirectories in this directory.
	58
	59	This is a pure virtual function and must be implemented in the derived class.
	60	*/
	61	virtual wxDirTraverseResult OnDir(const wxString& dirname);
	62
	63	/**
	64	This function is called for each file. It may return @c wxDIR_STOP to abort
65	traversing (for example, if the file being searched is found) or
66	@c wxDIR_CONTINUE to proceed.
67
68	This is a pure virtual function and must be implemented in the derived class.
69	*/
70	virtual wxDirTraverseResult OnFile(const wxString& filename);
71
72	/**
73	This function is called for each directory which we failed to open for
74	enumerating. It may return @c wxSIR_STOP to abort traversing completely,
75	@c wxDIR_IGNORE to skip this directory but continue with others or
76	@c wxDIR_CONTINUE to retry opening this directory once again.
77
78	The base class version always returns @c wxDIR_IGNORE.
79	*/
80	virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname);
81	};
82
83
84	/**
85	@class wxDir
86	@wxheader{dir.h}
87
88	wxDir is a portable equivalent of Unix open/read/closedir functions which
89	allow enumerating of the files in a directory. wxDir allows to enumerate files
90	as well as directories.
91
92	wxDir also provides a flexible way to enumerate files recursively using
93	wxDir::Traverse or a simpler
94	wxDir::GetAllFiles function.
95
96	Example of use:
97
98	@code
99	wxDir dir(wxGetCwd());
100
101	if ( !dir.IsOpened() )
102	{
103	// deal with the error here - wxDir would already log an error message
104	// explaining the exact reason of the failure
105	return;
106	}
107
108	puts("Enumerating object files in current directory:");
109
110	wxString filename;
111
112	bool cont = dir.GetFirst(, filespec, flags);
113	while ( cont )
114	{
115	printf("%s\n", filename.c_str());
116
117	cont = dir.GetNext();
118	}
119	@endcode
120
121	@library{wxbase}
122	@category{file}
123	*/
124	class wxDir
125	{
126	public:
127	//@{
128	/**
129	Opens the directory for enumeration, use IsOpened()
130	to test for errors.
131	*/
132	wxDir();
133	wxDir(const wxString& dir);
134	//@}
135
136	/**
137	Destructor cleans up the associated resources. It is not virtual and so this
138	class is not meant to be used polymorphically.
139	*/
140	~wxDir();
141
142	/**
143	Test for existence of a directory with the given name
144	*/
145	static bool Exists(const wxString& dir);
146
147	/**
148	The function returns the path of the first file matching the given @e filespec
149	or an empty string if there are no files matching it.
150
151	The @e flags parameter may or may not include @c wxDIR_FILES, the
152	function always behaves as if it were specified. By default, @e flags
153	includes @c wxDIR_DIRS and so the function recurses into the subdirectories
154	but if this flag is not specified, the function restricts the search only to
155	the directory @e dirname itself.
156
157	See also: Traverse()
158	*/
159	static wxString FindFirst(const wxString& dirname,
160	const wxString& filespec,
161	int flags = wxDIR_DEFAULT);
162
163	/**
164	The function appends the names of all the files under directory @e dirname
165	to the array @e files (note that its old content is preserved). Only files
166	matching the @e filespec are taken, with empty spec matching all the files.
167
168	The @e flags parameter should always include @c wxDIR_FILES or the array
169	would be unchanged and should include @c wxDIR_DIRS flag to recurse into
170	subdirectories (both flags are included in the value by default).
171
172	See also: Traverse()
173	*/
174	static size_t GetAllFiles(const wxString& dirname,
175	wxArrayString * files,
176	const wxString& filespec = wxEmptyString,
177	int flags = wxDIR_DEFAULT);
178
179	/**
180	Start enumerating all files matching @e filespec (or all files if it is
181	empty) and @e flags, return @true on success.
182	*/
183	bool GetFirst(wxString* filename,
184	const wxString& filespec = wxEmptyString,
185	int flags = wxDIR_DEFAULT);
186
187	/**
188	Returns the name of the directory itself. The returned string does not have the
189	trailing path separator (slash or backslash).
190	*/
191	wxString GetName();
192
193	/**
194	Continue enumerating files which satisfy the criteria specified by the last
195	call to GetFirst().
196	*/
197	bool GetNext(wxString* filename);
198
199	/**
200	Returns the size (in bytes) of all files recursively found in @c dir or
201	@c wxInvalidSize in case of error.
202
203	In case it happens that while traversing folders a file's size can not be read,
204	that file is added to the @c filesSkipped array, if not @NULL, and then
205	skipped.
206	This usually happens with some special folders which are locked by the
207	operating system
208	or by another process. Remember that when @c filesSkipped-GetCount() is not
209	zero,
210	then the returned value is not 100% accurate and, if the skipped files were
211	big, it could be
212	far from real size of the directory.
213
214	See also: wxFileName::GetHumanReadableSize,
215	wxGetDiskSpace
216	*/
217	static wxULongLong GetTotalSize(const wxString& dir,
218	wxArrayString* filesSkipped = @NULL);
219
220	/**
221	Returns @true if the directory contains any files matching the given
222	@e filespec. If @e filespec is empty, look for any files at all. In any
223	case, even hidden files are taken into account.
224	*/
225	bool HasFiles(const wxString& filespec = wxEmptyString);
226
227	/**
228	Returns @true if the directory contains any subdirectories (if a non
229	empty @e filespec is given, only check for directories matching it).
230	The hidden subdirectories are taken into account as well.
231	*/
232	bool HasSubDirs(const wxString& dirspec = wxEmptyString);
233
234	/**
235	Returns @true if the directory was successfully opened by a previous call to
236	Open().
237	*/
238	bool IsOpened();
239
240	/**
241	Open the directory for enumerating, returns @true on success
242	or @false if an error occurred.
243	*/
244	bool Open(const wxString& dir);
245
246	/**
247	Enumerate all files and directories under the given directory recursively
248	calling the element of the provided wxDirTraverser
249	object for each of them.
250
251	More precisely, the function will really recurse into subdirectories if
252	@e flags contains @c wxDIR_DIRS flag. It will ignore the files (but
253	still possibly recurse into subdirectories) if @c wxDIR_FILES flag is
254	given.
255
256	For each found directory, @ref wxDirTraverser::ondir sink.OnDir is called
257	and @ref wxDirTraverser::onfile sink.OnFile is called for every file.
258	Depending on the return value, the enumeration may continue or stop.
259
260	The function returns the total number of files found or @c (size_t)-1 on
261	error.
262
263	See also: GetAllFiles()
264	*/
265	size_t Traverse(wxDirTraverser& sink,
266	const wxString& filespec = wxEmptyString,
267	int flags = wxDIR_DEFAULT);
268	};