\section{KNotify\-Client Namespace Reference}
\label{namespaceKNotifyClient}\index{KNotifyClient@{KNotifyClient}}
This namespace provides a method for issuing events to a KNotify\-Server call {\bf KNotify\-Client::event}{\rm (p.\,\pageref{namespaceKNotifyClient_a19})}(\char`\"{}eventname\char`\"{}); to issue it.  


\subsection*{Classes}
\begin{CompactItemize}
\item 
class {\bf Instance}
\begin{CompactList}\small\item\em Makes it possible to use {\bf KNotify\-Client}{\rm (p.\,\pageref{namespaceKNotifyClient})} with a {\bf KInstance}{\rm (p.\,\pageref{classKInstance})} that is not the application. Enables {\bf KNotify\-Client}{\rm (p.\,\pageref{namespaceKNotifyClient})} to use a different {\bf KInstance}{\rm (p.\,\pageref{classKInstance})}. \item\end{CompactList}\end{CompactItemize}
\subsection*{Enumerations}
\begin{CompactItemize}
\item 
enum \{ \par
{\bf Default} =  -1, 
{\bf None} =  0, 
{\bf Sound} =  1, 
{\bf Messagebox} =  2, 
\par
{\bf Logfile} =  4, 
{\bf Stderr} =  8, 
{\bf Passive\-Popup} =  16, 
{\bf Execute} =  32, 
\par
{\bf Taskbar} =  64
 \}
\item 
enum \{ {\bf Notification} = 1, 
{\bf Warning} = 2, 
{\bf Error} = 4, 
{\bf Catastrophe} = 8
 \}
\item 
enum {\bf Standard\-Event} \{ \par
{\bf cannot\-Open\-File}, 
{\bf notification}, 
{\bf warning}, 
{\bf fatal\-Error}, 
\par
{\bf catastrophe}
 \}
\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
KDECORE\_\-EXPORT bool {\bf start\-Daemon} ()
\item 
KDECORE\_\-EXPORT int {\bf event} (const {\bf QString} \&message, const {\bf QString} \&text=QString::null) KDE\_\-DEPRECATED
\item 
KDECORE\_\-EXPORT int {\bf event} ({\bf Standard\-Event} event, const {\bf QString} \&text=QString::null) KDE\_\-DEPRECATED
\item 
KDECORE\_\-EXPORT int {\bf user\-Event} (const {\bf QString} \&text=QString::null, int present=Default, int level=Default, const {\bf QString} \&sound=QString::null, const {\bf QString} \&file=QString::null) KDE\_\-DEPRECATED
\item 
KDECORE\_\-EXPORT int {\bf event} (int win\-Id, const {\bf QString} \&message, const {\bf QString} \&text=QString::null)
\item 
KDECORE\_\-EXPORT int {\bf event} (int win\-Id, {\bf Standard\-Event} event, const {\bf QString} \&text=QString::null)
\item 
KDECORE\_\-EXPORT int {\bf user\-Event} (int win\-Id, const {\bf QString} \&text=QString::null, int present=Default, int level=Default, const {\bf QString} \&sound=QString::null, const {\bf QString} \&file=QString::null)
\item 
KDECORE\_\-EXPORT void {\bf beep} (const {\bf QString} \&reason=QString::null)
\item 
KDECORE\_\-EXPORT int {\bf get\-Presentation} (const {\bf QString} \&eventname)
\item 
KDECORE\_\-EXPORT {\bf QString} {\bf get\-File} (const {\bf QString} \&eventname, int present)
\item 
KDECORE\_\-EXPORT int {\bf get\-Default\-Presentation} (const {\bf QString} \&eventname)
\item 
KDECORE\_\-EXPORT {\bf QString} {\bf get\-Default\-File} (const {\bf QString} \&eventname, int present)
\item 
KDECORE\_\-EXPORT {\bf KInstance} $\ast$ {\bf instance} ()
\end{CompactItemize}


\subsection{Detailed Description}
This namespace provides a method for issuing events to a KNotify\-Server call {\bf KNotify\-Client::event}{\rm (p.\,\pageref{namespaceKNotifyClient_a19})}(\char`\"{}eventname\char`\"{}); to issue it. 

On installation, there should be a file called \$KDEDIR/share/apps/appname/eventsrc which contains the events.

The file looks like this: 

\footnotesize\begin{verbatim} [!Global!]
 IconName=Filename (e.g. kdesktop, without any extension)
 Comment=FriendlyNameOfApp

 [eventname]
 Name=FriendlyNameOfEvent
 Comment=Description Of Event
 default_sound=filetoplay.wav
 default_logfile=logfile.txt
 default_commandline=command
 default_presentation=1
  ...
\end{verbatim}
\normalsize
 default\_\-presentation contains these ORed events: None=0, Sound=1, Messagebox=2, Logfile=4, Stderr=8, Passive\-Popup=16, Execute=32, Taskbar=64

KNotify will search for sound files given with a relative path first in the application's sound directory (share/apps/Application Name/sounds), then in the {\bf KDE}{\rm (p.\,\pageref{namespaceKDE})} global sound directory (share/sounds).

You can also use the \char`\"{}nopresentation\char`\"{} key, with any the presentations ORed. Those that are in that field will not appear in the kcontrol module. This was intended for software like KWin to not allow a window-opening that opens a window (e.g., allowing to disable KMessage\-Boxes from appearing) If the user edits the eventsrc file manually, it will appear. This only affects the Kcm\-Notify.

You can also use the following events, which are system controlled and do not need to be placed in your eventsrc:

\begin{itemize}
\item cannotopenfile \item notification \item warning \item fatalerror \item catastrophe \end{itemize}


The events can be configured in an application using {\bf KNotify\-Dialog}, which is part of {\bf KIO}.

\begin{Desc}
\item[Author:]Charles Samuels $<${\tt charles@kde.org}$>$ \end{Desc}




\subsection{Enumeration Type Documentation}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}anonymous enum}\label{namespaceKNotifyClient_a31}


