\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=52pt]{classKDirWatch__inherit__graph}
\end{center}
\end{figure}
Collaboration diagram for KDir\-Watch:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=84pt]{classKDirWatch__coll__graph}
\end{center}
\end{figure}
\subsection*{Signals}
\begin{CompactItemize}
\item 
void {\bf dirty} (const  {\bf QString} \&)
\begin{CompactList}\small\item\em Emitted when a watched object is changed. \item\end{CompactList}\item 
void {\bf created} (const  {\bf QString} \&)
\begin{CompactList}\small\item\em Emitted when a file or directory is created. \item\end{CompactList}\item 
void {\bf deleted} (const  {\bf QString} \&)
\begin{CompactList}\small\item\em Emitted when a file or directory is deleted. \item\end{CompactList}\end{CompactItemize}
\subsection*{Public Member Functions}
\begin{CompactItemize}
\item 
{\bf KDir\-Watch} ({\bf QObject} $\ast${\bf parent}=0, const  char $\ast${\bf name}=0)
\begin{CompactList}\small\item\em Constructor. \item\end{CompactList}\item 
{\bf $\sim$KDir\-Watch} ()
\begin{CompactList}\small\item\em Destructor. \item\end{CompactList}\item 
void {\bf add\-Dir} (const  {\bf QString} \&path, bool watch\-Files=false, bool recursive=false)
\begin{CompactList}\small\item\em Adds a directory to be watched. \item\end{CompactList}\item 
void {\bf add\-File} (const  {\bf QString} \&file)
\begin{CompactList}\small\item\em Adds a file to be watched. \item\end{CompactList}\item 
{\bf QDate\-Time} {\bf ctime} (const  {\bf QString} \&path)
\begin{CompactList}\small\item\em Returns the time the directory/file was last changed. \item\end{CompactList}\item 
void {\bf remove\-Dir} (const  {\bf QString} \&path)
\begin{CompactList}\small\item\em Removes a directory from the list of scanned directories. \item\end{CompactList}\item 
void {\bf remove\-File} (const  {\bf QString} \&file)
\begin{CompactList}\small\item\em Removes a file from the list of watched files. \item\end{CompactList}\item 
bool {\bf stop\-Dir\-Scan} (const  {\bf QString} \&path)
\begin{CompactList}\small\item\em Stops scanning the specified path. \item\end{CompactList}\item 
bool {\bf restart\-Dir\-Scan} (const  {\bf QString} \&path)
\begin{CompactList}\small\item\em Restarts scanning for specified path. \item\end{CompactList}\item 
void {\bf start\-Scan} (bool notify=false, bool skipped\-Too=false)
\begin{CompactList}\small\item\em Starts scanning of all dirs in list. \item\end{CompactList}\item 
void {\bf stop\-Scan} ()
\begin{CompactList}\small\item\em Stops scanning of all directories in internal list. \item\end{CompactList}\item 
bool {\bf is\-Stopped} ()
\begin{CompactList}\small\item\em Is scanning stopped? After creation of a KDir\-Watch instance, this is false. \item\end{CompactList}\item 
bool {\bf contains} (const  {\bf QString} \&path) const 
\begin{CompactList}\small\item\em Check if a directory is being watched by this KDir\-Watch instance. \item\end{CompactList}\item 
void {\bf set\-Created} (const  {\bf QString} \&)
\begin{CompactList}\small\item\em {\bf created}{\rm (p.\,\pageref{classKDirWatch_l1})}() \item\end{CompactList}\item 
void {\bf set\-Dirty} (const  {\bf QString} \&)
\begin{CompactList}\small\item\em {\bf dirty}{\rm (p.\,\pageref{classKDirWatch_l0})}() \item\end{CompactList}\item 
void {\bf set\-Deleted} (const  {\bf QString} \&)
\begin{CompactList}\small\item\em {\bf deleted}{\rm (p.\,\pageref{classKDirWatch_l2})}() \item\end{CompactList}\end{CompactItemize}
\subsection*{Static Public Member Functions}
\begin{CompactItemize}
\item 
void {\bf statistics} ()
\begin{CompactList}\small\item\em Dump statistic information about all KDir\-Watch instances. \item\end{CompactList}\item 
{\bf KDir\-Watch} $\ast$ {\bf self} ()
\begin{CompactList}\small\item\em The KDir\-Watch instance usually globally used in an application. \item\end{CompactList}\item 
bool {\bf exists} ()
\begin{CompactList}\small\item\em Return true if {\bf KDir\-Watch::self()}{\rm (p.\,\pageref{classKDirWatch_e1})} exists \begin{Desc}
\item[Since:]3.1. \end{Desc}
\item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Watch directories and files for changes. Class for watching directory and file 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, 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 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[Author:]Sven Radej $<${\tt sven@lisa.exp.univie.ac.at}$>$ \end{Desc}




Definition at line 60 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} = 0, const char $\ast$ {\em name} = 0)}\label{classKDirWatch_a0}


Constructor. 

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

Definition at line 1264 of file kdirwatch.cpp.

References QObject::name(), KStd\-Accel::name(), and 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 1282 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} = false, bool {\em recursive} = 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 looked for changes, too. Thus, the signals file\-Dirty(), file\-Created(), file\-Deleted() can be emitted. are looked 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.

When {\tt recursive} is true, also all sub directories are watched. 

Definition at line 1295 of file kdirwatch.cpp.\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. 



Definition at line 1305 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. 



Definition at line 1310 of file kdirwatch.cpp.\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. 

Definition at line 1320 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. 

Definition at line 1325 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 {\bf restart\-Dir\-Scan}{\rm (p.\,\pageref{classKDirWatch_a8})} (path). Returns {\tt false} if specified path is not in list, {\tt true} otherwise. 

Definition at line 1330 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. Returns {\tt false} if specified path is not in list, {\tt true} otherwise. 

Definition at line 1339 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} = false, bool {\em skipped\-Too} = false)}\label{classKDirWatch_a9}


Starts scanning of all dirs in list. 

If notify is {\tt true}, all changed directories (since {\bf stop\-Scan}{\rm (p.\,\pageref{classKDirWatch_a10})}() call) will be notified for refresh. If notify is {\tt false}, all ctimes will be reset (except those who are stopped, but only if {\tt skipped\-Too} is {\tt 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. If {\tt skipped\-Too} is 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. 

Definition at line 1356 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 1350 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. 



Definition at line 174 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. 



Definition at line 1363 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 1376 of file kdirwatch.cpp.\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} \&)}\label{classKDirWatch_a13}


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



Definition at line 1386 of file kdirwatch.cpp.

References created(), 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} \&)}\label{classKDirWatch_a14}


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



Definition at line 1392 of file kdirwatch.cpp.

References dirty(), 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} \&)}\label{classKDirWatch_a15}


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



Definition at line 1398 of file kdirwatch.cpp.

References deleted(), and QObject::name().\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. 

Definition at line 1250 of file kdirwatch.cpp.\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}


Return true if {\bf KDir\-Watch::self()}{\rm (p.\,\pageref{classKDirWatch_e1})} exists \begin{Desc}
\item[Since:]3.1. \end{Desc}




Definition at line 1259 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} \&)\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. 

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} \&)\hspace{0.3cm}{\tt  [signal]}}\label{classKDirWatch_l1}


Emitted when a file or directory is created. 



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} \&)\hspace{0.3cm}{\tt  [signal]}}\label{classKDirWatch_l2}


Emitted when a file or directory is deleted. 

The object is still watched for new creation. 

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}
