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:

QDirQStringReturn Value
currentcurrentPathThe application's working directory
homehomePathThe user's home directory
rootrootPathThe root directory
temptempPathThe 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.


Copyright © 2007 Trolltech Trademarks
Qt Jambi 4.3.2_01