wxFile may be used for low-level input/output. It contains all the usual functions to work with integer file descriptors (opening/closing, reading/writing, seeking, and so on), but unlike the standard C functions, it reports errors via wxLog and closes the file automatically in the destructor. wxFFile brings similar benefits but uses buffered input/output and contains a pointer to a FILE handle.

You can create a wxFile object by using the default constructor followed by Create or Open, or you can use the constructor that takes a file name and open mode (wxFile::read, wxFile::write, or wxFile::read_write). You can also create a wxFile from an existing file descriptor, passed to the constructor or Attach function. A wxFile can be closed with Close, which is called automatically (if necessary) when the object is destroyed.

You can get data from the object with Read, passing a void* buffer and the number of bytes to read. Read will return the actual number of bytes read, or wxInvalidOffset if there was an error. Use Write to write a void* buffer or wxString to the file, calling Flush if you need the data to be written to the file immediately.

To test for the end of the file, use Eof, which will return true if the file pointer is at the end of the file. (In contrast, wxFFile’s Eof will return true only if an attempt has been made to read past the end of the file.) You can determine the length of the file with Length.

Seek and SeekEnd seek to a position in the file, taking an offset specified as starting from the beginning or end of the file, respectively. Tell returns the current offset from the start of the file as a wxFileOffset (a 64-bit integer if the platform supports it, or else a 32-bit integer).

Call the static Access function to determine whether a file can be opened in a given mode. Exists is another static function that tests the existence of the given file.

The following code fragment uses wxFile to open a data file and read all the data into an array.

To illustrate file writing, here’s a function that will dump the contents of a text control to a file.

wxTextFile provides a very straightforward way to read and write small files and process them line-by-line.

Use Open to read a file into memory and split it into lines, and use Write to save it. You can use GetLine or the array operator to retrieve a specified line, or you can iterate through the file with GetFirstLine, GetNextLine, and GetPrevLine. Add lines to the file with AddLine or InsertLine, and remove lines by passing the line number to RemoveLine. You can clear the whole file with Clear.

In the following example, each line of a file is prepended with a given string before being written back to the same file.

wxTempFile is derived from wxFile and uses a temporary file to write data, not writing to the actual file until Commit is called. When you write a user’s data, it’s a good idea to write to a temporary file because if an error occurs during the save operation (such as a power failure, program bug, or other cataclysm), this error will not corrupt the current file on disk.

wxDir is a portable equivalent of the Unix open/read/closedir functions, which support enumeration of the files in a directory. wxDir supports enumeration of files as well as directories. It also provides a flexible way to enumerate files recursively using Traverse or the simpler GetAllFiles function.

After opening a file with Open (or by passing a path to the constructor), call GetFirst passing a pointer to a string to receive the found file name. You can also pass a file specification (defaulting to the empty string to match all files) and optional flags. Then call GetNext until there are no more matching files and the function returns false. The file specification can contain wildcards, such as “*” (match any number of characters) and “?” (match one character). For the flags argument, pass a bit-list of wxDIR_FILES (match files), wxDIR_DIRS (match directories), wxDIR_HIDDEN (match hidden files), and wxDIR_DOTDOT (match “.” and “..”). The default is to match everything except “.” and “..”.

Here’s an example of its use:

Note that if there is a problem when enumerating files—for example, if the directory does not exist—wxDir will generate a log message. To suppress this behavior, use the wxLogNull object to temporarily disable logging:

wxFileName models the name of a file; it can parse and reconstitute the components of a file name, and it also provides a variety of file operations, some of which are static functions. Here are some examples of what you can do with this class. Please see the reference manual for the many other operations.

The most commonly used file functions are listed in Table 14-1, and are defined in wx/filefn.h. See also the wxFileName class, especially the static functions you can use without constructing a wxFileName object, such as wxFileName::FileExists.

wxWidgets also wraps many of the standard C file functions, such as wxFopen, wxFputc, and wxSscanf. These are not currently documented, but their definitions may be found in include/wx/wxchar.h in your wxWidgets distribution.

It’s also useful to know about the wxFILE_SEP_PATH symbol, which is the appropriate path separator for the platform on which the application is running (for example, backslash on Windows and forward slash on Unix-based systems).

wxFileInputStream and wxFileOutputStream are based on the wxFile class and can be initialized from a file name, a wxFile object, or an integer file descriptor. Here’s an example of using wxFileInputStream to read in some data, seek to the beginning of the stream, and retrieve the current position.

Using wxFileOutputStream is similarly straightforward. The following code uses a wxFileInputStream and wxFileOutputStream to make a copy of a file, writing in 1024-byte chunks for efficiency. Error checking has been omitted for the sake of brevity.

wxFFileInputStream and wxFFileOutputStream are identical to wxFileInputStream and wxFileOutputStream, except that they are based on the wxFFile class instead of wxFile. They can therefore be initialized from a FILE pointer or wxFFile object. The behavior of end-of-file handling also differs: wxFileInputStream will report wxSTREAM_EOF after having read the last byte, whereas wxFFileInputStream will report wxSTREAM_EOF after trying to read past the last byte.

wxMemoryInputStream and wxMemoryOutputStream use an internal buffer for streaming data. The constructors for both of these classes take a char* buffer and size, which can be omitted to let the class allocate space dynamically. We’ll see a memory stream being used shortly.

wxStringInputStream takes a wxString reference from which data is to be read. wxStringOutputStream takes an optional wxString pointer to which to stream the data; if this is omitted, an internal string is created that can be accessed with GetString.

