docs/doxygen/overviews/app.h

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