X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/36c9828f702fb504b07968703bcd82f04196070a..d3f3e7f11d154aedd87a3155dfe28d4211ffa0b5:/docs/doxygen/overviews/windowdeletion.h diff --git a/docs/doxygen/overviews/windowdeletion.h b/docs/doxygen/overviews/windowdeletion.h index 9ab084fa97..d9443b79ab 100644 --- a/docs/doxygen/overviews/windowdeletion.h +++ b/docs/doxygen/overviews/windowdeletion.h @@ -1,119 +1,121 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: windowdeletion +// Name: windowdeletion.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -/*! - - @page windowdeletion_overview Window deletion overview - - Classes: #wxCloseEvent, #wxWindow - Window deletion can be a confusing subject, so this overview is provided - to help make it clear when and how you delete windows, or respond to user requests - to close windows. - @b What is the sequence of events in a window deletion? - When the user clicks on the system close button or system close command, - in a frame or a dialog, wxWidgets calls wxWindow::Close. This - in turn generates an EVT_CLOSE event: see #wxCloseEvent. - It is the duty of the application to define a suitable event handler, and - decide whether or not to destroy the window. - If the application is for some reason forcing the application to close - (wxCloseEvent::CanVeto returns @false), the window should always be destroyed, otherwise there is the option to - ignore the request, or maybe wait until the user has answered a question - before deciding whether it is safe to close. The handler for EVT_CLOSE should - signal to the calling code if it does not destroy the window, by calling - wxCloseEvent::Veto. Calling this provides useful information - to the calling code. - The wxCloseEvent handler should only call wxWindow::Destroy to - delete the window, and not use the @b delete operator. This is because - for some window classes, wxWidgets delays actual deletion of the window until all events have been processed, - since otherwise there is the danger that events will be sent to a non-existent window. - As reinforced in the next section, calling Close does not guarantee that the window - will be destroyed. Call wxWindow::Destroy if you want to be - certain that the window is destroyed. - @b How can the application close a window itself? - Your application can either use wxWindow::Close event just as - the framework does, or it can call wxWindow::Destroy directly. - If using Close(), you can pass a @true argument to this function to tell the event handler - that we definitely want to delete the frame and it cannot be vetoed. - The advantage of using Close instead of Destroy is that it will call any clean-up code - defined by the EVT_CLOSE handler; for example it may close a document contained in - a window after first asking the user whether the work should be saved. Close can be vetoed - by this process (return @false), whereas Destroy definitely destroys the window. - @b What is the default behaviour? - The default close event handler for wxDialog simulates a Cancel command, - generating a wxID_CANCEL event. Since the handler for this cancel event might - itself call @b Close, there is a check for infinite looping. The default handler - for wxID_CANCEL hides the dialog (if modeless) or calls EndModal(wxID_CANCEL) (if modal). - In other words, by default, the dialog @e is not destroyed (it might have been created - on the stack, so the assumption of dynamic creation cannot be made). - The default close event handler for wxFrame destroys the frame using Destroy(). - @b What should I do when the user calls up Exit from a menu? - You can simply call wxWindow::Close on the frame. This - will invoke your own close event handler which may destroy the frame. - You can do checking to see if your application can be safely exited at this point, - either from within your close event handler, or from within your exit menu command - handler. For example, you may wish to check that all files have been saved. - Give the user a chance to save and quit, to not save but quit anyway, or to cancel - the exit command altogether. - @b What should I do to upgrade my 1.xx OnClose to 2.0? - In wxWidgets 1.xx, the @b OnClose function did not actually delete 'this', but signaled - to the calling function (either @b Close, or the wxWidgets framework) to delete - or not delete the window. - To update your code, you should provide an event table entry in your frame or - dialog, using the EVT_CLOSE macro. The event handler function might look like this: - - @code - void MyFrame::OnCloseWindow(wxCloseEvent& event) - { - if (MyDataHasBeenModified()) - { - wxMessageDialog* dialog = new wxMessageDialog(this, - "Save changed data?", "My app", wxYES_NO|wxCANCEL); - - int ans = dialog-ShowModal(); - dialog-Destroy(); - - switch (ans) - { - case wxID_YES: // Save, then destroy, quitting app - SaveMyData(); - this-Destroy(); - break; - case wxID_NO: // Don't save; just destroy, quitting app - this-Destroy(); - break; - case wxID_CANCEL: // Do nothing - so don't quit app. - default: - if (!event.CanVeto()) // Test if we can veto this deletion - this-Destroy(); // If not, destroy the window anyway. - else - event.Veto(); // Notify the calling code that we didn't delete the frame. - break; - } - } - } - @endcode - - @b How do I exit the application gracefully? - A wxWidgets application automatically exits when the last top level window - (#wxFrame or #wxDialog), is destroyed. Put - any application-wide cleanup code in wxApp::OnExit (this - is a virtual function, not an event handler). - @b Do child windows get deleted automatically? - Yes, child windows are deleted from within the parent destructor. This includes any children - that are themselves frames or dialogs, so you may wish to close these child frame or dialog windows - explicitly from within the parent close handler. - @b What about other kinds of window? - So far we've been talking about 'managed' windows, i.e. frames and dialogs. Windows - with parents, such as controls, don't have delayed destruction and don't usually have - close event handlers, though you can implement them if you wish. For consistency, - continue to use the wxWindow::Destroy function instead - of the @b delete operator when deleting these kinds of windows explicitly. - - */ +/** +@page overview_windowdeletion Window Deletion + +Classes: wxCloseEvent, wxWindow + +Window deletion can be a confusing subject, so this overview is provided to +help make it clear when and how you delete windows, or respond to user requests +to close windows. + +@li @ref overview_windowdeletion_sequence +@li @ref overview_windowdeletion_close +@li @ref overview_windowdeletion_default +@li @ref overview_windowdeletion_menuexit +@li @ref overview_windowdeletion_exitapp +@li @ref overview_windowdeletion_deletion +@li @ref overview_windowdeletion_windowkinds + + +
+ + +@section overview_windowdeletion_sequence Sequence of Events During Window Deletion + +When the user clicks on the system close button or system close command, in a +frame or a dialog, wxWidgets calls wxWindow::Close. This in turn generates an +EVT_CLOSE event: see wxCloseEvent. + +It is the duty of the application to define a suitable event handler, and +decide whether or not to destroy the window. If the application is for some +reason forcing the application to close (wxCloseEvent::CanVeto returns @false), +the window should always be destroyed, otherwise there is the option to ignore +the request, or maybe wait until the user has answered a question before +deciding whether it is safe to close. The handler for EVT_CLOSE should signal +to the calling code if it does not destroy the window, by calling +wxCloseEvent::Veto. Calling this provides useful information to the calling +code. + +The wxCloseEvent handler should only call wxWindow::Destroy to delete the +window, and not use the @c delete operator. This is because for some window +classes, wxWidgets delays actual deletion of the window until all events have +been processed, since otherwise there is the danger that events will be sent to +a non-existent window. + +As reinforced in the next section, calling Close does not guarantee that the window +will be destroyed. Call wxWindow::Destroy if you want to be +certain that the window is destroyed. + + +@section overview_windowdeletion_close Closing Windows + +Your application can either use wxWindow::Close event just as the framework +does, or it can call wxWindow::Destroy directly. If using Close(), you can pass +a @true argument to this function to tell the event handler that we definitely +want to delete the frame and it cannot be vetoed. + +The advantage of using Close instead of Destroy is that it will call any +clean-up code defined by the EVT_CLOSE handler; for example it may close a +document contained in a window after first asking the user whether the work +should be saved. Close can be vetoed by this process (return @false), whereas +Destroy definitely destroys the window. + + +@section overview_windowdeletion_default Default Window Close Behaviour + +The default close event handler for wxDialog simulates a Cancel command, +generating a wxID_CANCEL event. Since the handler for this cancel event might +itself call Close, there is a check for infinite looping. The default handler +for wxID_CANCEL hides the dialog (if modeless) or calls EndModal(wxID_CANCEL) +(if modal). In other words, by default, the dialog @e is not destroyed (it +might have been created on the stack, so the assumption of dynamic creation +cannot be made). + +The default close event handler for wxFrame destroys the frame using Destroy(). + + +@section overview_windowdeletion_menuexit User Calls to Exit From a Menu + +What should I do when the user calls up Exit from a menu? You can simply call +wxWindow::Close on the frame. This will invoke your own close event handler +which may destroy the frame. + +You can do checking to see if your application can be safely exited at this +point, either from within your close event handler, or from within your exit +menu command handler. For example, you may wish to check that all files have +been saved. Give the user a chance to save and quit, to not save but quit +anyway, or to cancel the exit command altogether. + + +@section overview_windowdeletion_exitapp Exiting the Application Gracefully + +A wxWidgets application automatically exits when the last top level window +(wxFrame or wxDialog), is destroyed. Put any application-wide cleanup code in +wxApp::OnExit (this is a virtual function, not an event handler). + + +@section overview_windowdeletion_deletion Automatic Deletion of Child Windows + +Child windows are deleted from within the parent destructor. This includes any +children that are themselves frames or dialogs, so you may wish to close these +child frame or dialog windows explicitly from within the parent close handler. + + +@section overview_windowdeletion_windowkinds Other Kinds of Windows + +So far we've been talking about 'managed' windows, i.e. frames and dialogs. +Windows with parents, such as controls, don't have delayed destruction and +don't usually have close event handlers, though you can implement them if you +wish. For consistency, continue to use the wxWindow::Destroy function instead +of the @c delete operator when deleting these kinds of windows explicitly. + +*/