docs/latex/wx/snglinst.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        snglinst.tex
   3 %% Purpose:     wxSingleInstanceChecker documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     08.06.01
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) 2001 Vadim Zeitlin
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxSingleInstanceChecker}}\label{wxsingleinstancechecker}
  13
  14 wxSingleInstanceChecker class allows to check that only a single instance of a
  15 program is running. To do it, you should create an object of this class. As
  16 long as this object is alive, calls to
  17 \helpref{IsAnotherRunning()}{wxsingleinstancecheckerisanotherrunning} from
  18 other processes will return {\tt TRUE}.
  19
  20 As the object should have the life span as big as possible, it makes sense to
  21 create it either as a global or in \helpref{wxApp::OnInit}{wxapponinit}. For
  22 example:
  23
  24 \begin{verbatim}
  25 bool MyApp::OnInit()
  26 {
  27     m_checker = new wxSingleInstanceChecker(GetAppName());
  28     if ( m_checker->IsAnotherRunning() )
  29     {
  30         wxLogError(_("Another program instance is already running, aborting."));
  31
  32         return FALSE;
  33     }
  34
  35     ... more initializations ...
  36
  37     return TRUE;
  38 }
  39
  40 int MyApp::OnExit()
  41 {
  42     delete m_checker;
  43
  44     return 0;
  45 }
  46 \end{verbatim}
  47
  48 This class is implemented for Win32 and Unix platforms supporting {\tt fcntl()}
  49 system call only.
  50
  51 \wxheading{Derived from}
  52
  53 No base class
  54
  55 \wxheading{Include files}
  56
  57 <wx/snglinst.h>
  58
  59 \latexignore{\rtfignore{\wxheading{Members}}}
  60
  61 \membersection{wxSingleInstanceChecker::wxSingleInstanceChecker}\label{wxsingleinstancecheckerctor}
  62
  63 \func{}{wxSingleInstanceChecker}{\void}
  64
  65 Default ctor, use \helpref{Create()}{wxsingleinstancecheckercreate} after it.
  66
  67 \membersection{wxSingleInstanceChecker::wxSingleInstanceChecker}\label{wxsingleinstancecheckerwxsingleinstancechecker}
  68
  69 \func{}{wxSingleInstanceChecker}{\param{const wxString\& }{name}, \param{const wxString\& }{path = wxEmptyString}}
  70
  71 Like \helpref{Create()}{wxsingleinstancecheckercreate} but without
  72 error checking.
  73
  74 \membersection{wxSingleInstanceChecker::Create}\label{wxsingleinstancecheckercreate}
  75
  76 \func{bool}{Create}{\param{const wxString\& }{name}, \param{const wxString\& }{path = wxEmptyString}}
  77
  78 Initialize the object if it had been created using the default constructor.
  79 Note that you can't call Create() more than once, so calling it if the
  80 \helpref{non default ctor}{wxsingleinstancecheckerwxsingleinstancechecker}
  81 had been used is an error.
  82
  83 \wxheading{Parameters}
  84
  85 \docparam{name}{must be given and be as unique as possible. It is used as the
  86 mutex name under Win32 and the lock file name under Unix.
  87 \helpref{GetAppName()}{wxappgetappname} may be a good value for this parameter}
  88
  89 \docparam{path}{is optional and is ignored under Win32 and used as the directory to
  90 create the lock file in under Unix (default is
  91 \helpref{wxGetHomeDir()}{wxgethomedir})}
  92
  93 \wxheading{Return value}
  94
  95 Returns {\tt FALSE} if initialization failed, it doesn't mean that another
  96 instance is running - use
  97 \helpref{IsAnotherRunning()}{wxsingleinstancecheckerisanotherrunning} to check
  98 for it.
  99
 100 \membersection{wxSingleInstanceChecker::IsAnotherRunning}\label{wxsingleinstancecheckerisanotherrunning}
 101
 102 \constfunc{bool}{IsAnotherRunning}{\void}
 103
 104 Returns {\tt TRUE} if another copy of this program is already running, {\tt
 105 FALSE} otherwise.
 106
 107 \membersection{wxSingleInstanceChecker::\destruct{wxSingleInstanceChecker}}\label{wxsingleinstancecheckerdtor}
 108
 109 \func{}{\destruct{wxSingleInstanceChecker}}{\void}
 110
 111 Destructor frees the associated resources.
 112
 113 Note that it is not virtual, this class is not meant to be used polymorphically
 114