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 the
  25  wxApp::OnInit member defined for a class derived from wxApp.
  26
  27  @e OnInit will usually create a top window as a bare minimum.
  28  Unlike in earlier versions of wxWidgets, OnInit does not return a frame. Instead it
  29  returns a boolean value which indicates whether processing should continue (@true)
  30  or not (@false). You call wxApp::SetTopWindow to let wxWidgets know about the top window.
  31
  32  Note that the program's command line arguments, represented by @e argc
  33  and @e argv, are available from within wxApp member functions.
  34
  35  An application closes by destroying all windows. Because all frames must
  36  be destroyed for the application to exit, it is advisable to use parent
  37  frames wherever possible when creating new frames, so that deleting the
  38  top level frame will automatically delete child frames. The alternative
  39  is to explicitly delete child frames in the top-level frame's wxCloseEvent
  40  handler.
  41
  42  In emergencies the wxExit function can be called to kill the
  43  application however normally the application shuts down automatically,
  44  see @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 create
  69  an instance of the application object at the appropriate point in wxWidgets initialization.
  70  Previous versions of wxWidgets used to rely on the creation of a global application object,
  71  but this is no longer recommended, because required global initialization may not have
  72  been performed at application object construction time.
  73
  74  You can also use DECLARE_APP(appClass) in a header file to declare the wxGetApp function
  75  which returns a reference to the application object. Otherwise you can only use the global
  76  @c wxTheApp pointer which is of type @c wxApp *.
  77
  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 @c "Exit" menu command if your program has a
  85  single top level window. If this behaviour is not desirable wxApp::SetExitOnFrameDelete
  86  can be called to change it.
  87
  88  Note that such logic doesn't apply for the windows shown before the program enters the
  89  main loop: in other words, you can safely show a dialog from wxApp::OnInit and not be
  90  afraid that your application terminates when this dialog -- which is the last top level
  91  window for the moment -- is closed.
  92
  93  Another aspect of the application shutdown is wxApp::OnExit
  94  which is called when the application exits but @e before wxWidgets cleans up
  95  its internal structures. You should delete all wxWidgets object that you
  96  created by the time OnExit finishes.
  97
  98  In particular, do @b not destroy them from application class' destructor!
  99  For 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
 111  thus destroyed from MyApp destructor. But MyApp object is deleted after
 112  wxWidgets structures that wxCHMHelpController depends on were
 113  uninitialized! The solution 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