\section{KUnique\-Application Class Reference}
\label{classKUniqueApplication}\index{KUniqueApplication@{KUniqueApplication}}
Maintains only a single instance of a running application at a time.  


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

Inheritance diagram for KUnique\-Application:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=121pt]{classKUniqueApplication__inherit__graph}
\end{center}
\end{figure}
Collaboration diagram for KUnique\-Application:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=121pt]{classKUniqueApplication__coll__graph}
\end{center}
\end{figure}
\subsection*{Public Member Functions}
\begin{CompactItemize}
\item 
{\bf KUnique\-Application} (bool allow\-Styles=true, bool GUIenabled=true, bool config\-Unique=false)
\item 
{\bf KUnique\-Application} (Display $\ast$display, Qt::HANDLE visual=0, Qt::HANDLE colormap=0, bool allow\-Styles=true, bool config\-Unique=false)
\item 
virtual {\bf $\sim$KUnique\-Application} ()
\item 
bool {\bf process} (const {\bf QCString} \&fun, const {\bf QByte\-Array} \&data, {\bf QCString} \&reply\-Type, {\bf QByte\-Array} \&reply\-Data)
\item 
virtual int {\bf new\-Instance} ()
\item 
bool {\bf restoring\-Session} ()
\end{CompactItemize}
\subsection*{Static Public Member Functions}
\begin{CompactItemize}
\item 
static void {\bf add\-Cmd\-Line\-Options} ()
\item 
static bool {\bf start} ()
\item 
static void {\bf set\-Handle\-Auto\-Started} ()\label{classKUniqueApplication_e2}

\end{CompactItemize}
\subsection*{Protected Member Functions}
\begin{CompactItemize}
\item 
virtual void {\bf virtual\_\-hook} (int id, void $\ast$data)\label{classKUniqueApplication_b0}

\end{CompactItemize}


\subsection{Detailed Description}
Maintains only a single instance of a running application at a time. 

If another instance is started, it will determine (via DCOP) whether it is the first instance or a second instance. If it is a second instance, it will forward on the information to the first instance and then quit.

The .desktop file for the application should state X-DCOP-Service\-Type=Unique, see {\bf kapplication.h}{\rm (p.\,\pageref{kapplication_8h})}

If your application is used to open files, it should also support the --tempfile option (see {\bf KCmd\-Line\-Args::add\-Temp\-File\-Option()}{\rm (p.\,\pageref{classKCmdLineArgs_e15})}), to delete tempfiles after use. Add X-KDE-Has\-Temp\-File\-Option=true to the .desktop file to indicate this.

\begin{Desc}
\item[See also:]{\bf KApplication}{\rm (p.\,\pageref{classKApplication})} {\bf DCOPObject} \end{Desc}
\begin{Desc}
\item[Author:]Preston Brown $<${\tt pbrown@kde.org}$>$ \end{Desc}




Definition at line 48 of file kuniqueapplication.h.

\subsection{Constructor \& Destructor Documentation}
\index{KUniqueApplication@{KUnique\-Application}!KUniqueApplication@{KUniqueApplication}}
\index{KUniqueApplication@{KUniqueApplication}!KUniqueApplication@{KUnique\-Application}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}KUnique\-Application::KUnique\-Application (bool {\em allow\-Styles} = {\tt true}, bool {\em GUIenabled} = {\tt true}, bool {\em config\-Unique} = {\tt false})}\label{classKUniqueApplication_a0}


Constructor. 

Takes command line arguments from {\bf KCmd\-Line\-Args}{\rm (p.\,\pageref{classKCmdLineArgs})}

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em allow\-Styles}]Set to false to disable the loading on plugin based styles. This is only useful to applications that do not display a GUI normally. If you do create an application with {\tt allow\-Styles} set to false it normally runs in the background but under special circumstances displays widgets. Call {\bf KApplication::enable\-Styles()}{\rm (p.\,\pageref{classKApplication_a35})} before displaying any widgets. \item[{\em GUIenabled}]Set to false to disable all GUI stuff. This implies no styles either. \item[{\em config\-Unique}]If true, the uniqueness of the application will depend on the value of the \char`\"{}Multiple\-Instances\char`\"{} key in the \char`\"{}KDE\char`\"{} group of the application config file. \end{description}
\end{Desc}


