No docs yet, just the bare interace so we can get XML for Phoenix.

[wxWidgets.git] / interface / wx / textfile.h

diff --git a/interface/wx/textfile.h b/interface/wx/textfile.h
index 55179ee8b648ea39ba0ccd7cc82a71ddf1d55cad..77c947945b15fb2c29918294d539de8b27a947eb 100644 (file)
--- a/interface/wx/textfile.h
+++ b/interface/wx/textfile.h
@@ -3,9 +3,23 @@
 // Purpose:     interface of wxTextFile
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxTextFile
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

+// TODO: document wxTextBuffer
+
+/**
+    The line termination type.
+*/
+enum wxTextFileType
+{
+    wxTextFileType_None,  //!< incomplete (the last line of the file only)
+    wxTextFileType_Unix,  //!< line is terminated with 'LF' = 0xA = 10 = '\\n'
+    wxTextFileType_Dos,   //!< line is terminated with 'CR' 'LF'
+    wxTextFileType_Mac,   //!< line is terminated with 'CR' = 0xD = 13 = '\\r'
+    wxTextFileType_Os2    //!< line is terminated with 'CR' 'LF'
+};
+

 /**
     @class wxTextFile
 
 /**
     @class wxTextFile
 


@@ -18,39 +32,31 @@
 
     One word of warning: the class is not at all optimized for big files and thus
     it will load the file entirely into memory when opened. Of course, you should
 
     One word of warning: the class is not at all optimized for big files and thus
     it will load the file entirely into memory when opened. Of course, you should

-    not
-    work in this way with large files (as an estimation, anything over 1 Megabyte is
-    surely too big for this class). On the other hand, it is not a serious
+    not work in this way with large files (as an estimation, anything over 1 Megabyte
+    is surely too big for this class). On the other hand, it is not a serious

     limitation for small files like configuration files or program sources
     which are well handled by wxTextFile.
 
     The typical things you may do with wxTextFile in order are:
 
     limitation for small files like configuration files or program sources
     which are well handled by wxTextFile.
 
     The typical things you may do with wxTextFile in order are:
 

-     Create and open it: this is done with either
-    wxTextFile::Create or wxTextFile::Open
-    function which opens the file (name may be specified either as the argument to
-    these functions or in the constructor), reads its contents in memory (in the
-    case of @c Open()) and closes it.
-     Work with the lines in the file: this may be done either with "direct
-    access" functions like wxTextFile::GetLineCount and
-    wxTextFile::GetLine (@e operator[] does exactly the same
-    but looks more like array addressing) or with "sequential access" functions
-    which include wxTextFile::GetFirstLine/
-    wxTextFile::GetNextLine and also
-    wxTextFile::GetLastLine/wxTextFile::GetPrevLine.
-    For the sequential access functions the current line number is maintained: it is
-    returned by wxTextFile::GetCurrentLine and may be
-    changed with wxTextFile::GoToLine.
-     Add/remove lines to the file: wxTextFile::AddLine and
-    wxTextFile::InsertLine add new lines while
-    wxTextFile::RemoveLine deletes the existing ones.
-    wxTextFile::Clear resets the file to empty.
-     Save your changes: notice that the changes you make to the file will @b not be
-    saved automatically; calling wxTextFile::Close or doing
-    nothing discards them! To save the changes you must explicitly call
-    wxTextFile::Write - here, you may also change the line
-    termination type if you wish.
-
+    - Create and open it: this is done with either wxTextFile::Create or wxTextFile::Open
+      function which opens the file (name may be specified either as the argument to
+      these functions or in the constructor), reads its contents in memory (in the
+      case of wxTextFile::Open()) and closes it.
+    - Work with the lines in the file: this may be done either with "direct
+      access" functions like wxTextFile::GetLineCount and wxTextFile::GetLine
+      (@e operator[] does exactly the same but looks more like array addressing)
+      or with "sequential access" functions which include wxTextFile::GetFirstLine,
+      wxTextFile::GetNextLine and also wxTextFile::GetLastLine, wxTextFile::GetPrevLine.
+      For the sequential access functions the current line number is maintained: it is
+      returned by wxTextFile::GetCurrentLine and may be changed with wxTextFile::GoToLine.
+    - Add/remove lines to the file: wxTextFile::AddLine and wxTextFile::InsertLine
+      add new lines while wxTextFile::RemoveLine deletes the existing ones.
+      wxTextFile::Clear resets the file to empty.
+    - Save your changes: notice that the changes you make to the file will @b not be
+      saved automatically; calling wxTextFile::Close or doing nothing discards them!
+      To save the changes you must explicitly call wxTextFile::Write - here, you may
+      also change the line termination type if you wish.

 
     @library{wxbase}
     @category{file}
 
     @library{wxbase}
     @category{file}


@@ -60,44 +66,59 @@
 class wxTextFile
 {
 public:
 class wxTextFile
 {
 public:

+    /**
+        Default type for current platform determined at compile time.
+     */
+    static const wxTextFileType typeDefault;
+
+    /**
+        Default constructor, use Create() or Open() with a file name parameter to
+        initialize the object.
+    */
+    wxTextFile();
+

     /**
         Constructor does not load the file into memory, use Open() to do it.
     */
     /**
         Constructor does not load the file into memory, use Open() to do it.
     */

