\section{KDir\-Watch Class Reference}
\label{classKDirWatch}\index{KDirWatch@{KDirWatch}}
Watch directories and files for changes. Class for watching directory and file changes.  


{\tt \#include $<$kdirwatch.h$>$}

Inheritance diagram for KDir\-Watch:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=50pt]{classKDirWatch__inherit__graph}
\end{center}
\end{figure}
Collaboration diagram for KDir\-Watch:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=76pt]{classKDirWatch__coll__graph}
\end{center}
\end{figure}
\subsection*{Public Types}
\begin{CompactItemize}
\item 
enum {\bf Method} \{ {\bf FAM}, 
{\bf DNotify}, 
{\bf Stat}
 \}
\end{CompactItemize}
\subsection*{Signals}
\begin{CompactItemize}
\item 
void {\bf dirty} (const {\bf QString} \&path)
\item 
void {\bf created} (const {\bf QString} \&path)
\item 
void {\bf deleted} (const {\bf QString} \&path)
\end{CompactItemize}
\subsection*{Public Member Functions}
\begin{CompactItemize}
\item 
{\bf KDir\-Watch} ({\bf QObject} $\ast${\bf parent}=0, const char $\ast${\bf name}=0)
\item 
{\bf $\sim$KDir\-Watch} ()
\item 
void {\bf add\-Dir} (const {\bf QString} \&path, bool watch\-Files=false, bool recursive=false)
\item 
void {\bf add\-File} (const {\bf QString} \&file)
\item 
{\bf QDate\-Time} {\bf ctime} (const {\bf QString} \&path)
\item 
void {\bf remove\-Dir} (const {\bf QString} \&path)
\item 
void {\bf remove\-File} (const {\bf QString} \&file)
\item 
bool {\bf stop\-Dir\-Scan} (const {\bf QString} \&path)
\item 
bool {\bf restart\-Dir\-Scan} (const {\bf QString} \&path)
\item 
void {\bf start\-Scan} (bool notify=false, bool skipped\-Too=false)
\item 
void {\bf stop\-Scan} ()
\item 
bool {\bf is\-Stopped} ()
\item 
bool {\bf contains} (const {\bf QString} \&path) const 
\item 
void {\bf set\-Created} (const {\bf QString} \&path)
\item 
void {\bf set\-Dirty} (const {\bf QString} \&path)
\item 
void {\bf set\-Deleted} (const {\bf QString} \&path)
\item 
Method {\bf internal\-Method} ()
\end{CompactItemize}
\subsection*{Static Public Member Functions}
\begin{CompactItemize}
\item 
static void {\bf statistics} ()
\item 
static {\bf KDir\-Watch} $\ast$ {\bf self} ()
\item 
static bool {\bf exists} ()
\end{CompactItemize}


\subsection{Detailed Description}
Watch directories and files for changes. Class for watching directory and file 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, KDir\-Watch will emit the signal {\bf dirty()}{\rm (p.\,\pageref{classKDirWatch_l0})}.

When a watched, but previously not existing directory gets created, KDir\-Watch will emit the signal {\bf created()}{\rm (p.\,\pageref{classKDirWatch_l1})}.

When a watched directory gets deleted, KDir\-Watch will emit the signal {\bf deleted()}{\rm (p.\,\pageref{classKDirWatch_l2})}. The directory is still watched for new creation.

When a watched file is changed, i.e. attributes changed or written to, KDir\-Watch will emit the signal {\bf dirty()}{\rm (p.\,\pageref{classKDirWatch_l0})}.

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: Dir\-Watch/Poll\-Interval and Dir\-Watch/NFSPoll\-Interval for NFS mounted directories.

\begin{Desc}
\item[See also:]{\bf self()}{\rm (p.\,\pageref{classKDirWatch_e1})} \end{Desc}
\begin{Desc}
\item[Author:]Sven Radej $<${\tt sven@lisa.exp.univie.ac.at}$>$ \end{Desc}




Definition at line 63 of file kdirwatch.h.

