From 1add55ae506f8523112895c9749187476d4ab473 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sun, 30 Mar 2008 23:34:30 +0000 Subject: [PATCH] s/NB:/@note; revised wxFFile git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52926 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/artprov.h | 2 +- interface/ffile.h | 122 +++++++++++++++++++++++++++++++------------ interface/grid.h | 2 +- interface/mimetype.h | 4 +- interface/xml/xml.h | 2 +- 5 files changed, 93 insertions(+), 39 deletions(-) diff --git a/interface/artprov.h b/interface/artprov.h index a54889c17d..e6e13df265 100644 --- a/interface/artprov.h +++ b/interface/artprov.h @@ -47,7 +47,7 @@ wxArtProvider::GetIcon. @todo IS THIS NB TRUE? - (NB: this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider + (@note this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too small). @section wxartprovider_identify Identifying art resources diff --git a/interface/ffile.h b/interface/ffile.h index 4f97fa6aea..da0722860e 100644 --- a/interface/ffile.h +++ b/interface/ffile.h @@ -6,15 +6,43 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + + +/** + Values used for both wxFile and wxFFile. + + @todo make the value names uppercase +*/ +enum wxSeekMode +{ + wxFromStart, + wxFromCurrent, + wxFromEnd +}; + +/** + See wxFFile::GetKind(). +*/ +enum wxFileKind +{ + wxFILE_KIND_UNKNOWN, + wxFILE_KIND_DISK, /**< A file supporting seeking to arbitrary offsets. */ + wxFILE_KIND_TERMINAL, /**< A terminal. */ + wxFILE_KIND_PIPE /**< A pipe. */ +}; + + /** @class wxFFile @wxheader{ffile.h} - wxFFile implements buffered file I/O. This is a very small class designed to - minimize the overhead of using it - in fact, there is hardly any overhead at - all, but using it brings you automatic error checking and hides differences - between platforms and compilers. It wraps inside it a @c FILE * handle used - by standard C IO library (also known as @c stdio). + wxFFile implements buffered file I/O. + + This is a very small class designed to minimize the overhead of using it - in fact, + there is hardly any overhead at all, but using it brings you automatic error checking + and hides differences between platforms and compilers. + + It wraps inside it a @c FILE * handle used by standard C IO library (also known as @c stdio). @library{wxbase} @category{file} @@ -24,10 +52,22 @@ class wxFFile { public: - //@{ + wxFFile(); + /** Opens a file with the given file pointer, which has already been opened. + @param fp + An existing file descriptor, such as stderr. + */ + wxFFile(FILE* fp); + + /** + Opens a file with the given mode. + As there is no way to return whether the operation was successful or not from + the constructor you should test the return value of IsOpened() to check that it + didn't fail. + @param filename The filename. @param mode @@ -35,24 +75,21 @@ public: Note that you should use "b" flag if you use binary files under Windows or the results might be unexpected due to automatic newline conversion done for the text files. - @param fp - An existing file descriptor, such as stderr. */ - wxFFile(); wxFFile(const wxString& filename, const wxString& mode = "r"); - wxFFile(FILE* fp); - //@} + /** Destructor will close the file. - NB: it is not virtual so you should @e not derive from wxFFile! + + @note it is not virtual so you should @e not derive from wxFFile! */ ~wxFFile(); /** Attaches an existing file pointer to the wxFFile object. - The descriptor should be already opened and it will be closed by wxFFile - object. + + The descriptor should be already opened and it will be closed by wxFFile object. */ void Attach(FILE* fp); @@ -63,21 +100,24 @@ public: /** Get back a file pointer from wxFFile object -- the caller is responsible for - closing the file if this - descriptor is opened. IsOpened() will return @false after call to Detach(). + closing the file if this descriptor is opened. + + IsOpened() will return @false after call to Detach(). */ void Detach(); /** Returns @true if the an attempt has been made to read @e past the end of the file. - Note that the behaviour of the file descriptor based class - wxFile is different as wxFile::Eof - will return @true here as soon as the last byte of the file has been - read. + + Note that the behaviour of the file descriptor based class wxFile is different as + wxFile::Eof() will return @true here as soon as the last byte of the file has been read. + Also note that this method may only be called for opened files and may crash if the file is not opened. + @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD + @see IsOpened() */ bool Eof() const; @@ -85,12 +125,15 @@ public: /** Returns @true if an error has occurred on this file, similar to the standard @c ferror() function. + Please note that this method may only be called for opened files and may crash if the file is not opened. + @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD + @see IsOpened() */ - + bool Error() const; /** Flushes the file and returns @true on success. @@ -98,14 +141,16 @@ public: bool Flush(); /** - Returns the type of the file. Possible return values are: + Returns the type of the file. + + @see wxFileKind */ wxFileKind GetKind() const; /** - Returns @true if the file is opened. Most of the methods of this class may - only - be used for an opened file. + Returns @true if the file is opened. + + Most of the methods of this class may only be used for an opened file. */ bool IsOpened() const; @@ -125,8 +170,7 @@ public: bool Open(const wxString& filename, const wxString& mode = "r"); /** - Reads the specified number of bytes into a buffer, returning the actual number - read. + Reads the specified number of bytes into a buffer, returning the actual number read. @param buffer A buffer to receive the data. @@ -138,7 +182,6 @@ public: size_t Read(void* buffer, size_t count); /** - ) Reads the entire contents of the file into a string. @param str @@ -149,7 +192,7 @@ public: @returns @true if file was read successfully, @false otherwise. */ - bool ReadAll(wxString* str); + bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto()); /** Seeks to the specified position and returns @true on success. @@ -163,8 +206,7 @@ public: /** Moves the file pointer to the specified number of bytes before the end of the - file - and returns @true on success. + file and returns @true on success. @param ofs Number of bytes before the end of the file. @@ -177,12 +219,24 @@ public: wxFileOffset Tell() const; /** - ) Writes the contents of the string to the file, returns @true on success. + The second argument is only meaningful in Unicode build of wxWidgets when - @e conv is used to convert @a s to multibyte representation. + @a conv is used to convert @a str to multibyte representation. + */ + bool Write(const wxString& str, const wxMBConv& conv = wxConvAuto()); + + /** + Writes the specified number of bytes from a buffer. + + @param buffer + A buffer containing the data. + @param count + The number of bytes to write. + + @returns The number of bytes written. */ - bool Write(const wxString& s); + size_t Write(const void* buffer, size_t count); /** Returns the file pointer associated with the file. diff --git a/interface/grid.h b/interface/grid.h index b4d63210e0..9d1eeb0ebc 100644 --- a/interface/grid.h +++ b/interface/grid.h @@ -1960,7 +1960,7 @@ public: void InitColWidths(); /** - NB: @e never access m_row/col arrays directly because they are created + @note @e never access m_row/col arrays directly because they are created on demand, @e always use accessor functions instead! Init the m_rowHeights/Bottoms arrays with default values. */ diff --git a/interface/mimetype.h b/interface/mimetype.h index 8e64ad2719..3e753b05f0 100644 --- a/interface/mimetype.h +++ b/interface/mimetype.h @@ -32,7 +32,7 @@ If GNOME or KDE desktop environment is installed, then wxMimeTypesManager gathers MIME information from respective files (e.g. .kdelnk files under KDE). - NB: Currently, wxMimeTypesManager is limited to reading MIME type information + @note Currently, wxMimeTypesManager is limited to reading MIME type information but it will support modifying it as well in future versions. @library{wxbase} @@ -63,7 +63,7 @@ public: void AddFallbacks(const wxFileTypeInfo* fallbacks); /** - NB: You won't normally need to use more than one wxMimeTypesManager object in a + @note You won't normally need to use more than one wxMimeTypesManager object in a program. @ref ctor() wxMimeTypesManager diff --git a/interface/xml/xml.h b/interface/xml/xml.h index 604daaa0ca..bc26ffb32f 100644 --- a/interface/xml/xml.h +++ b/interface/xml/xml.h @@ -440,7 +440,7 @@ public: /** Returns encoding of in-memory representation of the document (same as passed to Load() or constructor, defaults to UTF-8). - NB: this is meaningless in Unicode build where data are stored as @c wchar_t*. + @note this is meaningless in Unicode build where data are stored as @c wchar_t*. */ wxString GetEncoding() const; -- 2.45.2