added wxDir::FindFirst() (modified patch 1525502)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@40578 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -48,6 +48,10 @@ Major changes in 2.7 release
 2.7.1
 -----
 
+All:
+
+- Added wxDir::FindFirst() (Francesco Montorsi)
+
 All (GUI):
 
 - Added wxID_PAGE_SETUP standard id

docs/latex/wx/dir.tex

@@ -116,6 +116,22 @@ subdirectories (both flags are included in the value by default).
 See also: \helpref{Traverse}{wxdirtraverse}
 
 
+\membersection{wxDir::FindFirst}\label{wxdirfindfirst}
+
+\func{static wxString}{FindFirst}{\param{const wxString\& }{dirname}, \param{const wxString\& }{filespec}, \param{int }{flags = wxDIR\_DEFAULT}}
+
+The function returns the path of the first file matching the given \arg{filespec}
+or an empty string if there are no files matching it.
+
+The \arg{flags} parameter may or may not include {\tt wxDIR\_FILES}, the
+function always behaves as if it were specified. By default, \arg{flags} 
+includes {\tt 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 \arg{dirname} itself.
+
+See also: \helpref{Traverse}{wxdirtraverse}
+
+
 \membersection{wxDir::GetFirst}\label{wxdirgetfirst}
 
 \constfunc{bool}{GetFirst}{\param{wxString* }{filename}, \param{const wxString\& }{filespec = wxEmptyString}, \param{int }{flags = wxDIR\_DEFAULT}}

include/wx/dir.h

@@ -138,6 +138,13 @@ public:
                               const wxString& filespec = wxEmptyString,
                               int flags = wxDIR_DEFAULT);
 
+    // check if there any files matching the given filespec under the given
+    // directory (i.e. searches recursively), return the file path if found or
+    // empty string otherwise
+    static wxString FindFirst(const wxString& dirname,
+                              const wxString& filespec,
+                              int flags = wxDIR_DEFAULT);
+
 private:
     friend class wxDirData;
 

src/common/dircmn.cpp

@@ -236,3 +236,51 @@ size_t wxDir::GetAllFiles(const wxString& dirname,
 
     return nFiles;
 }
+
+// ----------------------------------------------------------------------------
+// wxDir::FindFirst()
+// ----------------------------------------------------------------------------
+
+class wxDirTraverserFindFirst : public wxDirTraverser
+{
+public:
+    wxDirTraverserFindFirst() { }
+
+    virtual wxDirTraverseResult OnFile(const wxString& filename)
+    {
+        m_file = filename;
+        return wxDIR_STOP;
+    }
+
+    virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
+    {
+        return wxDIR_CONTINUE;
+    }
+
+    const wxString& GetFile() const
+    {
+        return m_file;
+    }
+
+private:
+    wxString m_file;
+
+    DECLARE_NO_COPY_CLASS(wxDirTraverserFindFirst)
+};
+
+/* static */
+wxString wxDir::FindFirst(const wxString& dirname,
+                          const wxString& filespec,
+                          int flags)
+{
+    wxDir dir(dirname);
+    if ( dir.IsOpened() )
+    {
+        wxDirTraverserFindFirst traverser;
+
+        dir.Traverse(traverser, filespec, flags | wxDIR_FILES);
+        return traverser.GetFile();
+    }
+
+    return wxEmptyString;
+}