\subsection{Constructor \& Destructor Documentation}
\index{KDirWatch@{KDir\-Watch}!KDirWatch@{KDirWatch}}
\index{KDirWatch@{KDirWatch}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}KDir\-Watch::KDir\-Watch ({\bf QObject} $\ast$ {\em parent} = {\tt 0}, const char $\ast$ {\em name} = {\tt 0})}\label{classKDirWatch_a0}


Constructor. 

Scanning begins immediately when a dir/file watch is added. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em parent}]the parent of the {\bf QObject} (or 0 for parent-less KData\-Tools) \item[{\em name}]the name of the {\bf QObject}, can be 0 \end{description}
\end{Desc}


Definition at line 1312 of file kdirwatch.cpp.

References QObject::set\-Name().\index{KDirWatch@{KDir\-Watch}!~KDirWatch@{$\sim$KDirWatch}}
\index{~KDirWatch@{$\sim$KDirWatch}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}KDir\-Watch::$\sim${\bf KDir\-Watch} ()}\label{classKDirWatch_a1}


Destructor. 

Stops scanning and cleans up. 

Definition at line 1330 of file kdirwatch.cpp.

\subsection{Member Function Documentation}
\index{KDirWatch@{KDir\-Watch}!addDir@{addDir}}
\index{addDir@{addDir}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::add\-Dir (const {\bf QString} \& {\em path}, bool {\em watch\-Files} = {\tt false}, bool {\em recursive} = {\tt false})}\label{classKDirWatch_a2}


Adds a directory to be watched. 

The directory does not have to exist. When {\tt watch\-Files} is false (the default), the signals {\bf dirty()}{\rm (p.\,\pageref{classKDirWatch_l0})}, {\bf created()}{\rm (p.\,\pageref{classKDirWatch_l1})}, {\bf deleted()}{\rm (p.\,\pageref{classKDirWatch_l2})} can be emitted, all for the watched directory. When {\tt watch\-Files} is true, all files in the watched directory are watched for changes, too. Thus, the signals {\bf dirty()}{\rm (p.\,\pageref{classKDirWatch_l0})}, {\bf created()}{\rm (p.\,\pageref{classKDirWatch_l1})}, {\bf deleted()}{\rm (p.\,\pageref{classKDirWatch_l2})} can be emitted.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the path to watch \item[{\em watch\-Files}]if true, the KDir\-Watch will also watch files - NOT IMPLEMENTED YET \item[{\em recursive}]if true, all sub directories are also watched - NOT IMPLEMENTED YET \end{description}
\end{Desc}


Definition at line 1343 of file kdirwatch.cpp.

References endl(), and kd\-Debug().\index{KDirWatch@{KDir\-Watch}!addFile@{addFile}}
\index{addFile@{addFile}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::add\-File (const {\bf QString} \& {\em file})}\label{classKDirWatch_a3}


Adds a file to be watched. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em file}]the file to watch \end{description}
\end{Desc}


Definition at line 1352 of file kdirwatch.cpp.\index{KDirWatch@{KDir\-Watch}!ctime@{ctime}}
\index{ctime@{ctime}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf QDate\-Time} KDir\-Watch::ctime (const {\bf QString} \& {\em path})}\label{classKDirWatch_a4}


Returns the time the directory/file was last changed. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the file to check \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the date of the last modification \end{Desc}


Definition at line 1357 of file kdirwatch.cpp.

References QDate\-Time::set\-Time\_\-t().\index{KDirWatch@{KDir\-Watch}!removeDir@{removeDir}}
\index{removeDir@{removeDir}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::remove\-Dir (const {\bf QString} \& {\em path})}\label{classKDirWatch_a5}


Removes a directory from the list of scanned directories. 

If specified path is not in the list this does nothing. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the path of the dir to be removed from the list \end{description}
\end{Desc}


Definition at line 1369 of file kdirwatch.cpp.\index{KDirWatch@{KDir\-Watch}!removeFile@{removeFile}}
\index{removeFile@{removeFile}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::remove\-File (const {\bf QString} \& {\em file})}\label{classKDirWatch_a6}


Removes a file from the list of watched files. 

If specified path is not in the list this does nothing. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em file}]the file to be removed from the list \end{description}
\end{Desc}


