moving forward

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52051 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/doxygen/overviews/windowdeletion.h

@@ -11,13 +11,17 @@
  @page overview_windowdeletion 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?
+
+ @section sequence 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
@@ -27,42 +31,56 @@
  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?
+
+ @section close 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?
+
+ @section default 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?
+
+ @section exit 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?
+
+ @section upgrade 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:
 
@@ -98,16 +116,21 @@
    }
  @endcode
 
- @b How do I exit the application gracefully?
+ @section exit_app 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?
+
+ @section deletion 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?
+
+ @section window_kinds 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,

docs/doxygen/overviews/windowids.h

@@ -10,22 +10,24 @@
 
  @page overview_windowids Window IDs overview
 
- @b See Also
+ @seealso
  #wxIdManager
  wxWindow::NewControlId
  wxWindow::UnreserveControlId
- #Introduction
- @ref windowidstypes_overview
- @ref windowidsusing_overview
+
+ @li @ref introduction
+ @li @ref overview_windowidstypes
+ @li @ref overview_windowidsusing
 
 
- @section windowidsoverviewintro Introduction
+ @section introduction Introduction
 
  Various contols and other parts of wxWidgets need an ID.  Sometimes the
  ID may be directly provided by the use or have a predefined value, such as
  @c wxID_OPEN. Often, however, the value of the ID is unimportant and is
  created automatically by calling wxWindow::NewControlId
  or by passing @c wxID_ANY as the ID of an object.
+
  There are two ways to generate an ID.  One way, is to start at a negative number,
  and for each new ID, return the next smallest number.  This is fine for systems
  that can used the full range of negative numbers for an ID, as this provides
@@ -36,6 +38,7 @@
  If the program runs long enough, depending on the program itself, using this first
  method would cause the IDs to wrap around into the positive ID range and cause possible
  clashes with any directly specified ID values.
+
  The other way is to keep track of the IDs returned by wxWindow::NewControlId
  and don't return them again until the ID is completely free and not being used by
  any other objects.  This will make sure that the ID values do not clash with one
@@ -43,7 +46,7 @@
  that can possibly be returned by wxWindow::NewControlId.
  Other IDs are not reference counted.
 
- @section windowidsoverviewtypes Data types
+ @section overview_windowidstypes Data types
 
  A wxWindowID is just the integer type for a window ID.  It should be used almost
  everywhere.  To help keep track of the count for the automatically generated IDs,
@@ -54,15 +57,17 @@
  As the wxWindowIDRef gets destroyed or its value changes, it will decrease the count
  of the used ID.  When there are no more wxWindowIDRef types with the created ID, the
  ID is considered free and can then be used again by wxWindow::NewControlId.
+
  If a created ID is not assigned to a wxWindowIDRef, then it remains reserved until it
  is unreserved manually with wxWindow::UnreserveControlId.
  However, if it is assigned to a wxWindowIDRef, then it will be unreserved automatically
  and will be considered free when the count is 0, and should NOT be manually unreserved.
+
  wxWindowIDRef can store both automatic IDs from wxWindow::NewControlId
  as well as normal IDs.  Reference counting is only done for the automatic IDs.  Also,
  wxWindowIDRef has conversion operators that allow it to be treated just like a wxWindowID.
 
- @section windowidsoverviewusing Using wxWindowIDRef
+ @section overview_windowidsusing Using wxWindowIDRef
 
  A wxWindowIDRef should be used in place of a wxWindowID where you want to make sure the
  ID is not created again by wxWindow::NewControlId