docs/doxygen/overviews/app.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        app.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10
  11 @page overview_app wxApp Overview
  12
  13 Classes: wxApp
  14
  15 @li @ref overview_app_intro
  16 @li @ref overview_app_shutdown
  17
  18
  19 <hr>
  20
  21
  22 @section overview_app_intro Introduction
  23
  24 A wxWidgets application does not have a @e main procedure; the equivalent is
  25 the wxApp::OnInit member defined for a class derived from wxApp.
  26
  27 @e OnInit will usually create a top window as a bare minimum. Unlike in earlier
  28 versions of wxWidgets, OnInit does not return a frame. Instead it returns a
  29 boolean value which indicates whether processing should continue (@true) or not
  30 (@false). You call wxApp::SetTopWindow to let wxWidgets know about the top
  31 window.
  32
  33 Note that the program's command line arguments, represented by @e argc and
  34 @e argv, are available from within wxApp member functions.
  35
  36 An application closes by destroying all windows. Because all frames must be
  37 destroyed for the application to exit, it is advisable to use parent frames
  38 wherever possible when creating new frames, so that deleting the top level
  39 frame will automatically delete child frames. The alternative is to explicitly
  40 delete child frames in the top-level frame's wxCloseEvent handler.
  41
  42 In emergencies the wxExit function can be called to kill the application
  43 however normally the application shuts down automatically, see
  44 @ref overview_app_shutdown.
  45
  46 An example of defining an application follows:
  47
  48 @code
  49 class DerivedApp : public wxApp
  50 {
  51 public:
  52     virtual bool OnInit();
  53 };
  54
  55 IMPLEMENT_APP(DerivedApp)
  56
  57 bool DerivedApp::OnInit()
  58 {
  59     wxFrame *the_frame = new wxFrame(NULL, ID_MYFRAME, argv[0]);
  60     ...
  61     the_frame->Show(true);
  62     SetTopWindow(the_frame);
  63
  64     return true;
  65 }
  66 @endcode
  67
  68 Note the use of IMPLEMENT_APP(appClass), which allows wxWidgets to dynamically
  69 create an instance of the application object at the appropriate point in
  70 wxWidgets initialization. Previous versions of wxWidgets used to rely on the
  71 creation of a global application object, but this is no longer recommended,
  72 because required global initialization may not have been performed at
  73 application object construction time.
  74
  75 You can also use DECLARE_APP(appClass) in a header file to declare the wxGetApp
  76 function which returns a reference to the application object. Otherwise you can
  77 only use the global @c wxTheApp pointer which is of type @c wxApp*.
  78
  79
  80 @section overview_app_shutdown Application Shutdown
  81
  82 The application normally shuts down when the last of its top level windows is
  83 closed. This is normally the expected behaviour and means that it is enough to
  84 call wxWindow::Close() in response to the "Exit" menu command if your program
  85 has a single top level window. If this behaviour is not desirable
  86 wxApp::SetExitOnFrameDelete can be called to change it.
  87
  88 Note that such logic doesn't apply for the windows shown before the program
  89 enters the main loop: in other words, you can safely show a dialog from
  90 wxApp::OnInit and not be afraid that your application terminates when this
  91 dialog -- which is the last top level window for the moment -- is closed.
  92
  93 Another aspect of the application shutdown is wxApp::OnExit which is called
  94 when the application exits but @e before wxWidgets cleans up its internal
  95 structures. You should delete all wxWidgets object that you created by the time
  96 OnExit finishes.
  97
  98 In particular, do @b not destroy them from application class' destructor! For
  99 example, this code may crash:
 100
 101 @code
 102 class MyApp : public wxApp
 103 {
 104 public:
 105     wxCHMHelpController m_helpCtrl;
 106     ...
 107 };
 108 @endcode
 109
 110 The reason for that is that @c m_helpCtrl is a member object and is thus
 111 destroyed from MyApp destructor. But MyApp object is deleted after wxWidgets
 112 structures that wxCHMHelpController depends on were uninitialized! The solution
 113 is to destroy HelpCtrl in @e OnExit:
 114
 115 @code
 116 class MyApp : public wxApp
 117 {
 118 public:
 119     wxCHMHelpController *m_helpCtrl;
 120     ...
 121 };
 122
 123 bool MyApp::OnInit()
 124 {
 125     ...
 126     m_helpCtrl = new wxCHMHelpController;
 127     ...
 128 }
 129
 130 int MyApp::OnExit()
 131 {
 132     delete m_helpCtrl;
 133     return 0;
 134 }
 135 @endcode
 136
 137 */
 138