Definition at line 317 of file kuniqueapplication.cpp.

References QTimer::single\-Shot().\index{KUniqueApplication@{KUnique\-Application}!KUniqueApplication@{KUniqueApplication}}
\index{KUniqueApplication@{KUniqueApplication}!KUniqueApplication@{KUnique\-Application}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}KUnique\-Application::KUnique\-Application (Display $\ast$ {\em display}, Qt::HANDLE {\em visual} = {\tt 0}, Qt::HANDLE {\em colormap} = {\tt 0}, bool {\em allow\-Styles} = {\tt true}, bool {\em config\-Unique} = {\tt false})}\label{classKUniqueApplication_a1}


Constructor. 

Takes command line arguments from {\bf KCmd\-Line\-Args}{\rm (p.\,\pageref{classKCmdLineArgs})}

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em display}]Will be passed to {\bf Qt} as the X display. The display must be valid and already opened. \item[{\em visual}]Pointer to the X11 visual that should be used by the application. If NULL, the default visual will be used instead. \item[{\em colormap}]The colormap that should be used by the application. If 0, the default colormap will be used instead. \item[{\em allow\-Styles}]Set to false to disable the loading on plugin based styles. This is only useful to applications that do not display a GUI normally. If you do create an application with {\tt allow\-Styles} set to false it normally runs in the background but under special circumstances displays widgets. Call {\bf KApplication::enable\-Styles()}{\rm (p.\,\pageref{classKApplication_a35})} before displaying any widgets. \item[{\em config\-Unique}]If true, the uniqueness of the application will depend on the value of the \char`\"{}Multiple\-Instances\char`\"{} key in the \char`\"{}KDE\char`\"{} group of the application config file. \end{description}
\end{Desc}
\begin{Desc}
\item[Since:]{\bf KDE}{\rm (p.\,\pageref{namespaceKDE})} 3.3 \end{Desc}


Definition at line 332 of file kuniqueapplication.cpp.

References QTimer::single\-Shot().\index{KUniqueApplication@{KUnique\-Application}!~KUniqueApplication@{$\sim$KUniqueApplication}}
\index{~KUniqueApplication@{$\sim$KUniqueApplication}!KUniqueApplication@{KUnique\-Application}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}KUnique\-Application::$\sim${\bf KUnique\-Application} ()\hspace{0.3cm}{\tt  [virtual]}}\label{classKUniqueApplication_a2}


Destructor. 



Definition at line 348 of file kuniqueapplication.cpp.

\subsection{Member Function Documentation}
\index{KUniqueApplication@{KUnique\-Application}!addCmdLineOptions@{addCmdLineOptions}}
\index{addCmdLineOptions@{addCmdLineOptions}!KUniqueApplication@{KUnique\-Application}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KUnique\-Application::add\-Cmd\-Line\-Options ()\hspace{0.3cm}{\tt  [static]}}\label{classKUniqueApplication_e0}


Adds command line options specific for KUnique\-Application. 

Should be called before calling KUnique\-Application constructor and / or {\bf start()}{\rm (p.\,\pageref{classKUniqueApplication_e1})}. 

Reimplemented from {\bf KApplication} {\rm (p.\,\pageref{classKApplication_e0})}.

Definition at line 87 of file kuniqueapplication.cpp.

References KCmd\-Line\-Args::add\-Cmd\-Line\-Options().

Referenced by start().\index{KUniqueApplication@{KUnique\-Application}!start@{start}}
\index{start@{start}!KUniqueApplication@{KUnique\-Application}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KUnique\-Application::start ()\hspace{0.3cm}{\tt  [static]}}\label{classKUniqueApplication_e1}


Forks and registers with dcop. 

The command line arguments are being sent via DCOP to {\bf new\-Instance()}{\rm (p.\,\pageref{classKUniqueApplication_a4})} and will be received once the application enters the event loop.

Typically this is used like: 

\footnotesize\begin{verbatim} int main(int argc, char **argv) {
    KAboutData about("myappname", "myAppName", .....);
    KCmdLineArgs::init(argc, argv, &about);
    KCmdLineArgs::addCmdLineOptions( myCmdOptions );
    KUniqueApplication::addCmdLineOptions();

    if (!KUniqueApplication::start()) {
       fprintf(stderr, "myAppName is already running!\n");
       exit(0);
    }
    KUniqueApplication a;
    a.exec();
 }
