|  | Home · Overviews · Examples |

# QDir Class Reference
[com.trolltech.qt.core module]

The `QDir` class provides access to directory structures and their contents. More...

## Detailed Description

The `QDir` class provides access to directory structures and their contents.

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:/Documents and Settings")

On Windows, the second of the examples above will be translated to `C:\My Documents` 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:

`QDir` | `QString` | Return Value
--- | --- | ---
`current` | `currentPath` | The application's working directory
`home` | `homePath` | The user's home directory
`root` | `rootPath` | The root directory
`temp` | `tempPath` | The system's temporary directory

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[])
        {
            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;
        }

See also `QFileInfo`, `QFile`, `QFileDialog`, `QApplication::applicationDirPath`, and Find Files Example.