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