\end{verbatim}
\normalsize
 Note that it's not necessary to call {\bf start()}{\rm (p.\,\pageref{classKUniqueApplication_e1})} explicitly. It will be called automatically before creating KUnique\-Application if it hasn't been called yet, without any performance impact.

\begin{Desc}
\item[Returns:]true if registration is successful. false if another process was already running. \end{Desc}


Definition at line 93 of file kuniqueapplication.cpp.

References add\-Cmd\-Line\-Options(), KStartup\-Info\-Data::add\-Pid(), QCString::append(), KAbout\-Data::app\-Name(), DCOPClient::attach(), DCOPClient::call(), KStartup\-Info::current\-Startup\-Id\-Env(), KApplication::dcop\-Client(), endl(), QApplication::exit(), DCOPClient::is\-Application\-Registered(), QCString::is\-Empty(), KCmd\-Line\-Args::is\-Set(), KCmd\-Line\-Args::parsed\-Args(), DCOPClient::register\-As(), KStartup\-Info::send\-Change\-X(), KStartup\-Info::send\-Finish\-X(), QCString::set\-Num(), and DCOPClient::set\-Priority\-Call().\index{KUniqueApplication@{KUnique\-Application}!process@{process}}
\index{process@{process}!KUniqueApplication@{KUnique\-Application}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KUnique\-Application::process (const {\bf QCString} \& {\em fun}, const {\bf QByte\-Array} \& {\em data}, {\bf QCString} \& {\em reply\-Type}, {\bf QByte\-Array} \& {\em reply\-Data})\hspace{0.3cm}{\tt  [virtual]}}\label{classKUniqueApplication_a3}


Dispatches any incoming DCOP message for a new instance. 

If it is not a request for a new instance, return false. Overloaded from {\bf DCOPObject} to make sure that the application stays unique. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fun}]DCOP function signature \item[{\em data}]the data for the arguments \item[{\em reply\-Type}]the type of the reply value \item[{\em reply\-Data}]the reply \end{description}
\end{Desc}
\begin{Desc}
\item[See also:]{\bf DCOPObject} \end{Desc}


Reimplemented from {\bf DCOPObject}.

Definition at line 393 of file kuniqueapplication.cpp.

References DCOPObject::process().\index{KUniqueApplication@{KUnique\-Application}!newInstance@{newInstance}}
\index{newInstance@{newInstance}!KUniqueApplication@{KUnique\-Application}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int KUnique\-Application::new\-Instance ()\hspace{0.3cm}{\tt  [virtual]}}\label{classKUniqueApplication_a4}


Creates a new \char`\"{}instance\char`\"{} of the application. 

Usually this will involve making some calls into the GUI portion of your application asking for a new window to be created, possibly with some data already loaded based on the arguments received.

Command line arguments have been passed to {\bf KCmd\-Line\-Args}{\rm (p.\,\pageref{classKCmdLineArgs})} before this function is called and can be checked in the usual way.

The default implementation ensures the mainwindow of the already running instance is shown and activated if necessary. You should prefer using it from your overridden method instead of doing it directly.

Note that {\bf new\-Instance()}{\rm (p.\,\pageref{classKUniqueApplication_a4})} is called also in the first started application process.

\begin{Desc}
\item[Returns:]An exit value. The calling process will exit with this value. \end{Desc}


Definition at line 466 of file kuniqueapplication.cpp.

References QApplication::main\-Widget(), and KStartup\-Info::set\-New\-Startup\-Id().\index{KUniqueApplication@{KUnique\-Application}!restoringSession@{restoringSession}}
\index{restoringSession@{restoringSession}!KUniqueApplication@{KUnique\-Application}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KUnique\-Application::restoring\-Session ()}\label{classKUniqueApplication_a5}


Returns whether {\bf new\-Instance()}{\rm (p.\,\pageref{classKUniqueApplication_a4})} is being called while session restoration is in progress. 

\begin{Desc}
\item[Since:]{\bf KDE}{\rm (p.\,\pageref{namespaceKDE})} 3.3 \end{Desc}


Definition at line 461 of file kuniqueapplication.cpp.

References KApplication::is\-Restored().

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