org.kde.koala

Class KDirWatch

public class KDirWatch extends QObject

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 KDirWatchSignals for signals emitted by KDirWatch

Author: Sven Radej

See Also: KDirWatch

UNKNOWN: Class for watching directory and file changes.

Field Summary
static intDNotify
static intFAM
static intStat
Constructor Summary
protected KDirWatch(Class dummy)
KDirWatch(QObject parent, String name)
Constructor.
KDirWatch(QObject parent)
KDirWatch()
Method Summary
voidaddDir(String path, boolean watchFiles, boolean recursive)
Adds a directory to be watched.
voidaddDir(String path, boolean watchFiles)
voidaddDir(String path)
voidaddFile(String file)
Adds a file to be watched.
StringclassName()
booleancontains(String path)
Check if a directory is being watched by this KDirWatch instance
Calendarctime(String path)
Returns the time the directory/file was last changed.
voiddispose()
Delete the wrapped C++ instance ahead of finalize()
static booleanexists()
Returns true if there is an instance of KDirWatch.
protected voidfinalize()
Deletes the wrapped C++ instance
intinternalMethod()
Returns the preferred internal method to watch for changes.
booleanisDisposed()
Has the wrapped C++ instance been deleted?
booleanisStopped()
Is scanning stopped?
QMetaObjectmetaObject()
voidremoveDir(String path)
Removes a directory from the list of scanned directories.
voidremoveFile(String file)
Removes a file from the list of watched files.
booleanrestartDirScan(String path)
Restarts scanning for specified path.
static KDirWatchself()
The KDirWatch instance usually globally used in an application.
voidsetCreated(String path)
Emits created().
voidsetDeleted(String path)
Emits deleted().
voidsetDirty(String path)
Emits dirty().
voidstartScan(boolean notify, boolean skippedToo)
Starts scanning of all dirs in list.
voidstartScan(boolean notify)
voidstartScan()
static voidstatistics()
Dump statistic information about all KDirWatch instances.
booleanstopDirScan(String path)
Stops scanning the specified path.
voidstopScan()
Stops scanning of all directories in internal list.

Field Detail

DNotify

public static final int DNotify

FAM

public static final int FAM

Stat

public static final int Stat

Constructor Detail

KDirWatch

protected KDirWatch(Class dummy)

KDirWatch

public KDirWatch(QObject parent, String name)
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

UNKNOWN: Constructor.

KDirWatch

public KDirWatch(QObject parent)

KDirWatch

public KDirWatch()

Method Detail

addDir

public void addDir(String path, boolean watchFiles, boolean recursive)
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

UNKNOWN: Adds a directory to be watched.

addDir

public void addDir(String path, boolean watchFiles)

addDir

public void addDir(String path)

addFile

public void addFile(String file)
Adds a file to be watched.

Parameters: file the file to watch

UNKNOWN: Adds a file to be watched.

className

public String className()

contains

public boolean contains(String 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

UNKNOWN: Check if a directory is being watched by this KDirWatch instance

ctime

public Calendar ctime(String path)
Returns the time the directory/file was last changed.

Parameters: path the file to check

Returns: the date of the last modification

UNKNOWN: Returns the time the directory/file was last changed.

dispose

public void dispose()
Delete the wrapped C++ instance ahead of finalize()

exists

public static boolean exists()
Returns true if there is an instance of KDirWatch.

Returns: true if there is an instance of KDirWatch.

See Also: KDirWatch

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

finalize

protected void finalize()
Deletes the wrapped C++ instance

internalMethod

public int internalMethod()
Returns the preferred internal method to watch for changes.

UNKNOWN: Returns the preferred internal method to watch for changes.

isDisposed

public boolean isDisposed()
Has the wrapped C++ instance been deleted?

isStopped

public boolean isStopped()
Is scanning stopped? After creation of a KDirWatch instance, this is false.

Returns: true when scanning stopped

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

metaObject

public QMetaObject metaObject()

removeDir

public void removeDir(String 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

UNKNOWN: Removes a directory from the list of scanned directories.

removeFile

public void removeFile(String 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

UNKNOWN: Removes a file from the list of watched files.

restartDirScan

public boolean restartDirScan(String 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: KDirWatch

UNKNOWN: Restarts scanning for specified path.

self

public static 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

UNKNOWN: The KDirWatch instance usually globally used in an application.

setCreated

public void setCreated(String path)
Emits created().

Parameters: path the path of the file or directory

UNKNOWN: Emits created().

setDeleted

public void setDeleted(String path)
Emits deleted().

Parameters: path the path of the file or directory

UNKNOWN: Emits deleted().

setDirty

public void setDirty(String path)
Emits dirty().

Parameters: path the path of the file or directory

UNKNOWN: Emits dirty().

startScan

public void startScan(boolean notify, boolean skippedToo)
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.

UNKNOWN: Starts scanning of all dirs in list.

startScan

public void startScan(boolean notify)

startScan

public void startScan()

statistics

public static void statistics()
Dump statistic information about all KDirWatch instances. This checks for consistency, too.

UNKNOWN: Dump statistic information about all KDirWatch instances.

stopDirScan

public boolean stopDirScan(String 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: KDirWatch

UNKNOWN: Stops scanning the specified path.

stopScan

public void stopScan()
Stops scanning of all directories in internal list. The timer is stopped, but the list is not cleared.

UNKNOWN: Stops scanning of all directories in internal list.