Describes the notification method. 

\begin{Desc}
\item[Enumeration values: ]\par
\begin{description}
\index{PassivePopup@{PassivePopup}!KNotifyClient@{KNotifyClient}}\index{KNotifyClient@{KNotifyClient}!PassivePopup@{PassivePopup}}\item[{\em 
Passive\-Popup\label{namespaceKNotifyClient_a31a6}
}]\begin{Desc}
\item[Since:]3.1 \end{Desc}
\index{Execute@{Execute}!KNotifyClient@{KNotifyClient}}\index{KNotifyClient@{KNotifyClient}!Execute@{Execute}}\item[{\em 
Execute\label{namespaceKNotifyClient_a31a7}
}]\begin{Desc}
\item[Since:]3.1 \end{Desc}
\index{Taskbar@{Taskbar}!KNotifyClient@{KNotifyClient}}\index{KNotifyClient@{KNotifyClient}!Taskbar@{Taskbar}}\item[{\em 
Taskbar\label{namespaceKNotifyClient_a31a8}
}]\begin{Desc}
\item[Since:]3.2 \end{Desc}
\end{description}
\end{Desc}



Definition at line 138 of file knotifyclient.h.\subsubsection{\setlength{\rightskip}{0pt plus 5cm}anonymous enum}\label{namespaceKNotifyClient_a32}


Describes the level of the error. 



Definition at line 153 of file knotifyclient.h.\index{KNotifyClient@{KNotify\-Client}!StandardEvent@{StandardEvent}}
\index{StandardEvent@{StandardEvent}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}enum {\bf KNotify\-Client::Standard\-Event}}\label{namespaceKNotifyClient_a33}


default events you can use 



Definition at line 163 of file knotifyclient.h.

\subsection{Function Documentation}
\index{KNotifyClient@{KNotify\-Client}!startDaemon@{startDaemon}}
\index{startDaemon@{startDaemon}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KNotify\-Client::start\-Daemon ()}\label{namespaceKNotifyClient_a18}


This starts the KNotify Daemon, if it's not already started. 

This will be useful for games that use sound effects. Run this at the start of the program, and there won't be a pause when it is first triggered. \begin{Desc}
\item[Returns:]true if daemon is running (always true at the moment) \end{Desc}


Definition at line 225 of file knotifyclient.cpp.

References KApplication::start\-Service\-By\-Desktop\-Name().\index{KNotifyClient@{KNotify\-Client}!event@{event}}
\index{event@{event}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int KNotify\-Client::event (const {\bf QString} \& {\em message}, const {\bf QString} \& {\em text} = {\tt QString::null})}\label{namespaceKNotifyClient_a19}


\begin{Desc}
\item[{\bf Deprecated}]\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em message}]The name of the event \item[{\em text}]The text to put in a dialog box. This won't be shown if the user connected the event to sound, only. Can be QString::null. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a value $>$ 0, unique for this event if successful, 0 otherwise\end{Desc}


Definition at line 112 of file knotifyclient.cpp.

Referenced by beep(), and event().\index{KNotifyClient@{KNotify\-Client}!event@{event}}
\index{event@{event}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int KNotify\-Client::event (Standard\-Event {\em event}, const {\bf QString} \& {\em text} = {\tt QString::null})}\label{namespaceKNotifyClient_a20}


