docs/latex/wx/tapp.tex

   1 \section{wxApp overview}\label{wxappoverview}
   2
   3 Classes: \helpref{wxApp}{wxapp}
   4
   5 A wxWidgets 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 wxWidgets, 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 wxWidgets know
  12 about the top window.
  13
  14 Note that the program's command line arguments, represented by {\it argc}
  15 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 however normally the application shuts down automatically,
  26 \helpref{see below}{wxappshutdownoverview}.
  27
  28 An example of defining an application follows:
  29
  30 \begin{verbatim}
  31 class DerivedApp : public wxApp
  32 {
  33 public:
  34   virtual bool OnInit();
  35 };
  36
  37 IMPLEMENT_APP(DerivedApp)
  38
  39 bool DerivedApp::OnInit()
  40 {
  41   wxFrame *the_frame = new wxFrame(NULL, ID_MYFRAME, argv[0]);
  42   ...
  43   the_frame->Show(true);
  44   SetTopWindow(the_frame);
  45
  46   return true;
  47 }
  48 \end{verbatim}
  49
  50 Note the use of IMPLEMENT\_APP(appClass), which allows wxWidgets to dynamically create an instance of the application object
  51 at the appropriate point in wxWidgets initialization. Previous versions of wxWidgets used
  52 to rely on the creation of a global application object, but this is no longer recommended,
  53 because required global initialization may not have been performed at application object
  54 construction time.
  55
  56 You can also use DECLARE\_APP(appClass) in a header file to declare the wxGetApp function which returns
  57 a reference to the application object. Otherwise you can only use the global
  58 \texttt{wxTheApp} pointer which is of type \texttt{wxApp *}.
  59
  60
  61 \subsection{Application shutdown}\label{wxappshutdownoverview}
  62
  63 The application normally shuts down when the last of its top level windows is
  64 closed. This is normally the expected behaviour and means that it is enough to
  65 call \helpref{Close()}{wxwindowclose} in response to the {\tt "Exit"} menu
  66 command if your program has a single top level window. If this behaviour is not
  67 desirable \helpref{wxApp::SetExitOnFrameDelete}{wxappsetexitonframedelete} can
  68 be called to change it. Note that starting from wxWidgets 2.3.3 such logic
  69 doesn't apply for the windows shown before the program enters the main loop: in
  70 other words, you can safely show a dialog from
  71 \helpref{wxApp::OnInit}{wxapponinit} and not be afraid that your application
  72 terminates when this dialog -- which is the last top level window for the
  73 moment -- is closed.
  74
  75
  76 Another aspect of the application shutdown is \helpref{OnExit}{wxapponexit}
  77 which is called when the application exits but {\it before} wxWidgets cleans up
  78 its internal structures. You should delete all wxWidgets object that you
  79 created by the time OnExit finishes. In particular, do {\bf not} destroy them
  80 from application class' destructor!
  81
  82 For example, this code may crash:
  83
  84 \begin{verbatim}
  85 class MyApp : public wxApp
  86 {
  87  public:
  88     wxCHMHelpController m_helpCtrl;
  89     ...
  90 };
  91 \end{verbatim}
  92
  93 The reason for that is that {\tt m\_helpCtrl} is a member object and is
  94 thus destroyed from MyApp destructor. But MyApp object is deleted after
  95 wxWidgets structures that wxCHMHelpController depends on were
  96 uninitialized! The solution is to destroy HelpCtrl in {\it OnExit}:
  97
  98 \begin{verbatim}
  99 class MyApp : public wxApp
 100 {
 101  public:
 102     wxCHMHelpController *m_helpCtrl;
 103     ...
 104 };
 105
 106 bool MyApp::OnInit()
 107 {
 108   ...
 109   m_helpCtrl = new wxCHMHelpController;
 110   ...
 111 }
 112
 113 int MyApp::OnExit()
 114 {
 115   delete m_helpCtrl;
 116   return 0;
 117 }
 118 \end{verbatim}