-    wxTextFile(const wxString& strFile) const;
+    wxTextFile(const wxString& strFile);

 
     /**
         Destructor does nothing.
     */
 
     /**
         Destructor does nothing.
     */

-    ~wxTextFile() const;
+    virtual ~wxTextFile();

 
     /**
         Adds a line to the end of file.
     */
 
     /**
         Adds a line to the end of file.
     */

-    void AddLine(const wxString& str,
-                 wxTextFileType type = typeDefault) const;
+    void AddLine(const wxString& str, wxTextFileType type = typeDefault);

 
     /**
         Delete all lines from the file, set current line number to 0.
     */
 
     /**
         Delete all lines from the file, set current line number to 0.
     */

-    void Clear() const;
+    void Clear();
+
+    /**
+        Closes the file and frees memory, @b "losing all changes".
+        Use Write() if you want to save them.
+    */
+    bool Close();

 
     /**
 
     /**

-        Closes the file and frees memory, @b losing all changes. Use Write()
-        if you want to save them.
+        Creates the file with the name which was given in the
+        wxTextFile(const wxString&) constructor.
+        The array of file lines is initially empty.
+
+        It will fail if the file already exists, Open() should be used in this case.

     */
     */

-    bool Close() const;
+    bool Create();

 
 

-    //@{

     /**
     /**

-        Creates the file with the given name or the name which was given in the
-        @ref ctor() constructor. The array of file lines is initially
-        empty.
-        It will fail if the file already exists, Open() should
-        be used in this case.
+        Creates the file with the given name.
+        The array of file lines is initially empty.
+
+        It will fail if the file already exists, Open() should be used in this case.

     */
     */

-    bool Create() const;
-    const bool Create(const wxString& strFile) const;
-    //@}
+    bool Create(const wxString& strFile);

 
     /**
         Returns @true if the current line is the last one.
 
     /**
         Returns @true if the current line is the last one.


@@ -113,43 +134,66 @@ public:
     /**
         Returns the current line: it has meaning only when you're using
         GetFirstLine()/GetNextLine() functions, it doesn't get updated when
     /**
         Returns the current line: it has meaning only when you're using
         GetFirstLine()/GetNextLine() functions, it doesn't get updated when

-        you're using "direct access" functions like GetLine(). GetFirstLine() and
-        GetLastLine() also change the value of the current line, as well as
-        GoToLine().
+        you're using "direct access" functions like GetLine().
+        GetFirstLine() and GetLastLine() also change the value of the current line,
+        as well as GoToLine().

     */
     size_t GetCurrentLine() const;
 
     /**
     */
     size_t GetCurrentLine() const;
 
     /**

-        Get the line termination string corresponding to given constant. @e typeDefault
-        is
-        the value defined during the compilation and corresponds to the native format
-        of the platform, i.e. it will be wxTextFileType_Dos under Windows,
-        wxTextFileType_Unix under Unix (including Mac OS X when compiling with the
-        Apple Developer Tools) and wxTextFileType_Mac under Mac OS (including
-        Mac OS X when compiling with CodeWarrior).
+        Get the line termination string corresponding to given constant.
+
+        @e typeDefault is the value defined during the compilation and corresponds
+        to the native format of the platform, i.e. it will be @c wxTextFileType_Dos
+        under Windows, @c wxTextFileType_Unix under Unix (including Mac OS X when
+        compiling with the Apple Developer Tools) and @c wxTextFileType_Mac under
+        Mac OS (including Mac OS X when compiling with CodeWarrior).

     */
     */