\begin{Desc}
\item[{\bf Deprecated}]Allows to easily emit standard events.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em event}]The event you want to raise. \item[{\em text}]The text explaining the event you raise. Can be QString::null. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a value $>$ 0, unique for this event if successful, 0 otherwise\end{Desc}


Definition at line 107 of file knotifyclient.cpp.

References event().\index{KNotifyClient@{KNotify\-Client}!userEvent@{userEvent}}
\index{userEvent@{userEvent}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int KNotify\-Client::user\-Event (const {\bf QString} \& {\em text} = {\tt QString::null}, int {\em present} = {\tt Default}, int {\em level} = {\tt Default}, const {\bf QString} \& {\em sound} = {\tt QString::null}, const {\bf QString} \& {\em file} = {\tt QString::null})}\label{namespaceKNotifyClient_a21}


\begin{Desc}
\item[{\bf Deprecated}]Will fire an event that's not registered.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em text}]The error message text, if applicable \item[{\em present}]The presentation method(s) of the event \item[{\em level}]The error message level, defaulting to \char`\"{}Default\char`\"{} \item[{\em sound}]The sound file to play if selected with {\tt present} \item[{\em file}]The log file to append the message to if selected with {\tt present} \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a value $>$ 0, unique for this event if successful, 0 otherwise\end{Desc}


Definition at line 117 of file knotifyclient.cpp.

Referenced by KAudio\-Player::play().\index{KNotifyClient@{KNotify\-Client}!event@{event}}
\index{event@{event}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int KNotify\-Client::event (int {\em win\-Id}, const {\bf QString} \& {\em message}, const {\bf QString} \& {\em text} = {\tt QString::null})}\label{namespaceKNotifyClient_a22}


This should be the most used method in here. 

Pass the origin-widget's win\-Id() here so that a Passive\-Popup can be placed appropriately.

Call it by {\bf KNotify\-Client::event}{\rm (p.\,\pageref{namespaceKNotifyClient_a19})}(widget-$>$win\-Id(), \char`\"{}Event\-Name\char`\"{}); It will use {\bf KApplication::k\-Application}{\rm (p.\,\pageref{classKApplication_e1})}-$>$dcop\-Client() to communicate to the server \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em win\-Id}]The win\-Id() of the widget where the event originates \item[{\em message}]The name of the event \item[{\em text}]The text to put in a dialog box. This won't be shown if the user connected the event to sound, only. Can be QString::null. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a value $>$ 0, unique for this event if successful, 0 otherwise \end{Desc}
\begin{Desc}
\item[Since:]3.1.1\end{Desc}


Definition at line 150 of file knotifyclient.cpp.\index{KNotifyClient@{KNotify\-Client}!event@{event}}
\index{event@{event}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int KNotify\-Client::event (int {\em win\-Id}, Standard\-Event {\em event}, const {\bf QString} \& {\em text} = {\tt QString::null})}\label{namespaceKNotifyClient_a23}


You should pass the origin-widget's win\-Id() here so that a Passive\-Popup can be placed appropriately. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em win\-Id}]The win\-Id() of the widget where the event originates \item[{\em event}]The event you want to raise \item[{\em text}]The text to put in a dialog box. This won't be shown if the user connected the event to sound, only. Can be QString::null. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a value $>$ 0, unique for this event if successful, 0 otherwise \end{Desc}
\begin{Desc}
\item[Since:]3.1.1\end{Desc}


Definition at line 124 of file knotifyclient.cpp.

References QString::from\-Latin1().\index{KNotifyClient@{KNotify\-Client}!userEvent@{userEvent}}
\index{userEvent@{userEvent}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int KNotify\-Client::user\-Event (int {\em win\-Id}, const {\bf QString} \& {\em text} = {\tt QString::null}, int {\em present} = {\tt Default}, int {\em level} = {\tt Default}, const {\bf QString} \& {\em sound} = {\tt QString::null}, const {\bf QString} \& {\em file} = {\tt QString::null})}\label{namespaceKNotifyClient_a24}


Will fire an event that's not registered. 

You should pass the origin-widget's win\-Id() here so that a Passive\-Popup can be placed appropriately. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em win\-Id}]The win\-Id() of the originating widget \item[{\em text}]The error message text, if applicable \item[{\em present}]The presentation method(s) of the event \item[{\em level}]The error message level, defaulting to \char`\"{}Default\char`\"{} \item[{\em sound}]The sound file to play if selected with {\tt present} \item[{\em file}]The log file to append the message to if selected with {\tt present} \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a value $>$ 0, unique for this event if successful, 0 otherwise \end{Desc}
\begin{Desc}
\item[Since:]3.1.1\end{Desc}


Definition at line 156 of file knotifyclient.cpp.\index{KNotifyClient@{KNotify\-Client}!beep@{beep}}
\index{beep@{beep}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KNotify\-Client::beep (const {\bf QString} \& {\em reason} = {\tt QString::null})}\label{namespaceKNotifyClient_a25}


This is a simple substitution for {\bf QApplication::beep()}. 

It simply calls 

\footnotesize\begin{verbatim} KNotifyClient::event( KNotifyClient::notification, reason );
\end{verbatim}
\normalsize
 \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em reason}]the reason, can be QString::null.\end{description}