Definition at line 1374 of file kdirwatch.cpp.\index{KDirWatch@{KDir\-Watch}!stopDirScan@{stopDirScan}}
\index{stopDirScan@{stopDirScan}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KDir\-Watch::stop\-Dir\-Scan (const {\bf QString} \& {\em path})}\label{classKDirWatch_a7}


Stops scanning the specified path. 

The {\tt 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 restart\-Dir\-Scan(path).

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the path to skip \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]true if the {\tt path} is being watched, otherwise false \end{Desc}
\begin{Desc}
\item[See also:]restart\-Dir\-Scanning() \end{Desc}


Definition at line 1379 of file kdirwatch.cpp.\index{KDirWatch@{KDir\-Watch}!restartDirScan@{restartDirScan}}
\index{restartDirScan@{restartDirScan}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KDir\-Watch::restart\-Dir\-Scan (const {\bf QString} \& {\em path})}\label{classKDirWatch_a8}


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, {\em and\/} when {\em you\/} have refreshed that path.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the path to restart scanning \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]true if the {\tt path} is being watched, otherwise false \end{Desc}
\begin{Desc}
\item[See also:]stop\-Dir\-Scanning() \end{Desc}


Definition at line 1388 of file kdirwatch.cpp.\index{KDirWatch@{KDir\-Watch}!startScan@{startScan}}
\index{startScan@{startScan}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::start\-Scan (bool {\em notify} = {\tt false}, bool {\em skipped\-Too} = {\tt false})}\label{classKDirWatch_a9}


Starts scanning of all dirs in list. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em notify}]If true, all changed directories (since {\bf stop\-Scan()}{\rm (p.\,\pageref{classKDirWatch_a10})} call) will be notified for refresh. If notify is false, all ctimes will be reset (except those who are stopped, but only if {\tt skipped\-Too} 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 {\tt false} or else all directories in list will be notified. \item[{\em skipped\-Too}]if true, the skipped directoris (scanning of which was stopped with {\bf stop\-Dir\-Scan()}{\rm (p.\,\pageref{classKDirWatch_a7})} ) will be reset and notified for change. Otherwise, stopped directories will continue to be unnotified. \end{description}
\end{Desc}


Definition at line 1405 of file kdirwatch.cpp.\index{KDirWatch@{KDir\-Watch}!stopScan@{stopScan}}
\index{stopScan@{stopScan}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::stop\-Scan ()}\label{classKDirWatch_a10}


Stops scanning of all directories in internal list. 

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

Definition at line 1399 of file kdirwatch.cpp.\index{KDirWatch@{KDir\-Watch}!isStopped@{isStopped}}
\index{isStopped@{isStopped}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KDir\-Watch::is\-Stopped ()\hspace{0.3cm}{\tt  [inline]}}\label{classKDirWatch_a11}


Is scanning stopped? After creation of a KDir\-Watch instance, this is false. 

\begin{Desc}
\item[Returns:]true when scanning stopped \end{Desc}


Definition at line 190 of file kdirwatch.h.\index{KDirWatch@{KDir\-Watch}!contains@{contains}}
\index{contains@{contains}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KDir\-Watch::contains (const {\bf QString} \& {\em path}) const}\label{classKDirWatch_a12}


Check if a directory is being watched by this KDir\-Watch instance. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the directory to check \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]true if the directory is being watched \end{Desc}


Definition at line 1412 of file kdirwatch.cpp.\index{KDirWatch@{KDir\-Watch}!statistics@{statistics}}
\index{statistics@{statistics}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::statistics ()\hspace{0.3cm}{\tt  [static]}}\label{classKDirWatch_e0}


Dump statistic information about all KDir\-Watch instances. 

This checks for consistency, too. 

Definition at line 1425 of file kdirwatch.cpp.

References endl(), and kd\-Debug().\index{KDirWatch@{KDir\-Watch}!setCreated@{setCreated}}
\index{setCreated@{setCreated}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::set\-Created (const {\bf QString} \& {\em path})}\label{classKDirWatch_a13}


Emits {\bf created()}{\rm (p.\,\pageref{classKDirWatch_l1})}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the path of the file or directory \end{description}
\end{Desc}


Definition at line 1435 of file kdirwatch.cpp.