-    static const char* GetEOL(wxTextFileType type = typeDefault) const;
+    static const wxChar* GetEOL(wxTextFileType type = typeDefault);

 
     /**
 
     /**

-        This method together with GetNextLine()
-        allows more "iterator-like" traversal of the list of lines, i.e. you may
-        write something like:
+        This method together with GetNextLine() allows more "iterator-like"
+        traversal of the list of lines, i.e. you may write something like:
+
+        @code
+        wxTextFile file;
+        ...
+        for ( str = file.GetFirstLine(); !file.Eof(); str = file.GetNextLine() )
+        {
+            // do something with the current line in str
+        }
+        // do something with the last line in str
+        @endcode

     */
     */

-    wxString GetFirstLine() const;
+    wxString& GetFirstLine();

 
     /**
 
     /**

-        Gets the last line of the file. Together with
-        GetPrevLine() it allows to enumerate the lines
+        Gets the last line of the file.
+
+        Together with GetPrevLine() it allows to enumerate the lines

         in the file from the end to the beginning like this:
         in the file from the end to the beginning like this:

+
+        @code
+        wxTextFile file;
+        ...
+        for ( str = file.GetLastLine();
+            file.GetCurrentLine() > 0;
+            str = file.GetPrevLine() )
+        {
+            // do something with the current line in str
+        }
+        // do something with the first line in str
+        @endcode

     */
     */

-    wxString GetLastLine();
+    wxString& GetLastLine();

 
     /**
 
     /**

-        Retrieves the line number @a n from the file. The returned line may be
-        modified but you shouldn't add line terminator at the end - this will be done
-        by wxTextFile.
+        Retrieves the line number @a n from the file.
+
+        The returned line may be modified but you shouldn't add line terminator
+        at the end - this will be done by wxTextFile.

     */
     */

-    wxString GetLine(size_t n) const;
+    wxString& GetLine(size_t n) const;

 
     /**
         Get the number of lines in the file.
 
     /**
         Get the number of lines in the file.


@@ -157,84 +201,97 @@ public:
     size_t GetLineCount() const;
 
     /**
     size_t GetLineCount() const;
 
     /**

-        Get the type of the line (see also wxTextFile::GetEOL)
+        Get the type of the line (see also wxTextFile::GetEOL).

     */
     wxTextFileType GetLineType(size_t n) const;
 
     /**
         Get the name of the file.
     */
     */
     wxTextFileType GetLineType(size_t n) const;
 
     /**
         Get the name of the file.
     */

-    const char* GetName() const;
+    const wxString& GetName() const;

 
     /**
 
     /**

-        Gets the next line (see GetFirstLine() for
-        the example).
+        Gets the next line (see GetFirstLine() for the example).

     */
     */

-    wxString GetNextLine();
+    wxString& GetNextLine();

 
     /**
         Gets the previous line in the file.
     */
 
     /**
         Gets the previous line in the file.
     */

-    wxString GetPrevLine();
+    wxString& GetPrevLine();

 
     /**
 
     /**

-        Changes the value returned by GetCurrentLine()
-        and used by wxTextFile::GetFirstLine/GetNextLine().
+        Changes the value returned by GetCurrentLine() and used by GetFirstLine()
+        and GetNextLine().

     */
     */

