- Change the way that application shutdown works in order to support JavaScript 'onbeforeunload' handling (issue #853). See comments in cef_life_span_handler.h for a detailed description of the new shutdown process.

- Fix a crash on Linux during window destruction (issue #681).

git-svn-id: https://chromiumembedded.googlecode.com/svn/trunk@1149 5089003a-bbd8-11dd-ad1f-f1f9622dbc98

include/cef_life_span_handler.h

@@ -77,7 +77,7 @@ class CefLifeSpanHandler : public virtual CefBase {
   }
 
   ///
-  // Called after a new window is created.
+  // Called after a new browser is created.
   ///
   /*--cef()--*/
   virtual void OnAfterCreated(CefRefPtr<CefBrowser> browser) {}
@@ -91,19 +91,73 @@ class CefLifeSpanHandler : public virtual CefBase {
   virtual bool RunModal(CefRefPtr<CefBrowser> browser) { return false; }
 
   ///
-  // Called when a window has recieved a request to close. Return false to
-  // proceed with the window close or true to cancel the window close. If this
-  // is a modal window and a custom modal loop implementation was provided in
-  // RunModal() this callback should be used to restore the opener window to a
-  // usable state.
+  // Called when a browser has recieved a request to close. This may result
+  // directly from a call to CefBrowserHost::CloseBrowser() or indirectly if the
+  // browser is a top-level OS window created by CEF and the user attempts to
+  // close the window. This method will be called after the JavaScript
+  // 'onunload' event has been fired. It will not be called for browsers after
+  // the associated OS window has been destroyed (for those browsers it is no
+  // longer possible to cancel the close).
+  //
+  // If CEF created an OS window for the browser returning false will send an OS
+  // close notification to the browser window's top-level owner (e.g. WM_CLOSE
+  // on Windows, performClose: on OS-X and "delete_event" on Linux). If no OS
+  // window exists (window rendering disabled) returning false will cause the
+  // browser object to be destroyed immediately. Return true if the browser is
+  // parented to another window and that other window needs to receive close
+  // notification via some non-standard technique.
+  //
+  // If an application provides its own top-level window it should handle OS
+  // close notifications by calling CefBrowserHost::CloseBrowser(false) instead
+  // of immediately closing (see the example below). This gives CEF an
+  // opportunity to process the 'onbeforeunload' event and optionally cancel the
+  // close before DoClose() is called.
+  //
+  // The CefLifeSpanHandler::OnBeforeClose() method will be called immediately
+  // before the browser object is destroyed. The application should only exit
+  // after OnBeforeClose() has been called for all existing browsers.
+  //
+  // If the browser represents a modal window and a custom modal loop
+  // implementation was provided in CefLifeSpanHandler::RunModal() this callback
+  // should be used to restore the opener window to a usable state.
+  //
+  // By way of example consider what should happen during window close when the
+  // browser is parented to an application-provided top-level OS window.
+  // 1.  User clicks the window close button which sends an OS close
+  //     notification (e.g. WM_CLOSE on Windows, performClose: on OS-X and
+  //     "delete_event" on Linux).
+  // 2.  Application's top-level window receives the close notification and:
+  //     A. Calls CefBrowserHost::CloseBrowser(false).
+  //     B. Cancels the window close.
+  // 3.  JavaScript 'onbeforeunload' handler executes and shows the close
+  //     confirmation dialog (which can be overridden via
+  //     CefJSDialogHandler::OnBeforeUnloadDialog()).
+  // 4.  User approves the close.
+  // 5.  JavaScript 'onunload' handler executes.
+  // 6.  Application's DoClose() handler is called. Application will:
+  //     A. Call CefBrowserHost::ParentWindowWillClose() to notify CEF that the
+  //        parent window will be closing.
+  //     B. Set a flag to indicate that the next close attempt will be allowed.
+  //     C. Return false.
+  // 7.  CEF sends an OS close notification.
+  // 8.  Application's top-level window receives the OS close notification and
+  //     allows the window to close based on the flag from #6B.
+  // 9.  Browser OS window is destroyed.
+  // 10. Application's CefLifeSpanHandler::OnBeforeClose() handler is called and
+  //     the browser object is destroyed.
+  // 11. Application exits by calling CefQuitMessageLoop() if no other browsers
+  //     exist.
   ///
   /*--cef()--*/
   virtual bool DoClose(CefRefPtr<CefBrowser> browser) { return false; }
 
   ///
-  // Called just before a window is closed. If this is a modal window and a
-  // custom modal loop implementation was provided in RunModal() this callback
-  // should be used to exit the custom modal loop.
+  // Called just before a browser is destroyed. Release all references to the
+  // browser object and do not attempt to execute any methods on the browser
+  // object after this callback returns. If this is a modal window and a custom
+  // modal loop implementation was provided in RunModal() this callback should
+  // be used to exit the custom modal loop. See DoClose() documentation for
+  // additional usage information.
   ///
   /*--cef()--*/
   virtual void OnBeforeClose(CefRefPtr<CefBrowser> browser) {}