]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/textfile.h
update for bakefile 0.2.6
[wxWidgets.git] / interface / wx / textfile.h
index 6d5b77183a93a3de8fe0ab93fc25f45eb66ddb37..32cc79bf6b4f7b8ec0541ce64cf26f0ee36d4d3e 100644 (file)
@@ -6,18 +6,20 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+// TODO: document wxTextBuffer
 
-/** The line termination type (kept wxTextFileType name for compability) */
+/**
+    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_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_Mac,   //!< line is terminated with 'CR' = 0xD = 13 = '\\r'
     wxTextFileType_Os2    //!< line is terminated with 'CR' 'LF'
 };
 
-
 /**
     @class wxTextFile
 
@@ -40,7 +42,7 @@ enum wxTextFileType
     - 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.
+      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)
@@ -53,10 +55,9 @@ enum wxTextFileType
       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 callwxTextFile::Write - here, you may
+      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}
 
@@ -65,6 +66,11 @@ enum wxTextFileType
 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.
@@ -84,30 +90,35 @@ public:
     /**
         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.
     */
-    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() const;
+    bool Close();
 
-    //@{
     /**
-        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.
+        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 Create() const;
-    bool Create(const wxString& strFile) const;
-    //@}
+    bool Create();
+
+    /**
+        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 wxString& strFile);
 
     /**
         Returns @true if the current line is the last one.
@@ -138,7 +149,7 @@ public:
         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"
@@ -154,7 +165,7 @@ public:
         // do something with the last line in str
         @endcode
     */
-    wxString GetFirstLine() const;
+    wxString& GetFirstLine();
 
     /**
         Gets the last line of the file.
@@ -174,7 +185,7 @@ public:
         // do something with the first line in str
         @endcode
     */
-    wxString GetLastLine();
+    wxString& GetLastLine();
 
     /**
         Retrieves the line number @a n from the file.
@@ -182,7 +193,7 @@ public:
         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.
@@ -197,23 +208,23 @@ public:
     /**
         Get the name of the file.
     */
-    const char* GetName() const;
+    const wxString& GetName() const;
 
     /**
         Gets the next line (see GetFirstLine() for the example).
     */
-    wxString GetNextLine();
+    wxString& GetNextLine();
 
     /**
         Gets the previous line in the file.
     */
-    wxString GetPrevLine();
+    wxString& GetPrevLine();
 
     /**
         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).
@@ -228,17 +239,16 @@ public:
         Insert a line before the line number @a 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;
 
-    //@{
     /**
-        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.
+        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.
 
@@ -246,13 +256,21 @@ public:
         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.
+    */
     bool Open(const wxString& strFile, const wxMBConv& conv = wxConvAuto()) const;
-    //@}
 
     /**
         Delete line number @a n from the file.
     */
-    void RemoveLine(size_t n) const;
+    void RemoveLine(size_t n);
 
     /**
         Change the file on disk.
@@ -262,18 +280,18 @@ public:
         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
+        it is used to convert all lines to multibyte representation before writing
         them to physical file.
 
         @return
             @true if operation succeeded, @false if it failed.
     */
     bool Write(wxTextFileType typeNew = wxTextFileType_None,
-               const wxMBConv& conv = wxConvAuto()) const;
+               const wxMBConv& conv = wxConvAuto());
 
     /**
         The same as GetLine().
     */
-    wxString operator[](size_t n) const;
+    wxString& operator[](size_t n) const;
 };