First attempt to document raw bitmap access

[wxWidgets.git] / interface / dir.h

diff --git a/interface/dir.h b/interface/dir.h
index 5077125fbc1b5eb1af24179d7ff1292ab267125c..cb9ca739175e89e4feb9fe08d6cc19e9d73f1ea1 100644 (file)
--- a/interface/dir.h
+++ b/interface/dir.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dir.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dir.h

-// Purpose:     documentation for wxDirTraverser class
+// Purpose:     interface of wxDirTraverser

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -9,128 +9,126 @@
 /**
     @class wxDirTraverser
     @wxheader{dir.h}
 /**
     @class wxDirTraverser
     @wxheader{dir.h}

-    
+

     wxDirTraverser is an abstract interface which must be implemented by objects
     passed to wxDir::Traverse function.
     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):
     Example of use (this works almost like wxDir::GetAllFiles):

-    
+

     @code
     class wxDirTraverserSimple : public wxDirTraverser
         {
         public:
             wxDirTraverserSimple(wxArrayString& files) : m_files(files) { }
     @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 OnFile(const wxString& filename)
             {
                 m_files.Add(filename);
                 return wxDIR_CONTINUE;
             }

-    
+

             virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
             {
                 return wxDIR_CONTINUE;
             }
             virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname))
             {
                 return wxDIR_CONTINUE;
             }

-    
+

         private:
             wxArrayString& m_files;
         };
         private:
             wxArrayString& m_files;
         };

-    
+

         // get the names of all files in the array
         wxArrayString files;
         wxDirTraverserSimple traverser(files);
         // get the names of all files in the array
         wxArrayString files;
         wxDirTraverserSimple traverser(files);

-    
+

         wxDir dir(dirname);
         dir.Traverse(traverser);
     @endcode
         wxDir dir(dirname);
         dir.Traverse(traverser);
     @endcode

-    
+

     @library{wxbase}
     @category{file}
 */
     @library{wxbase}
     @category{file}
 */

-class wxDirTraverser 
+class wxDirTraverser

 {
 public:
     /**
 {
 public:
     /**

-        This function is called for each directory. It may return @c wxSIR_STOP 
+        This function is called for each directory. It may return @c wxDIR_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.
         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
         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 
+        traversing (for example, if the file being searched is found) or

         @c wxDIR_CONTINUE to proceed.
         @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
         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 
+        enumerating. It may return @c wxDIR_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.
         @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);
 };
 
 
         The base class version always returns @c wxDIR_IGNORE.
     */
     virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname);
 };
 
 

+

 /**
     @class wxDir
     @wxheader{dir.h}
 /**
     @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 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 also provides a flexible way to enumerate files recursively using
+    wxDir::Traverse or a simpler

     wxDir::GetAllFiles function.
     wxDir::GetAllFiles function.

-    
+

     Example of use:
     Example of use:

-    
+

     @code
     wxDir dir(wxGetCwd());
     @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;
         }
         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:");
         puts("Enumerating object files in current directory:");

-    
+

         wxString filename;
         wxString filename;

-    
+

         bool cont = dir.GetFirst(, filespec, flags);
         while ( cont )
         {
             printf("%s\n", filename.c_str());
         bool cont = dir.GetFirst(, filespec, flags);
         while ( cont )
         {
             printf("%s\n", filename.c_str());

-    
+

             cont = dir.GetNext();
         }
     @endcode
             cont = dir.GetNext();
         }
     @endcode

-    
+

     @library{wxbase}
     @category{file}
 */
     @library{wxbase}
     @category{file}
 */

