docs/doxygen/overviews/windowdeletion.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        windowdeletion.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10
  11 @page overview_windowdeletion Window Deletion
  12
  13 Classes: wxCloseEvent, wxWindow
  14
  15 Window deletion can be a confusing subject, so this overview is provided to
  16 help make it clear when and how you delete windows, or respond to user requests
  17 to close windows.
  18
  19 @li @ref overview_windowdeletion_sequence
  20 @li @ref overview_windowdeletion_close
  21 @li @ref overview_windowdeletion_default
  22 @li @ref overview_windowdeletion_menuexit
  23 @li @ref overview_windowdeletion_exitapp
  24 @li @ref overview_windowdeletion_deletion
  25 @li @ref overview_windowdeletion_windowkinds
  26
  27
  28 <hr>
  29
  30
  31 @section overview_windowdeletion_sequence Sequence of Events During Window Deletion
  32
  33 When the user clicks on the system close button or system close command, in a
  34 frame or a dialog, wxWidgets calls wxWindow::Close. This in turn generates an
  35 EVT_CLOSE event: see wxCloseEvent.
  36
  37 It is the duty of the application to define a suitable event handler, and
  38 decide whether or not to destroy the window. If the application is for some
  39 reason forcing the application to close (wxCloseEvent::CanVeto returns @false),
  40 the window should always be destroyed, otherwise there is the option to ignore
  41 the request, or maybe wait until the user has answered a question before
  42 deciding whether it is safe to close. The handler for EVT_CLOSE should signal
  43 to the calling code if it does not destroy the window, by calling
  44 wxCloseEvent::Veto. Calling this provides useful information to the calling
  45 code.
  46
  47 The wxCloseEvent handler should only call wxWindow::Destroy to delete the
  48 window, and not use the @c delete operator. This is because for some window
  49 classes, wxWidgets delays actual deletion of the window until all events have
  50 been processed, since otherwise there is the danger that events will be sent to
  51 a non-existent window.
  52
  53 As reinforced in the next section, calling Close does not guarantee that the window
  54 will be destroyed. Call wxWindow::Destroy if you want to be
  55 certain that the window is destroyed.
  56
  57
  58 @section overview_windowdeletion_close Closing Windows
  59
  60 Your application can either use wxWindow::Close event just as the framework
  61 does, or it can call wxWindow::Destroy directly. If using Close(), you can pass
  62 a @true argument to this function to tell the event handler that we definitely
  63 want to delete the frame and it cannot be vetoed.
  64
  65 The advantage of using Close instead of Destroy is that it will call any
  66 clean-up code defined by the EVT_CLOSE handler; for example it may close a
  67 document contained in a window after first asking the user whether the work
  68 should be saved. Close can be vetoed by this process (return @false), whereas
  69 Destroy definitely destroys the window.
  70
  71
  72 @section overview_windowdeletion_default Default Window Close Behaviour
  73
  74 The default close event handler for wxDialog simulates a Cancel command,
  75 generating a wxID_CANCEL event. Since the handler for this cancel event might
  76 itself call Close, there is a check for infinite looping. The default handler
  77 for wxID_CANCEL hides the dialog (if modeless) or calls EndModal(wxID_CANCEL)
  78 (if modal). In other words, by default, the dialog @e is not destroyed (it
  79 might have been created on the stack, so the assumption of dynamic creation
  80 cannot be made).
  81
  82 The default close event handler for wxFrame destroys the frame using Destroy().
  83
  84
  85 @section overview_windowdeletion_menuexit User Calls to Exit From a Menu
  86
  87 What should I do when the user calls up Exit from a menu? You can simply call
  88 wxWindow::Close on the frame. This will invoke your own close event handler
  89 which may destroy the frame.
  90
  91 You can do checking to see if your application can be safely exited at this
  92 point, either from within your close event handler, or from within your exit
  93 menu command handler. For example, you may wish to check that all files have
  94 been saved. Give the user a chance to save and quit, to not save but quit
  95 anyway, or to cancel the exit command altogether.
  96
  97
  98 @section overview_windowdeletion_exitapp Exiting the Application Gracefully
  99
 100 A wxWidgets application automatically exits when the last top level window
 101 (wxFrame or wxDialog), is destroyed. Put any application-wide cleanup code in
 102 wxApp::OnExit (this is a virtual function, not an event handler).
 103
 104
 105 @section overview_windowdeletion_deletion Automatic Deletion of Child Windows
 106
 107 Child windows are deleted from within the parent destructor. This includes any
 108 children that are themselves frames or dialogs, so you may wish to close these
 109 child frame or dialog windows explicitly from within the parent close handler.
 110
 111
 112 @section overview_windowdeletion_windowkinds Other Kinds of Windows
 113
 114 So far we've been talking about 'managed' windows, i.e. frames and dialogs.
 115 Windows with parents, such as controls, don't have delayed destruction and
 116 don't usually have close event handlers, though you can implement them if you
 117 wish. For consistency, continue to use the wxWindow::Destroy function instead
 118 of the @c delete operator when deleting these kinds of windows explicitly.
 119
 120 */
 121