Member Function Documentation

[explicit] KDirWatch::KDirWatch(QObject *parent = nullptr)

Constructor.

Scanning begins immediately when a dir/file watch is added.

parent the parent of the QObject (or nullptr for parent-less KDataTools)

[override virtual noexcept] KDirWatch::~KDirWatch()

Destructor.

Stops scanning and cleans up.

void KDirWatch::addDir(const QString &path, KDirWatch::WatchModes watchModes = WatchDirOnly)

Adds a directory to be watched.

The directory does not have to exist. When watchModes is set to WatchDirOnly (the default), the signals dirty(), created(), deleted() can be emitted, all for the watched directory. When watchModes is set to WatchFiles, all files in the watched directory are watched for changes, too. Thus, the signals dirty(), created(), deleted() can be emitted. When watchModes is set to WatchSubDirs, all subdirs are watched using the same flags specified in watchModes (symlinks aren't followed). If the path points to a symlink to a directory, the target directory is watched instead. If you want to watch the link, use addFile().

path the path to watch

watchModes watch modes

See also KDirWatch::WatchMode.

void KDirWatch::addFile(const QString &file)

Adds a file to be watched. If it's a symlink to a directory, it watches the symlink itself.

file the file to watch

bool KDirWatch::contains(const QString &path) const

Check if a directory is being watched by this KDirWatch instance path the directory to check Returns true if the directory is being watched

[signal] void KDirWatch::created(const QString &path)

Emitted when a file or directory (being watched explicitly) is created. This is not emitted when creating a file is created in a watched directory.

path the path of the file or directory

See also setCreated().

QDateTime KDirWatch::ctime(const QString &path) const

Returns the time the directory/file was last changed.

path the file to check

Returns the date of the last modification

[signal] void KDirWatch::deleted(const QString &path)

Emitted when a file or directory is deleted.

The object is still watched for new creation.

path the path of the file or directory

See also setDeleted().

[signal] void KDirWatch::dirty(const QString &path)

Emitted when a watched object is changed. For a directory this signal is emitted when files therein are created or deleted. For a file this signal is emitted when its size or attributes change.

When you watch a directory, changes in the size or attributes of contained files may or may not trigger this signal to be emitted depending on which backend is used by KDirWatch.

The new ctime is set before the signal is emitted.

path the path of the file or directory

See also setDirty().

[static] bool KDirWatch::exists()

Returns true if there is an instance of KDirWatch.

See also KDirWatch::self().

KDirWatch::Method KDirWatch::internalMethod() const

Returns the preferred internal method to watch for changes.

bool KDirWatch::isStopped()

Is scanning stopped? After creation of a KDirWatch instance, this is false. Returns true when scanning stopped

void KDirWatch::removeDir(const QString &path)

Removes a directory from the list of scanned directories.

If specified path is not in the list this does nothing.

path the path of the dir to be removed from the list

void KDirWatch::removeFile(const QString &file)

Removes a file from the list of watched files.

If specified path is not in the list this does nothing.

file the file to be removed from the list

bool KDirWatch::restartDirScan(const QString &path)

Restarts scanning for specified path.

It doesn't notify about the changes (by emitting a signal). The ctime value is reset.

Call it when you are finished with big operations on that path, and when you have refreshed that path.

path the path to restart scanning

Returns true if the path is being watched, otherwise false

See also stopDirScan().

[static] KDirWatch *KDirWatch::self()

The KDirWatch instance usually globally used in an application. It is automatically deleted when the application exits.

However, you can create an arbitrary number of KDirWatch instances aside from this one - for those you have to take care of memory management.

This function returns an instance of KDirWatch. If there is none, it will be created.

Returns a KDirWatch instance

[slot] void KDirWatch::setCreated(const QString &path)

Emits created().

path the path of the file or directory

See also created().

[slot] void KDirWatch::setDeleted(const QString &path)

Emits deleted().

path the path of the file or directory

See also deleted().

[slot] void KDirWatch::setDirty(const QString &path)

Emits dirty().

path the path of the file or directory

See also dirty().

void KDirWatch::startScan(bool notify = false, bool skippedToo = false)

Starts scanning of all dirs in list.

notify If true, all changed directories (since stopScan() call) will be notified for refresh. If notify is false, all ctimes will be reset (except those who are stopped, but only if skippedToo is false) and changed dirs won't be notified. You can start scanning even if the list is empty. First call should be called with false or else all directories in list will be notified.

skippedToo if true, the skipped directories (scanning of which was stopped with stopDirScan() ) will be reset and notified for change. Otherwise, stopped directories will continue to be unnotified.

bool KDirWatch::stopDirScan(const QString &path)

Stops scanning the specified path.

The path is not deleted from the internal list, it is just skipped. Call this function when you perform an huge operation on this directory (copy/move big files or many files). When finished, call restartDirScan(path).

path the path to skip

Returns true if the path is being watched, otherwise false

See also restartDirScan().

void KDirWatch::stopScan()

Stops scanning of all directories in internal list.

The timer is stopped, but the list is not cleared.