-class wxDir 
+class wxDir

 {
 public:
     //@{
     /**
 {
 public:
     //@{
     /**

-        Opens the directory for enumeration, use IsOpened() 
+        Opens the directory for enumeration, use IsOpened()

         to test for errors.
     */
     wxDir();
         to test for errors.
     */
     wxDir();

-        wxDir(const wxString& dir);
+    wxDir(const wxString& dir);

     //@}
 
     /**
     //@}
 
     /**


@@ -147,13 +145,11 @@ public:
     /**
         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 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 
+        The @a flags parameter may or may not include @c wxDIR_FILES, the
+        function always behaves as if it were specified. By default, @a 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
         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.
-        
+        the directory @a dirname itself.

         See also: Traverse()
     */
     static wxString FindFirst(const wxString& dirname,
         See also: Traverse()
     */
     static wxString FindFirst(const wxString& dirname,


@@ -161,45 +157,42 @@ public:
                               int flags = wxDIR_DEFAULT);
 
     /**
                               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
+        The function appends the names of all the files under directory @a dirname
+        to the array @a files (note that its old content is preserved). Only files
+        matching the @a filespec are taken, with empty spec matching all the files.
+        The @a 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).
         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,
         See also: Traverse()
     */
     static size_t GetAllFiles(const wxString& dirname,

-                              wxArrayString * files,
+                              wxArrayString* files,

                               const wxString& filespec = wxEmptyString,
                               int flags = wxDIR_DEFAULT);
 
     /**
                               const wxString& filespec = wxEmptyString,
                               int flags = wxDIR_DEFAULT);
 
     /**

-        Start enumerating all files matching @e filespec (or all files if it is
+        Start enumerating all files matching @a filespec (or all files if it is

         empty) and @e flags, return @true on success.
     */
     bool GetFirst(wxString* filename,
                   const wxString& filespec = wxEmptyString,
         empty) and @e flags, return @true on success.
     */
     bool GetFirst(wxString* filename,
                   const wxString& filespec = wxEmptyString,

-                  int flags = wxDIR_DEFAULT);
+                  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).
     */

-    wxString GetName();
+    wxString GetName() const;

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

-    bool GetNext(wxString* filename);
+    bool GetNext(wxString* filename) const;

 
     /**
         Returns the size (in bytes) of all files recursively found in @c dir or
         @c wxInvalidSize in case of error.
 
     /**
         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.
         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.


@@ -210,16 +203,15 @@ public:
         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.
         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,
         See also: wxFileName::GetHumanReadableSize,

-        wxGetDiskSpace
+        wxGetDiskSpace()

     */
     static wxULongLong GetTotalSize(const wxString& dir,
     */
     static wxULongLong GetTotalSize(const wxString& dir,

-                                    wxArrayString* filesSkipped = @NULL);
+                                    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
+        Returns @true if the directory contains any files matching the given
+        @e filespec. If @a 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);
         case, even hidden files are taken into account.
     */
     bool HasFiles(const wxString& filespec = wxEmptyString);


@@ -232,10 +224,10 @@ public:
     bool HasSubDirs(const wxString& dirspec = wxEmptyString);
 
     /**
     bool HasSubDirs(const wxString& dirspec = wxEmptyString);
 
     /**

-        Returns @true if the directory was successfully opened by a previous call to 
+        Returns @true if the directory was successfully opened by a previous call to

         Open().
     */
         Open().
     */

-    bool IsOpened();
+    bool IsOpened() const;

 
     /**
         Open the directory for enumerating, returns @true on success
 
     /**
         Open the directory for enumerating, returns @true on success


@@ -245,24 +237,21 @@ public:
 
     /**
         Enumerate all files and directories under the given directory recursively
 
     /**
         Enumerate all files and directories under the given directory recursively

-        calling the element of the provided wxDirTraverser 
+        calling the element of the provided wxDirTraverser

         object for each of them.
         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
+        More precisely, the function will really recurse into subdirectories if
+        @a flags contains @c wxDIR_DIRS flag. It will ignore the files (but

         still possibly recurse into subdirectories) if @c wxDIR_FILES flag is
         given.
         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.
         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.
         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);
 };
         See also: GetAllFiles()
     */
     size_t Traverse(wxDirTraverser& sink,
                     const wxString& filespec = wxEmptyString,
                     int flags = wxDIR_DEFAULT);
 };

+