\end{Desc}


Definition at line 239 of file knotifyclient.cpp.

References DCOPClient::attach(), QApplication::beep(), event(), DCOPClient::is\-Application\-Registered(), and DCOPClient::is\-Attached().\index{KNotifyClient@{KNotify\-Client}!getPresentation@{getPresentation}}
\index{getPresentation@{getPresentation}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int KNotify\-Client::get\-Presentation (const {\bf QString} \& {\em eventname})}\label{namespaceKNotifyClient_a26}


Gets the presentation associated with a certain event name Remeber that they may be ORed: 

\footnotesize\begin{verbatim} if (present & KNotifyClient::Sound) { [Yes, sound is a default] }  
\end{verbatim}
\normalsize
. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em eventname}]the event name to check \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the presentation methods\end{Desc}


Definition at line 163 of file knotifyclient.cpp.

References KConfig\-Base::read\-Num\-Entry(), and KConfig\-Base::set\-Group().\index{KNotifyClient@{KNotify\-Client}!getFile@{getFile}}
\index{getFile@{getFile}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf QString} KNotify\-Client::get\-File (const {\bf QString} \& {\em eventname}, int {\em present})}\label{namespaceKNotifyClient_a27}


Gets the default file associated with a certain event name The control panel module will list all the event names This has the potential for being slow. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em eventname}]the name of the event \item[{\em present}]the presentation method \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the associated file. Can be QString::null if not found.\end{Desc}


Definition at line 176 of file knotifyclient.cpp.

References KConfig\-Base::read\-Path\-Entry(), and KConfig\-Base::set\-Group().\index{KNotifyClient@{KNotify\-Client}!getDefaultPresentation@{getDefaultPresentation}}
\index{getDefaultPresentation@{getDefaultPresentation}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int KNotify\-Client::get\-Default\-Presentation (const {\bf QString} \& {\em eventname})}\label{namespaceKNotifyClient_a28}


Gets the default presentation for the event of this program. 

Remember that the Presentation may be ORed. Try this: 

\footnotesize\begin{verbatim} if (present & KNotifyClient::Sound) { [Yes, sound is a default] }
\end{verbatim}
\normalsize
 \begin{Desc}
\item[Returns:]the presentation methods\end{Desc}


Definition at line 194 of file knotifyclient.cpp.

References KConfig\-Base::read\-Num\-Entry(), and KConfig\-Base::set\-Group().\index{KNotifyClient@{KNotify\-Client}!getDefaultFile@{getDefaultFile}}
\index{getDefaultFile@{getDefaultFile}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf QString} KNotify\-Client::get\-Default\-File (const {\bf QString} \& {\em eventname}, int {\em present})}\label{namespaceKNotifyClient_a29}


Gets the default File for the event of this program. 

It gets it in relation to present. Some events don't apply to this function (\char`\"{}Message Box\char`\"{}) Some do (Sound) \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em eventname}]the name of the event \item[{\em present}]the presentation method \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the default file. Can be QString::null if not found.\end{Desc}


Definition at line 207 of file knotifyclient.cpp.

References KConfig\-Base::read\-Path\-Entry(), and KConfig\-Base::set\-Group().\index{KNotifyClient@{KNotify\-Client}!instance@{instance}}
\index{instance@{instance}!KNotifyClient@{KNotify\-Client}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf KInstance} $\ast$ KNotify\-Client::instance ()}\label{namespaceKNotifyClient_a30}


Shortcut to {\bf KNotify\-Client::Instance::current()}{\rm (p.\,\pageref{classKNotifyClient_1_1Instance_e0})} :). 

\begin{Desc}
\item[Returns:]the current {\bf KInstance}{\rm (p.\,\pageref{classKInstance})}.\end{Desc}


Definition at line 267 of file knotifyclient.cpp.

References KNotify\-Client::Instance::current().

Referenced by KNotify\-Client::Instance::Instance().