]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/tdelwin.tex
Added wxHtmlPrintout::AddFilter so the same filters used for
[wxWidgets.git] / docs / latex / wx / tdelwin.tex
CommitLineData
a660d684
KB
1\section{Window deletion overview}\label{windowdeletionoverview}
2
3Classes: \helpref{wxCloseEvent}{wxcloseevent}, \helpref{wxWindow}{wxwindow}
4
5Window deletion can be a confusing subject, so this overview is provided
532372a3 6to help make it clear when and how you delete windows, or respond to user requests
a660d684
KB
7to close windows.
8
9\wxheading{What is the sequence of events in a window deletion?}
10
11When the user clicks on the system close button or system close command,
e3065973 12in a frame or a dialog, wxWindows calls \helpref{wxWindow::Close}{wxwindowclose}. This
f4fcc291 13in turn generates an EVT\_CLOSE event: see \helpref{wxCloseEvent}{wxcloseevent}.
a660d684 14
e3065973
JS
15It is the duty of the application to define a suitable event handler, and
16decide whether or not to destroy the window.
17If the application is for some reason forcing the application to close
cc81d32f 18(\helpref{wxCloseEvent::CanVeto}{wxcloseeventcanveto} returns false), the window should always be destroyed, otherwise there is the option to
a660d684 19ignore the request, or maybe wait until the user has answered a question
f6bcfd97 20before deciding whether it is safe to close. The handler for EVT\_CLOSE should
e3065973
JS
21signal to the calling code if it does not destroy the window, by calling
22\helpref{wxCloseEvent::Veto}{wxcloseeventveto}. Calling this provides useful information
23to the calling code.
a660d684
KB
24
25The wxCloseEvent handler should only call \helpref{wxWindow::Destroy}{wxwindowdestroy} to
26delete the window, and not use the {\bf delete} operator. This is because
27for some window classes, wxWindows delays actual deletion of the window until all events have been processed,
28since otherwise there is the danger that events will be sent to a non-existent window.
29
532372a3
JS
30As reinforced in the next section, calling Close does not guarantee that the window
31will be destroyed. Call \helpref{wxWindow::Destroy}{wxwindowdestroy} if you want to be
32certain that the window is destroyed.
33
a660d684
KB
34\wxheading{How can the application close a window itself?}
35
e3065973
JS
36Your application can either use \helpref{wxWindow::Close}{wxwindowclose} event just as
37the framework does, or it can call \helpref{wxWindow::Destroy}{wxwindowdestroy} directly.
cc81d32f 38If using Close(), you can pass a true argument to this function to tell the event handler
e3065973 39that we definitely want to delete the frame and it cannot be vetoed.
a660d684 40
e3065973
JS
41The advantage of using Close instead of Destroy is that it will call any clean-up code
42defined by the EVT\_CLOSE handler; for example it may close a document contained in
43a window after first asking the user whether the work should be saved. Close can be vetoed
cc81d32f 44by this process (return false), whereas Destroy definitely destroys the window.
a660d684
KB
45
46\wxheading{What is the default behaviour?}
47
e3065973 48The default close event handler for wxDialog simulates a Cancel command,
a660d684 49generating a wxID\_CANCEL event. Since the handler for this cancel event might
e3065973
JS
50itself call {\bf Close}, there is a check for infinite looping. The default handler
51for wxID\_CANCEL hides the dialog (if modeless) or calls EndModal(wxID\_CANCEL) (if modal).
532372a3 52In other words, by default, the dialog {\it is not destroyed} (it might have been created
e3065973
JS
53on the stack, so the assumption of dynamic creation cannot be made).
54
55The default close event handler for wxFrame destroys the frame using Destroy().
f4fcc291
JS
56%
57%Under Windows, wxDialog defines a handler for \helpref{wxWindow::OnCharHook}{wxwindowoncharhook} that
58%generates a Cancel event if the Escape key has been pressed.
a660d684
KB
59
60\wxheading{What should I do when the user calls up Exit from a menu?}
61
62You can simply call \helpref{wxWindow::Close}{wxwindowclose} on the frame. This
63will invoke your own close event handler which may destroy the frame.
64
65You can do checking to see if your application can be safely exited at this point,
66either from within your close event handler, or from within your exit menu command
67handler. For example, you may wish to check that all files have been saved.
68Give the user a chance to save and quit, to not save but quit anyway, or to cancel
69the exit command altogether.
70
71\wxheading{What should I do to upgrade my 1.xx OnClose to 2.0?}
72
f6bcfd97 73In wxWindows 1.xx, the {\bf OnClose} function did not actually delete 'this', but signaled
a660d684
KB
74to the calling function (either {\bf Close}, or the wxWindows framework) to delete
75or not delete the window.
76
a660d684
KB
77To update your code, you should provide an event table entry in your frame or
78dialog, using the EVT\_CLOSE macro. The event handler function might look like this:
79
80{\small%
81\begin{verbatim}
82 void MyFrame::OnCloseWindow(wxCloseEvent& event)
83 {
a660d684
KB
84 if (MyDataHasBeenModified())
85 {
86 wxMessageDialog* dialog = new wxMessageDialog(this,
87 "Save changed data?", "My app", wxYES_NO|wxCANCEL);
88
89 int ans = dialog->ShowModal();
e3065973 90 dialog->Destroy();
a660d684
KB
91
92 switch (ans)
93 {
94 case wxID_YES: // Save, then destroy, quitting app
95 SaveMyData();
96 this->Destroy();
97 break;
98 case wxID_NO: // Don't save; just destroy, quitting app
99 this->Destroy();
100 break;
101 case wxID_CANCEL: // Do nothing - so don't quit app.
102 default:
e3065973
JS
103 if (!event.CanVeto()) // Test if we can veto this deletion
104 this->Destroy(); // If not, destroy the window anyway.
105 else
106 event.Veto(); // Notify the calling code that we didn't delete the frame.
a660d684
KB
107 break;
108 }
109 }
110 }
111\end{verbatim}
112}%
113
114\wxheading{How do I exit the application gracefully?}
115
2fd284a4 116A wxWindows application automatically exits when the designated top window, or the
e3065973
JS
117last frame or dialog, is destroyed. Put any application-wide cleanup code in \helpref{wxApp::OnExit}{wxapponexit} (this
118is a virtual function, not an event handler).
a660d684
KB
119
120\wxheading{Do child windows get deleted automatically?}
121
122Yes, child windows are deleted from within the parent destructor. This includes any children
123that are themselves frames or dialogs, so you may wish to close these child frame or dialog windows
124explicitly from within the parent close handler.
125
126\wxheading{What about other kinds of window?}
127
128So far we've been talking about `managed' windows, i.e. frames and dialogs. Windows
129with parents, such as controls, don't have delayed destruction and don't usually have
130close event handlers, though you can implement them if you wish. For consistency,
131continue to use the \helpref{wxWindow::Destroy}{wxwindowdestroy} function instead
132of the {\bf delete} operator when deleting these kinds of windows explicitly.
133