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 6to help make it clear when and how you delete windows, or respond to user requests 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, 12in a frame or a dialog, wxWidgets calls \helpref{wxWindow::Close}{wxwindowclose}. This 13in turn generates an EVT\_CLOSE event: see \helpref{wxCloseEvent}{wxcloseevent}. 14 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 18(\helpref{wxCloseEvent::CanVeto}{wxcloseeventcanveto} returns false), the window should always be destroyed, otherwise there is the option to 19ignore the request, or maybe wait until the user has answered a question 20before deciding whether it is safe to close. The handler for EVT\_CLOSE should 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. 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, wxWidgets 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 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 34\wxheading{How can the application close a window itself?} 35 36Your application can either use \helpref{wxWindow::Close}{wxwindowclose} event just as 37the framework does, or it can call \helpref{wxWindow::Destroy}{wxwindowdestroy} directly. 38If using Close(), you can pass a true argument to this function to tell the event handler 39that we definitely want to delete the frame and it cannot be vetoed. 40 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 44by this process (return false), whereas Destroy definitely destroys the window. 45 46\wxheading{What is the default behaviour?} 47 48The default close event handler for wxDialog simulates a Cancel command, 49generating a wxID\_CANCEL event. Since the handler for this cancel event might 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). 52In other words, by default, the dialog {\it is not destroyed} (it might have been created 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(). 56 57\wxheading{What should I do when the user calls up Exit from a menu?} 58 59You can simply call \helpref{wxWindow::Close}{wxwindowclose} on the frame. This 60will invoke your own close event handler which may destroy the frame. 61 62You can do checking to see if your application can be safely exited at this point, 63either from within your close event handler, or from within your exit menu command 64handler. For example, you may wish to check that all files have been saved. 65Give the user a chance to save and quit, to not save but quit anyway, or to cancel 66the exit command altogether. 67 68\wxheading{What should I do to upgrade my 1.xx OnClose to 2.0?} 69 70In wxWidgets 1.xx, the {\bf OnClose} function did not actually delete 'this', but signaled 71to the calling function (either {\bf Close}, or the wxWidgets framework) to delete 72or not delete the window. 73 74To update your code, you should provide an event table entry in your frame or 75dialog, using the EVT\_CLOSE macro. The event handler function might look like this: 76 77{\small% 78\begin{verbatim} 79 void MyFrame::OnCloseWindow(wxCloseEvent& event) 80 { 81 if (MyDataHasBeenModified()) 82 { 83 wxMessageDialog* dialog = new wxMessageDialog(this, 84 "Save changed data?", "My app", wxYES_NO|wxCANCEL); 85 86 int ans = dialog->ShowModal(); 87 dialog->Destroy(); 88 89 switch (ans) 90 { 91 case wxID_YES: // Save, then destroy, quitting app 92 SaveMyData(); 93 this->Destroy(); 94 break; 95 case wxID_NO: // Don't save; just destroy, quitting app 96 this->Destroy(); 97 break; 98 case wxID_CANCEL: // Do nothing - so don't quit app. 99 default: 100 if (!event.CanVeto()) // Test if we can veto this deletion 101 this->Destroy(); // If not, destroy the window anyway. 102 else 103 event.Veto(); // Notify the calling code that we didn't delete the frame. 104 break; 105 } 106 } 107 } 108\end{verbatim} 109}% 110 111\wxheading{How do I exit the application gracefully?} 112 113A wxWidgets application automatically exits when the last top level window 114(\helpref{wxFrame}{wxframe} or \helpref{wxDialog}{wxdialog}), is destroyed. Put 115any application-wide cleanup code in \helpref{wxApp::OnExit}{wxapponexit} (this 116is a virtual function, not an event handler). 117 118\wxheading{Do child windows get deleted automatically?} 119 120Yes, child windows are deleted from within the parent destructor. This includes any children 121that are themselves frames or dialogs, so you may wish to close these child frame or dialog windows 122explicitly from within the parent close handler. 123 124\wxheading{What about other kinds of window?} 125 126So far we've been talking about `managed' windows, i.e. frames and dialogs. Windows 127with parents, such as controls, don't have delayed destruction and don't usually have 128close event handlers, though you can implement them if you wish. For consistency, 129continue to use the \helpref{wxWindow::Destroy}{wxwindowdestroy} function instead 130of the {\bf delete} operator when deleting these kinds of windows explicitly. 131 132