References created(), endl(), kd\-Debug(), and QObject::name().\index{KDirWatch@{KDir\-Watch}!setDirty@{setDirty}}
\index{setDirty@{setDirty}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::set\-Dirty (const {\bf QString} \& {\em path})}\label{classKDirWatch_a14}


Emits {\bf dirty()}{\rm (p.\,\pageref{classKDirWatch_l0})}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the path of the file or directory \end{description}
\end{Desc}


Definition at line 1441 of file kdirwatch.cpp.

References dirty(), endl(), kd\-Debug(), and QObject::name().\index{KDirWatch@{KDir\-Watch}!setDeleted@{setDeleted}}
\index{setDeleted@{setDeleted}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::set\-Deleted (const {\bf QString} \& {\em path})}\label{classKDirWatch_a15}


Emits {\bf deleted()}{\rm (p.\,\pageref{classKDirWatch_l2})}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the path of the file or directory \end{description}
\end{Desc}


Definition at line 1447 of file kdirwatch.cpp.

References deleted(), endl(), kd\-Debug(), and QObject::name().\index{KDirWatch@{KDir\-Watch}!internalMethod@{internalMethod}}
\index{internalMethod@{internalMethod}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}KDir\-Watch::Method KDir\-Watch::internal\-Method ()}\label{classKDirWatch_a16}


Returns the preferred internal method to watch for changes. 

\begin{Desc}
\item[Since:]3.2 \end{Desc}


Definition at line 1453 of file kdirwatch.cpp.\index{KDirWatch@{KDir\-Watch}!self@{self}}
\index{self@{self}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf KDir\-Watch} $\ast$ KDir\-Watch::self ()\hspace{0.3cm}{\tt  [static]}}\label{classKDirWatch_e1}


The KDir\-Watch instance usually globally used in an application. 

It is automatically deleted when the application exits.

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

This function returns an instance of KDir\-Watch. If there is none, it will be created.

\begin{Desc}
\item[Returns:]a KDir\-Watch instance \end{Desc}


Definition at line 1298 of file kdirwatch.cpp.

References KStatic\-Deleter$<$ type $>$::set\-Object().\index{KDirWatch@{KDir\-Watch}!exists@{exists}}
\index{exists@{exists}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KDir\-Watch::exists ()\hspace{0.3cm}{\tt  [static]}}\label{classKDirWatch_e2}


Returns true if there is an instance of KDir\-Watch. 

\begin{Desc}
\item[Returns:]true if there is an instance of KDir\-Watch. \end{Desc}
\begin{Desc}
\item[See also:]{\bf KDir\-Watch::self()}{\rm (p.\,\pageref{classKDirWatch_e1})} \end{Desc}
\begin{Desc}
\item[Since:]3.1 \end{Desc}


Definition at line 1307 of file kdirwatch.cpp.\index{KDirWatch@{KDir\-Watch}!dirty@{dirty}}
\index{dirty@{dirty}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::dirty (const {\bf QString} \& {\em path})\hspace{0.3cm}{\tt  [signal]}}\label{classKDirWatch_l0}


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 KDir\-Watch.

The new ctime is set before the signal is emitted. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the path of the file or directory \end{description}
\end{Desc}


Referenced by set\-Dirty().\index{KDirWatch@{KDir\-Watch}!created@{created}}
\index{created@{created}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::created (const {\bf QString} \& {\em path})\hspace{0.3cm}{\tt  [signal]}}\label{classKDirWatch_l1}


Emitted when a file or directory is created. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the path of the file or directory \end{description}
\end{Desc}


Referenced by set\-Created().\index{KDirWatch@{KDir\-Watch}!deleted@{deleted}}
\index{deleted@{deleted}!KDirWatch@{KDir\-Watch}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KDir\-Watch::deleted (const {\bf QString} \& {\em path})\hspace{0.3cm}{\tt  [signal]}}\label{classKDirWatch_l2}


Emitted when a file or directory is deleted. 

The object is still watched for new creation. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em path}]the path of the file or directory \end{description}
\end{Desc}


Referenced by set\-Deleted().

The documentation for this class was generated from the following files:\begin{CompactItemize}
\item 
kdirwatch.h\item 
kdirwatch.cpp\end{CompactItemize}
