docs/latex/wx/tapp.tex

   1 \section{wxApp overview}\label{wxappoverview}
   2
   3 Classes: \helpref{wxApp}{wxapp}
   4
   5 A wxWindows application does not have a {\it main} procedure; the equivalent is the
   6 \rtfsp\helpref{OnInit}{wxapponinit} member defined for a class derived from wxApp.\rtfsp
   7 \rtfsp{\it OnInit} will usually create a top window as a bare minimum.
   8
   9 Unlike in earlier versions of wxWindows, OnInit does not return a frame. Instead it
  10 returns a boolean value which indicates whether processing should continue (TRUE) or not (FALSE).
  11 You call \helpref{wxApp::SetTopWindow}{wxappsettopwindow} to let wxWindows know
  12 about the top window.
  13
  14 Note that the program's command line arguments, represented by {\it
  15 argc} and {\it argv}, are available from within wxApp member functions.
  16
  17 An application closes by destroying all windows. Because all frames must
  18 be destroyed for the application to exit, it is advisable to use parent
  19 frames wherever possible when creating new frames, so that deleting the
  20 top level frame will automatically delete child frames. The alternative
  21 is to explicitly delete child frames in the top-level frame's \helpref{wxCloseEvent}{wxcloseevent}\rtfsp
  22 handler.
  23
  24 In emergencies the \helpref{wxExit}{wxexit} function can be called to kill the
  25 application.
  26
  27 An example of defining an application follows:
  28
  29 \begin{verbatim}
  30 class DerivedApp : public wxApp
  31 {
  32 public:
  33   virtual bool OnInit();
  34 };
  35
  36 IMPLEMENT_APP(DerivedApp)
  37
  38 bool DerivedApp::OnInit()
  39 {
  40   wxFrame *the_frame = new wxFrame(NULL, argv[0]);
  41   ...
  42   SetTopWindow(the_frame);
  43
  44   return TRUE;
  45 }
  46 \end{verbatim}
  47
  48 Note the use of IMPLEMENT\_APP(appClass), which allows wxWindows to dynamically create an instance of the application object
  49 at the appropriate point in wxWindows initialization. Previous versions of wxWindows used
  50 to rely on the creation of a global application object, but this is no longer recommended,
  51 because required global initialization may not have been performed at application object
  52 construction time.
  53
  54 You can also use DECLARE\_APP(appClass) in a header file to declare the wxGetApp function which returns
  55 a reference to the application object.
  56
  57 \subsection{Application shutdown}
  58
  59 \helpref{OnExit}{wxapponexit} is called when the application exits but {\it before}
  60 wxWindows cleans its internal structures. Your should delete all wxWindows object that
  61 your created by the time OnExit finishes. In particular, do {\bf not} destroy them
  62 from application class' destructor!
  63
  64 For example, this code may crash:
  65
  66 \begin{verbatim}
  67 class MyApp : public wxApp
  68 {
  69  public:
  70     wxCHMHelpController m_helpCtrl;
  71     ...
  72 };
  73 \end{verbatim}
  74
  75 The reason for that is that {\tt m\_helpCtrl} is a member object and is
  76 thus destroyed from MyApp destructor. But MyApp object is deleted after
  77 wxWindows structures that wxCHMHelpController depends on were
  78 uninitialized! The solution is to destroy HelpCtrl in {\it OnExit}:
  79
  80 \begin{verbatim}
  81 class MyApp : public wxApp
  82 {
  83  public:
  84     wxCHMHelpController *m_helpCtrl;
  85     ...
  86 };
  87
  88 bool MyApp::OnInit()
  89 {
  90   ...
  91   m_helpCtrl = new wxCHMHelpController;
  92   ...
  93 }
  94
  95 int MyApp::OnExit()
  96 {
  97   delete m_helpCtrl;
  98   return 0;
  99 }
 100 \end{verbatim}