So far, we’ve described stream classes that access raw bytes, which must be converted to something useful by the application. To help with this process, you can use four classes to read and write data at a higher level: wxTextInputStream, wxTextOutputStream, wxDataInputStream, and wxDataOutput Stream. Objects of these classes are constructed by referring to existing streams, and they provide insertion and extraction operators for use with a variety of C++ types.

wxTextInputStream reads data from a human-readable text file. If you’re scanning through a file using wxTextInputStream, you should check for end of file before reading the next item. You should be prepared, however, to receive an empty item (such as an empty string or zero number) at the end of the file. This issue is unavoidable because most files end with white space, usually a newline. Here’s an example of using a wxTextInputStream in conjunction with wxFileInputStream:

wxTextOutputStream writes text data to an output stream, using the native line-ending format by default. The following example writes to the standard error stream.

wxDataInputStream and wxDataOutputStream are similar but write binary data. The data is streamed in a portable way so that the same data files can be read and written, regardless of platform. Here’s an example of reading from a data file.

And to write the data:

wxSocketOutputStream and wxSocketInputStream are initialized from a wxSocket object; see Chapter 18 for more details.

wxFilterInputStream and wxFilterOutputStream are base classes for streams that can be placed on top of other streams. wxZlibInputStream is an example. If you pass an input stream that has been created from a zlib or glib file, you can read data from the wxZlibInputStream without worrying about the mechanics of decompression. Similarly, you can create a wxZlibOutputStream passing an output stream such as wxFileOutputStream—writing data to the wxZlibOutput Stream will cause it to be compressed and sent to the wxFileOutputStream.

The following example compresses a string of data (buf) into a memory stream and then copies the compressed data to a permanent storage area (data).

wxZipInputStream is a more complex kind of stream, working on an archive, not just a linear stream of data. In fact, archives are handled by a comprehensive suite of classes including wxArchiveClassFactory and wxArchiveEntry, but you can read and write zip files without using these directly. To use wxZipInputStream, you can create the stream either from a wxInputStream, which has itself opened the archive, or by explicitly specifying the archive file name plus the file name within the archive. Both methods are illustrated in the following example, where string data is read from one or more files in the archive (first example) or a single specified file (second example).

wxZipOutputStream is the class for writing to zip files. PutNextEntry or PutNextDirEntry is used to create a new entry in the zip file, and then the entry’s data can be written. For example:

wxWidgets provides a virtual file system capability that enables an application to read data from a variety of sources as if it were dealing with ordinary files. It supports reading from a zip file, from memory, and from HTTP and FTP locations. Although it can’t be used for storing editable documents because it’s mainly a read-only mechanism, you could, for example, use it for accessing resources in a single zip archive. wxHtmlWindow, the wxWidgets HTML help controller, and the XRC resource system recognize virtual file system locations. Virtual file systems can be more convenient to work with than the archive classes mentioned in the last section, but the latter have the advantage of being able to write to archives. Although both systems use streams, they are otherwise unrelated.

The different virtual file systems are implemented by classes derived from wxFileSystemHandler, and instances of these classes need to be added via wxFileSystem::AddHandler (usually in the application’s OnInit function) before the file systems can be used. Usually all interaction with the file system happens through a wxFileSystem object, but occasionally a handler provides functions that can be used directly by the application, such as wxMemoryFSHandler’s AddFile and RemoveFile.

Before getting into the details of how an application can interact with the file system API in C++, let’s look at a couple of ways that we can use virtual file systems implicitly through other wxWidgets subsystems. Here’s an example of a URL that can be used in an HTML file displayed by wxHtmlWindow:

The part before the hash (#) is the name of the archive, and the part after the hash is the name of the file system protocol followed by the location of the file within the zip archive.

Similarly, we can specify a virtual file location in an XRC file:

In these examples, the code to use the virtual file system is hidden in the wxHtmlWindow and XRC implementations. To use virtual file systems directly, you use the wxFileSystem and wxFSFile classes. In the following snippet, a wxBitmap is loaded from an image in a zip archive. When the application initializes, the wxZipFSHandler is registered with wxFileSystem. An instance of wxFileSystem, which can be temporary or can last the lifetime of the application, is used to open the file logo.png from within the myapp.bin archive. The wxFSFile object returned is queried for the associated stream, which is used to read in the image (because wxImage is stream-aware). The image is converted to a wxBitmap, and the wxFSFile and wxFileSystem objects are deleted.

Note that you must pass a URL, not a regular file name, to wxFileSystem:: OpenFile. When specifying an absolute file location on the left side of a URL, you should use the form file:/<hostname>//<file>, and if there is no hostname, three slashes should still be used. You can convert from a file name to a URL using wxFileSystem::FileNameToURL and back again with wxFileSystem::URLToFileName.

As a further demonstration of using zip archives, LoadTextResource (as shown in the following example) loads an ASCII text file (such as an HTML file) into the variable text, given an archive file name and the name of the text file within the archive.

The wxMemoryFSHandler allows you to store data in the application’s memory and uses the memory protocol name. Obviously your application has to be careful not to store enormous amounts of data in memory, but it can be very handy when writing to actual disk files is not appropriate or efficient. For example, when previewing XRC dialogs, DialogBlocks adds to memory the bitmaps shown when a user-defined bitmap is not available. These bitmaps don’t exist anywhere on disk, but they can still be referenced by the XRC as if they were files:

wxMemoryFSHandler has an overloaded AddFile function that takes a file name argument and a wxImage, wxBitmap, wxString, or void* data argument. When you no longer need that data in memory, you can remove it with RemoveFile. For example:

The third and final virtual file system handler supported by wxWidgets is wxInternetFSHandler, which handles the FTP and HTTP protocols.