-    void GoToLine(size_t n) const;
+    void GoToLine(size_t n);

 
     /**
 
     /**

-        Guess the type of file (which is supposed to be opened). If sufficiently
-        many lines of the file are in DOS/Unix/Mac format, the corresponding value will
-        be returned. If the detection mechanism fails wxTextFileType_None is returned.
+        Guess the type of file (which is supposed to be opened).
+
+        If sufficiently many lines of the file are in DOS/Unix/Mac format,
+        the corresponding value will be returned.
+        If the detection mechanism fails @c wxTextFileType_None is returned.

     */
     wxTextFileType GuessType() const;
 
     /**
     */
     wxTextFileType GuessType() const;
 
     /**

-        Insert a line before the line number @e n.
+        Insert a line before the line number @a n.

     */
     void InsertLine(const wxString& str, size_t n,
     */
     void InsertLine(const wxString& str, size_t n,

-                    wxTextFileType type = typeDefault) const;
+                    wxTextFileType type = typeDefault);

 
     /**
         Returns @true if the file is currently opened.
     */
     bool IsOpened() const;
 
 
     /**
         Returns @true if the file is currently opened.
     */
     bool IsOpened() const;
 

-    //@{

     /**
     /**

-        )
-        Open() opens the file with the given name or the name which was given in the
-        @ref ctor() constructor and also loads file in memory on
-        success. It will fail if the file does not exist,
-        Create() should be used in this case.
-        The @e conv argument is only meaningful in Unicode build of wxWidgets when
+        Opens the file with the name which was given in the wxTextFile(const wxString&)
+        constructor and also loads file in memory on success.
+
+        It will fail if the file does not exist, Create() should be used in this case.
+
+        The @a conv argument is only meaningful in Unicode build of wxWidgets when
+        it is used to convert the file to wide character representation.
+    */
+    bool Open(const wxMBConv& conv = wxConvAuto()) const;
+
+    /**
+        Opens the file with the given name and also loads file in memory on success.
+
+        It will fail if the file does not exist, Create() should be used in this case.
+
+        The @a conv argument is only meaningful in Unicode build of wxWidgets when

         it is used to convert the file to wide character representation.
     */
         it is used to convert the file to wide character representation.
     */

-    bool Open() const;
-    const bool Open(const wxString& strFile) const;
-    //@}
+    bool Open(const wxString& strFile, const wxMBConv& conv = wxConvAuto()) const;

 
     /**
         Delete line number @a n from the file.
     */
 
     /**
         Delete line number @a n from the file.
     */

-    void RemoveLine(size_t n) const;
+    void RemoveLine(size_t n);

 
     /**
 
     /**

-        )
-        Change the file on disk. The @a typeNew parameter allows you to change the
-        file format (default argument means "don't change type") and may be used to
-        convert, for example, DOS files to Unix.
-        The @e conv argument is only meaningful in Unicode build of wxWidgets when
-        it is used to convert all lines to multibyte representation before writing them
+        Change the file on disk.
+
+        The @a typeNew parameter allows you to change the file format
+        (default argument means "don't change type") and may be used to convert,
+        for example, DOS files to Unix.
+
+        The @a conv argument is only meaningful in Unicode build of wxWidgets when
+        it is used to convert all lines to multibyte representation before writing

         them to physical file.
         them to physical file.

-        Returns @true if operation succeeded, @false if it failed.
+
+        @return
+            @true if operation succeeded, @false if it failed.

     */
     */

-    bool Write(wxTextFileType typeNew = wxTextFileType_None) const;
+    bool Write(wxTextFileType typeNew = wxTextFileType_None,
+               const wxMBConv& conv = wxConvAuto());

 
     /**
         The same as GetLine().
     */
 
     /**
         The same as GetLine().
     */

-    wxString operator[](size_t n) const;
+    wxString& operator[](size_t n) const;

 };
 
 };