]>
git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/app.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: topic overview
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
11 @page overview_app wxApp Overview
17 @section overview_app_intro Introduction
19 A wxWidgets application does not have a @e main procedure; the equivalent is
20 the wxApp::OnInit member defined for a class derived from wxApp.
22 @e OnInit will usually create a top window as a bare minimum. Unlike in earlier
23 versions of wxWidgets, OnInit does not return a frame. Instead it returns a
24 boolean value which indicates whether processing should continue (@true) or not
27 Note that the program's command line arguments, represented by @e argc and
28 @e argv, are available from within wxApp member functions.
30 An application closes by destroying all windows. Because all frames must be
31 destroyed for the application to exit, it is advisable to use parent frames
32 wherever possible when creating new frames, so that deleting the top level
33 frame will automatically delete child frames. The alternative is to explicitly
34 delete child frames in the top-level frame's wxCloseEvent handler.
36 In emergencies the wxExit function can be called to kill the application
37 however normally the application shuts down automatically, see
38 @ref overview_app_shutdown.
40 An example of defining an application follows:
43 class DerivedApp : public wxApp
46 virtual bool OnInit();
49 IMPLEMENT_APP(DerivedApp)
51 bool DerivedApp::OnInit()
53 wxFrame *the_frame = new wxFrame(NULL, ID_MYFRAME, argv[0]);
55 the_frame->Show(true);
61 Note the use of IMPLEMENT_APP(appClass), which allows wxWidgets to dynamically
62 create an instance of the application object at the appropriate point in
63 wxWidgets initialization. Previous versions of wxWidgets used to rely on the
64 creation of a global application object, but this is no longer recommended,
65 because required global initialization may not have been performed at
66 application object construction time.
68 You can also use DECLARE_APP(appClass) in a header file to declare the wxGetApp
69 function which returns a reference to the application object. Otherwise you can
70 only use the global @c wxTheApp pointer which is of type @c wxApp*.
74 @section overview_app_shutdown Application Shutdown
76 The application normally shuts down when the last of its top level windows is
77 closed. This is normally the expected behaviour and means that it is enough to
78 call wxWindow::Close() in response to the "Exit" menu command if your program
79 has a single top level window. If this behaviour is not desirable
80 wxApp::SetExitOnFrameDelete can be called to change it.
82 Note that such logic doesn't apply for the windows shown before the program
83 enters the main loop: in other words, you can safely show a dialog from
84 wxApp::OnInit and not be afraid that your application terminates when this
85 dialog -- which is the last top level window for the moment -- is closed.
87 Another aspect of the application shutdown is wxApp::OnExit which is called
88 when the application exits but @e before wxWidgets cleans up its internal
89 structures. You should delete all wxWidgets object that you created by the time
92 In particular, do @b not destroy them from application class' destructor! For
93 example, this code may crash:
96 class MyApp : public wxApp
99 wxCHMHelpController m_helpCtrl;
104 The reason for that is that @c m_helpCtrl is a member object and is thus
105 destroyed from MyApp destructor. But MyApp object is deleted after wxWidgets
106 structures that wxCHMHelpController depends on were uninitialized! The solution
107 is to destroy HelpCtrl in @e OnExit:
110 class MyApp : public wxApp
113 wxCHMHelpController *m_helpCtrl;
120 m_helpCtrl = new wxCHMHelpController;