QDir Class

Detailed Description

A QDir is used to manipulate path names, access information regarding paths and files, and manipulate the underlying file system. It can also be used to access Qt's resource system.

Qt uses "/" as a universal directory separator in the same way that "/" is used as a path separator in URLs. If you always use "/" as a directory separator, Qt will translate your paths to conform to the underlying operating system.

A QDir can point to a file using either a relative or an absolute path. Absolute paths begin with the directory separator (optionally preceded by a drive specification under Windows). Relative file names begin with a directory name or a file name and specify a path relative to the current directory.

Examples of absolute paths:

 QDir("/home/user/Documents")
 QDir("C:/Users")

On Windows, the second example above will be translated to C:\Users when used to access files.

Examples of relative paths:

 QDir("images/landscape.png")

You can use the isRelative() or isAbsolute() functions to check if a QDir is using a relative or an absolute file path. Call makeAbsolute() to convert a relative QDir to an absolute one.

Navigation and Directory Operations

A directory's path can be obtained with the path() function, and a new path set with the setPath() function. The absolute path to a directory is found by calling absolutePath().

The name of a directory is found using the dirName() function. This typically returns the last element in the absolute path that specifies the location of the directory. However, it can also return "." if the QDir represents the current directory.

 QDir("Documents/Letters/Applications").dirName() // "Applications"
 QDir().dirName()                                 // "."

The path for a directory can also be changed with the cd() and cdUp() functions, both of which operate like familiar shell commands. When cd() is called with the name of an existing directory, the QDir object changes directory so that it represents that directory instead. The cdUp() function changes the directory of the QDir object so that it refers to its parent directory; i.e. cd("..") is equivalent to cdUp().

Directories can be created with mkdir(), renamed with rename(), and removed with rmdir().

You can test for the presence of a directory with a given name by using exists(), and the properties of a directory can be tested with isReadable(), isAbsolute(), isRelative(), and isRoot().

The refresh() function re-reads the directory's data from disk.

Files and Directory Contents

Directories contain a number of entries, representing files, directories, and symbolic links. The number of entries in a directory is returned by count(). A string list of the names of all the entries in a directory can be obtained with entryList(). If you need information about each entry, use entryInfoList() to obtain a list of QFileInfo objects.

Paths to files and directories within a directory can be constructed using filePath() and absoluteFilePath(). The filePath() function returns a path to the specified file or directory relative to the path of the QDir object; absoluteFilePath() returns an absolute path to the specified file or directory. Neither of these functions checks for the existence of files or directory; they only construct paths.

 QDir directory("Documents/Letters");
 QString path = directory.filePath("contents.txt");
 QString absolutePath = directory.absoluteFilePath("contents.txt");

Files can be removed by using the remove() function. Directories cannot be removed in the same way as files; use rmdir() to remove them instead.

It is possible to reduce the number of entries returned by entryList() and entryInfoList() by applying filters to a QDir object. You can apply a name filter to specify a pattern with wildcards that file names need to match, an attribute filter that selects properties of entries and can distinguish between files and directories, and a sort order.

Name filters are lists of strings that are passed to setNameFilters(). Attribute filters consist of a bitwise OR combination of Filters, and these are specified when calling setFilter(). The sort order is specified using setSorting() with a bitwise OR combination of SortFlags.

You can test to see if a filename matches a filter using the match() function.

Filter and sort order flags may also be specified when calling entryList() and entryInfoList() in order to override previously defined behavior.

The Current Directory and Other Special Paths

Access to some common directories is provided with a number of static functions that return QDir objects. There are also corresponding functions for these that return strings:

The setCurrent() static function can also be used to set the application's working directory.

If you want to find the directory containing the application's executable, see QCoreApplication::applicationDirPath().

The drives() static function provides a list of root directories for each device that contains a filing system. On Unix systems this returns a list containing a single root directory "/"; on Windows the list will usually contain C:/, and possibly other drive letters such as D:/, depending on the configuration of the user's system.

Path Manipulation and Strings

Paths containing "." elements that reference the current directory at that point in the path, ".." elements that reference the parent directory, and symbolic links can be reduced to a canonical form using the canonicalPath() function.

Paths can also be simplified by using cleanPath() to remove redundant "/" and ".." elements.

It is sometimes necessary to be able to show a path in the native representation for the user's platform. The static toNativeSeparators() function returns a copy of the specified path in which each directory separator is replaced by the appropriate separator for the underlying operating system.

Examples

Check if a directory exists:

 QDir dir("example");
 if (!dir.exists())
     qWarning("Cannot find the example directory");

(We could also use the static convenience function QFile::exists().)

Traversing directories and reading a file:

 QDir dir = QDir::root();                 // "/"
 if (!dir.cd("tmp")) {                    // "/tmp"
     qWarning("Cannot find the \"/tmp\" directory");
 } else {
     QFile file(dir.filePath("ex1.txt")); // "/tmp/ex1.txt"
     if (!file.open(QIODevice::ReadWrite))
         qWarning("Cannot create the file %s", file.name());
 }

A program that lists all the files in the current directory (excluding symbolic links), sorted by size, smallest first:

 #include <QDir>
 #include <iostream>

 int main(int argc, char *argv[])
 {
     QCoreApplication app(argc, argv);
     QDir dir;
     dir.setFilter(QDir::Files | QDir::Hidden | QDir::NoSymLinks);
     dir.setSorting(QDir::Size | QDir::Reversed);

     QFileInfoList list = dir.entryInfoList();
     std::cout << "     Bytes Filename" << std::endl;
     for (int i = 0; i < list.size(); ++i) {
         QFileInfo fileInfo = list.at(i);
         std::cout << qPrintable(QString("%1 %2").arg(fileInfo.size(), 10)
                                                 .arg(fileInfo.fileName()));
         std::cout << std::endl;
     }
     return 0;
 }

 Q_CLEANUP_RESOURCE(myapp);

 Q_INIT_RESOURCE(myapp);

 inline void initMyResource() { Q_INIT_RESOURCE(myapp); }

 namespace MyNamespace
 {
     ...

     void myFunction()
     {
         initMyResource();
     }
 }