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{Data structures}
  56
  57 \latexignore{\rtfignore{\wxheading{Members}}}
  58
  59 \membersection{wxSingleInstanceChecker::wxSingleInstanceChecker}\label{wxsingleinstancecheckerctor}
  60
  61 \func{}{wxSingleInstanceChecker}{\void}
  62
  63 Default ctor, use \helpref{Create()}{wxsingleinstancecheckercreate} after it.
  64
  65 \membersection{wxSingleInstanceChecker::wxSingleInstanceChecker}\label{wxsingleinstancecheckerwxsingleinstancechecker}
  66
  67 \func{}{wxSingleInstanceChecker}{\param{const wxString\& }{name}, \param{const wxString\& }{path = wxEmptyString}}
  68
  69 Like \helpref{Create()}{wxsingleinstancecheckercreate} but without
  70 error checking.
  71
  72 \membersection{wxSingleInstanceChecker::Create}\label{wxsingleinstancecheckercreate}
  73
  74 \func{bool}{Create}{\param{const wxString\& }{name}, \param{const wxString\& }{path = wxEmptyString}}
  75
  76 Initialize the object if it had been created using the default constructor.
  77 Note that you can't call Create() more than once, so calling it if the
  78 \helpref{non default ctor}{wxsingleinstancecheckerwxsingleinstancechecker}
  79 had been used is an error.
  80
  81 \wxheading{Parameters}
  82
  83 \docparam{name}{must be given and be as unique as possible. It is used as the
  84 mutex name under Win32 and the lock file name under Unix.
  85 \helpref{GetAppName()}{wxappgetappname} may be a good value for this parameter}
  86
  87 \docparam{path}{is optional and is ignored under Win32 and used as the directory to
  88 create the lock file in under Unix (default is
  89 \helpref{wxGetHomeDir()}{wxgethomedir})}
  90
  91 \wxheading{Return value}
  92
  93 Returns {\tt FALSE} if initialization failed, it doesn't mean that another
  94 instance is running - use
  95 \helpref{IsAnotherRunning()}{wxsingleinstancecheckerisanotherrunning} to check
  96 for it.
  97
  98 \membersection{wxSingleInstanceChecker::IsAnotherRunning}\label{wxsingleinstancecheckerisanotherrunning}
  99
 100 \constfunc{bool}{IsAnotherRunning}{\void}
 101
 102 Returns {\tt TRUE} if another copy of this program is already running, {\tt
 103 FALSE} otherwise.
 104
 105 \membersection{wxSingleInstanceChecker::\destruct{wxSingleInstanceChecker}}\label{wxsingleinstancecheckerdtor}
 106
 107 \func{}{\destruct{wxSingleInstanceChecker}}{\void}
 108
 109 Destructor frees the associated resources.
 110
 111 Note that it is not virtual, this class is not meant to be used polymorphically
 112