KDirWatch Class Reference

`#include <kdirwatch.h>`

Inherits QObject.

## Public Types

enum | Method { FAM, DNotify, Stat, INotify }

## Signals

void | dirty (const QString &path)
void | created (const QString &path)
void | deleted (const QString &path)

## Public Member Functions

| 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 &path)
void | setDirty (const QString &path)
void | setDeleted (const QString &path)
Method | internalMethod ()

## Static Public Member Functions

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

## Detailed Description

Watch directories and files for changes.

The watched directories or files don'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 the 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.

See also
  self() Class for watching directory and file changes.

Author
  Sven Radej sven@.nosp@m.lisa.nosp@m..exp..nosp@m.univ.nosp@m.ie.ac.nosp@m..at

Definition at line 63 of file kdirwatch.h.

## Constructor & Destructor Documentation

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

Constructor.

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

Parameters

  parent | the parent of the QObject (or 0 for parent-less KDataTools)
  name | the name of the QObject, can be 0

Definition at line 1603 of file kdirwatch.cpp.

KDirWatch::~KDirWatch | ( |  | ) |

Destructor.

Stops scanning and cleans up.

Definition at line 1621 of file kdirwatch.cpp.

## Member Function Documentation

void KDirWatch::addDir | ( | const QString & | path,
|  | bool | watchFiles = `false`,
|  | bool | recursive = `false`
| ) |  |

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 watched for changes, too. Thus, the signals dirty(), created(), deleted() can be emitted.

Parameters

  path | the path to watch
  watchFiles | if true, the KDirWatch will also watch files - NOT IMPLEMENTED YET
  recursive | if true, all sub directories are also watched - NOT IMPLEMENTED YET

Definition at line 1634 of file kdirwatch.cpp.

void KDirWatch::addFile | ( | const QString & | file | ) |

Adds a file to be watched.

Parameters

  file | the file to watch

Definition at line 1643 of file kdirwatch.cpp.

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

Check if a directory is being watched by this KDirWatch instance.

Parameters

  path | the directory to check

Returns
  true if the directory is being watched

Definition at line 1703 of file kdirwatch.cpp.

void KDirWatch::created | ( | const QString & | path | ) |

signal

Emitted when a file or directory is created.

Parameters

  path | the path of the file or directory

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

Returns the time the directory/file was last changed.

Parameters

  path | the file to check

Returns
  the date of the last modification

Definition at line 1648 of file kdirwatch.cpp.

void KDirWatch::deleted | ( | const QString & | path | ) |

signal

Emitted when a file or directory is deleted.

The object is still watched for new creation.

Parameters

  path | the path of the file or directory

void KDirWatch::dirty | ( | const QString & | path | ) |

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.

Parameters

  path | the path of the file or directory

bool KDirWatch::exists | ( |  | ) |

static

Returns true if there is an instance of KDirWatch.

Returns
  true if there is an instance of KDirWatch.

See also
  KDirWatch::self()

Since
  3.1

Definition at line 1598 of file kdirwatch.cpp.

KDirWatch::Method KDirWatch::internalMethod | ( |  | ) |

Returns the preferred internal method to watch for changes.

Since
  3.2

Definition at line 1744 of file kdirwatch.cpp.

bool KDirWatch::isStopped | ( |  | ) |

inline

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

Returns
  true when scanning stopped

Definition at line 190 of file kdirwatch.h.

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.

Parameters

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

Definition at line 1660 of file kdirwatch.cpp.

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.

Parameters

  file | the file to be removed from the list

Definition at line 1665 of file kdirwatch.cpp.

bool KDirWatch::restartDirScan | ( | const QString & | path | ) |

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.

Parameters

  path | the path to restart scanning

Returns
  true if the `path` is being watched, otherwise false

See also
  stopDirScanning()

Definition at line 1679 of file kdirwatch.cpp.

KDirWatch * KDirWatch::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.

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

Returns
  a KDirWatch instance

Definition at line 1589 of file kdirwatch.cpp.

void KDirWatch::setCreated | ( | const QString & | path | ) |

Emits created().

Parameters

  path | the path of the file or directory

Definition at line 1726 of file kdirwatch.cpp.

void KDirWatch::setDeleted | ( | const QString & | path | ) |

Emits deleted().

Parameters

  path | the path of the file or directory

Definition at line 1738 of file kdirwatch.cpp.

void KDirWatch::setDirty | ( | const QString & | path | ) |

Emits dirty().

Parameters

  path | the path of the file or directory

Definition at line 1732 of file kdirwatch.cpp.

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

Starts scanning of all dirs in list.

Parameters

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

Definition at line 1696 of file kdirwatch.cpp.

void KDirWatch::statistics | ( |  | ) |

static

Dump statistic information about all KDirWatch instances.

This checks for consistency, too.

Definition at line 1716 of file kdirwatch.cpp.

bool KDirWatch::stopDirScan | ( | const QString & | path | ) |

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).

Parameters

  path | the path to skip

Returns
  true if the `path` is being watched, otherwise false

See also
  restartDirScanning()

Definition at line 1670 of file kdirwatch.cpp.

void KDirWatch::stopScan | ( |  | ) |

Stops scanning of all directories in internal list.

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

Definition at line 1690 of file kdirwatch.cpp.

The documentation for this class was generated from the following files:

- kdirwatch.h
- kdirwatch.cpp

KDE Home | KDE Accessibility Home | Description of Access Keys