X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c6cf894ae2dc66126724a9aee8ba5c62f4d9572a..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/textfile.h diff --git a/interface/wx/textfile.h b/interface/wx/textfile.h index 6d5b77183a..a2a9b1cdef 100644 --- a/interface/wx/textfile.h +++ b/interface/wx/textfile.h @@ -2,22 +2,23 @@ // Name: textfile.h // Purpose: interface of wxTextFile // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +// 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 +41,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 +54,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 +65,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 +89,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. @@ -134,11 +144,11 @@ public: @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). + under Windows and @c wxTextFileType_Unix under Unix (including Mac OS + X, the value @c wxTextFileType_Mac was only used for classic Mac OS + versions). */ - 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 +164,7 @@ public: // do something with the last line in str @endcode */ - wxString GetFirstLine() const; + wxString& GetFirstLine(); /** Gets the last line of the file. @@ -174,15 +184,19 @@ public: // 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. + The returned line may be modified when non-const method is used but you + shouldn't add line terminator at the end -- this will be done by + wxTextFile itself. */ - wxString GetLine(size_t n) const; + //@{ + wxString& GetLine(size_t n); + const wxString& GetLine(size_t n) const; + //@} /** Get the number of lines in the file. @@ -197,23 +211,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,31 +242,38 @@ 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. 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; - bool Open(const wxString& strFile, const wxMBConv& conv = wxConvAuto()) const; - //@} + bool Open(const wxMBConv& conv = wxConvAuto()); + + /** + 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()); /** 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 +283,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; };