KDirWatch Class Reference

from PyKDE4.kio import *

Detailed Description

Class for watching directory and file changes.

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 INOTIFY 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()

Author:: Sven Radej <sven@lisa.exp.univie.ac.at>

Enumerations
Method	{ FAM, INotify, DNotify, Stat }
WatchMode	{ WatchDirOnly, WatchFiles, WatchSubDirs } Typesafe wrapper: WatchModes
Signals
	created (QString path)
	deleted (QString path)
	dirty (QString path)
Methods
	__init__ (self, QObject parent=0)
	addDir (self, QString path, KDirWatch.WatchModes watchModes=KDirWatch.WatchDirOnly)
	addFile (self, QString file)
bool	contains (self, QString path)
	created (self, QString path)
QDateTime	ctime (self, QString path)
	deleted (self, QString path)
	dirty (self, QString path)
KDirWatch.Method	internalMethod (self)
bool	isStopped (self)
	removeDir (self, QString path)
	removeFile (self, QString file)
bool	restartDirScan (self, QString path)
	setCreated (self, QString path)
	setDeleted (self, QString path)
	setDirty (self, QString path)
	startScan (self, bool notify=0, bool skippedToo=0)
bool	stopDirScan (self, QString path)
	stopScan (self)
Static Methods
bool	exists ()
KDirWatch	self ()
	statistics ()

Method Documentation

__init__	(	self,
		QObject	parent=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)

addDir	(	self,
		QString	path,
		KDirWatch.WatchModes	watchModes=KDirWatch.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().

Parameters:

	path	the path to watch
	watchModes	watch modes

@sa KDirWatch.WatchMode

addFile	(	self,
		QString	file
	)

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

Parameters:

file

the file to watch

bool contains	(	self,
		QString	path
	)

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

created	(	self,
		QString	path
	)

Emitted when a file or directory is created.

Parameters:

path

the path of the file or directory

Signal syntax:: QObject.connect(source, SIGNAL("created(const QString&)"), target_slot)

QDateTime ctime	(	self,
		QString	path
	)

Returns the time the directory/file was last changed.

Parameters:

path

the file to check

Returns:: the date of the last modification

deleted	(	self,
		QString	path
	)

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

Signal syntax:: QObject.connect(source, SIGNAL("deleted(const QString&)"), target_slot)

dirty	(	self,
		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.

Parameters:

path

the path of the file or directory

Signal syntax:: QObject.connect(source, SIGNAL("dirty(const QString&)"), target_slot)

bool exists ( )

Returns true if there is an instance of KDirWatch.

Returns:: true if there is an instance of KDirWatch.

See also:: KDirWatch.self()

KDirWatch.Method internalMethod ( self )

Returns the preferred internal method to watch for changes.

bool isStopped ( self )

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

Returns:: true when scanning stopped

removeDir	(	self,
		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

removeFile	(	self,
		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

bool restartDirScan	(	self,
		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()

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

setCreated	(	self,
		QString	path
	)

Emits created().

Parameters:

path

the path of the file or directory

setDeleted	(	self,
		QString	path
	)

Emits deleted().

Parameters:

path

the path of the file or directory

setDirty	(	self,
		QString	path
	)

Emits dirty().

Parameters:

path

the path of the file or directory

startScan	(	self,
		bool	notify=0,
		bool	skippedToo=0
	)

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.

statistics ( )

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

bool stopDirScan	(	self,
		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()

stopScan ( self )

Stops scanning of all directories in internal list.

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

Enumeration Documentation

Method

Enumerator:

FAM
INotify
DNotify
Stat

WatchMode

Available watch modes for directory monitoring

Note:: It is necessary to wrap members of this enumeration in a WatchModes instance when passing them to a method as group of flags. For example: WatchModes( WatchDirOnly | WatchFiles)

Enumerator:

WatchDirOnly = 0
WatchFiles = 0x01
WatchSubDirs = 0x02

KDirWatch Class Reference

Detailed Description

Enumerations

Signals

Methods

Static Methods

Method Documentation

Enumeration Documentation

Modules