class KDirWatch

# class KDirWatch | Class for watching directory and file changes. More...
Definition | `#include <kdirwatch.h>`
Inherits | QObject (qt) [public ]
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Methods

- KDirWatch (QObject* parent = 0, const char* name = 0)
- ~KDirWatch ()
- void addDir (const QString& path, bool watchFiles = false, bool recursive = false)
- void addFile (const QString& file)
- QDateTime ctime (const QString& path)
- void removeDir (const QString& path)
- void removeFile (const QString& file)
- bool stopDirScan (const QString& path)
- bool restartDirScan (const QString& path)
- void startScan ( bool notify=false, bool skippedToo=false )
- void stopScan ()
- bool isStopped ()
- bool contains ( const QString& path ) const
- void setCreated ( const QString& )
- void setDirty ( const QString& )
- void setDeleted ( const QString& )

#### Signals

- void dirty (const QString&)
- void created (const QString&)
- void deleted (const QString&)

#### Public Static Methods

- static void statistics ()
- static KDirWatch* self ()
- static bool exists ()

## Detailed Description

Watch directories and files for changes. The watched directories or files doesn't have to exist yet.

When a watched directory is changed, i.e. when files therein are created or deleted, KDirWatch will emit the signal dirty().

When a watched, but previously not existing directory gets created, KDirWatch will emit the signal created().

When a watched directory gets deleted, KDirWatch will emit the signal deleted(). The directory is still watched for new creation.

When a watched file is changed, i.e. attributes changed or written to, KDirWatch will emit the signal dirty().

Scanning of particular directories or files can be stopped temporarily and restarted. The whole class can be stopped and restarted. Directories and files can be added/removed from list in any state.

The implementation uses the FAM service when available; if FAM is not available, the DNOTIFY functionality is used on LINUX. As a last resort, a regular polling for change of modification times is done; the polling interval is a global config option: DirWatch/PollInterval and DirWatch/NFSPollInterval for NFS mounted directories.

KDirWatch (QObject* parent = 0, const char* name = 0) | ### KDirWatch

Constructor.

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

~KDirWatch () | ### ~KDirWatch

Destructor.

Stops scanning and cleans up.

void addDir (const QString& path, bool watchFiles = false, bool recursive = false) | ### addDir

Adds a directory to be watched.

The directory does not have to exist. When `watchFiles` is false (the default), the signals dirty(), created(), deleted() can be emitted, all for the watched directory. When `watchFiles` is true, all files in the watched directory are looked for changes, too. Thus, the signals fileDirty(), fileCreated(), fileDeleted() can be emitted. are looked for changes, too. Thus, the signals dirty(), created(), deleted() can be emitted.

When `recursive` is true, also all sub directories are watched.

void addFile (const QString& file) | ### addFile

Adds a file to be watched.

QDateTime ctime (const QString& path) | ### ctime

Returns the time the directory/file was last changed.

void removeDir (const QString& path) | ### removeDir

Removes a directory from the list of scanned directories.

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

void removeFile (const QString& file) | ### removeFile

Removes a file from the list of watched files.

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

bool stopDirScan (const QString& path) | ### stopDirScan

Stops scanning the specified path.

The `path` is not deleted from the interal just, 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). Returns `false` if specified path is not in list, `true` otherwise.

bool restartDirScan (const QString& path) | ### restartDirScan

Restarts scanning for specified path.

Resets ctime. It doesn't notify the change (by emitted a signal), since the ctime value is reset.

Call it when you are finished with big operations on that path, and when you have refreshed that path. Returns `false` if specified path is not in list, `true` otherwise.

void startScan ( bool notify=false, bool skippedToo=false ) | ### startScan

Starts scanning of all dirs in list.

If notify is `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. If `skippedToo` is true, the skipped directoris (scanning of which was stopped with stopDirScan() ) will be reset and notified for change. Otherwise, stopped directories will continue to be unnotified.

void stopScan () | ### stopScan

Stops scanning of all directories in internal list.

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

bool isStopped () | ### isStopped

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

bool contains ( const QString& path ) | ### contains

[const]

Check if a directory is being watched by this KDirWatch instance

void statistics () | ### statistics

[static]

Dump statistic information about all KDirWatch instances. This checks for consistency, too.

void setCreated ( const QString& ) | ### setCreated

void setDirty ( const QString& ) | ### setDirty

void setDeleted ( const QString& ) | ### setDeleted

KDirWatch* self () | ### self

[static]

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.

bool exists () | ### exists

[static]

Return true if KDirWatch::self() exists

void dirty (const QString&) | ### dirty

[signal]

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.

void created (const QString&) | ### created

[signal]

Emitted when a file or directory is created.

void deleted (const QString&) | ### deleted

[signal]

Emitted when a file or directory is deleted.

The object is still watched for new creation.

- Author: Sven Radej
- Generated: root on macppc.ports.openbsd.org on Sat Sep 6 10:36:57 2003, using kdoc 2.0a54.