mention that creation time only lives up to its name under Windows

[wxWidgets.git] / docs / latex / wx / snglinst.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        snglinst.tex
%% Purpose:     wxSingleInstanceChecker documentation
%% Author:      Vadim Zeitlin
%% Modified by:
%% Created:     08.06.01
%% RCS-ID:      $Id$
%% Copyright:   (c) 2001 Vadim Zeitlin
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxSingleInstanceChecker}}\label{wxsingleinstancechecker}

wxSingleInstanceChecker class allows to check that only a single instance of a
program is running. To do it, you should create an object of this class. As
long as this object is alive, calls to 
\helpref{IsAnotherRunning()}{wxsingleinstancecheckerisanotherrunning} from
other processes will return {\tt TRUE}.

As the object should have the life span as big as possible, it makes sense to
create it either as a global or in \helpref{wxApp::OnInit}{wxapponinit}. For
example:

\begin{verbatim}
bool MyApp::OnInit()
{
    m_checker = new wxSingleInstanceChecker(GetAppName());
    if ( m_checker->IsAnotherRunning() )
    {
        wxLogError(_("Another program instance is already running, aborting."));

        return FALSE;
    }

    ... more initializations ...

    return TRUE;
}

int MyApp::OnExit()
{
    delete m_checker;

    return 0;
}
\end{verbatim}

This class is implemented for Win32 and Unix platforms supporting {\tt fcntl()}
system call only.

\wxheading{Derived from}

No base class

\wxheading{Include files}

<wx/snglinst.h>

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxSingleInstanceChecker::wxSingleInstanceChecker}\label{wxsingleinstancecheckerctor}

\func{}{wxSingleInstanceChecker}{\void}

Default ctor, use \helpref{Create()}{wxsingleinstancecheckercreate} after it.

\membersection{wxSingleInstanceChecker::wxSingleInstanceChecker}\label{wxsingleinstancecheckerwxsingleinstancechecker}

\func{}{wxSingleInstanceChecker}{\param{const wxString\& }{name}, \param{const wxString\& }{path = wxEmptyString}}

Like \helpref{Create()}{wxsingleinstancecheckercreate} but without
error checking.

\membersection{wxSingleInstanceChecker::Create}\label{wxsingleinstancecheckercreate}

\func{bool}{Create}{\param{const wxString\& }{name}, \param{const wxString\& }{path = wxEmptyString}}

Initialize the object if it had been created using the default constructor.
Note that you can't call Create() more than once, so calling it if the 
\helpref{non default ctor}{wxsingleinstancecheckerwxsingleinstancechecker} 
had been used is an error.

\wxheading{Parameters}

\docparam{name}{must be given and be as unique as possible. It is used as the
mutex name under Win32 and the lock file name under Unix. 
\helpref{GetAppName()}{wxappgetappname} may be a good value for this parameter}

\docparam{path}{is optional and is ignored under Win32 and used as the directory to
create the lock file in under Unix (default is 
\helpref{wxGetHomeDir()}{wxgethomedir})}

\wxheading{Return value}

Returns {\tt FALSE} if initialization failed, it doesn't mean that another
instance is running - use 
\helpref{IsAnotherRunning()}{wxsingleinstancecheckerisanotherrunning} to check
for it.

\membersection{wxSingleInstanceChecker::IsAnotherRunning}\label{wxsingleinstancecheckerisanotherrunning}

\constfunc{bool}{IsAnotherRunning}{\void}

Returns {\tt TRUE} if another copy of this program is already running, {\tt
FALSE} otherwise.

\membersection{wxSingleInstanceChecker::\destruct{wxSingleInstanceChecker}}\label{wxsingleinstancecheckerdtor}

\func{}{\destruct{wxSingleInstanceChecker}}{\void}

Destructor frees the associated resources.

Note that it is not virtual, this class is not meant to be used polymorphically