- 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/capi/cef_life_span_handler_capi.h

@@ -76,7 +76,7 @@ typedef struct _cef_life_span_handler_t {
       struct _cef_browser_settings_t* settings, int* no_javascript_access);
 
   ///
-  // Called after a new window is created.
+  // Called after a new browser is created.
   ///
   void (CEF_CALLBACK *on_after_created)(struct _cef_life_span_handler_t* self,
       struct _cef_browser_t* browser);
@@ -90,19 +90,73 @@ typedef struct _cef_life_span_handler_t {
       struct _cef_browser_t* browser);
 
   ///
-  // Called when a window has recieved a request to close. Return false (0) to
-  // proceed with the window close or true (1) to cancel the window close. If
-  // this is a modal window and a custom modal loop implementation was provided
-  // in run_modal() 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 cef_browser_host_t::close_browser() or indirectly
+  // if the browser is a top-level OS window created by CEF and the user
+  // attempts to close the window. This function 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 (0) 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 (0) will
+  // cause the browser object to be destroyed immediately. Return true (1) 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 cef_browser_host_t::CloseBrowser(false (0))
+  // instead of immediately closing (see the example below). This gives CEF an
+  // opportunity to process the 'onbeforeunload' event and optionally cancel the
+  // close before do_close() is called.
+  //
+  // The cef_life_span_handler_t::OnBeforeclose() function 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 cef_life_span_handler_t::run_modal() 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 do_close() 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
+  // cef_life_span_handler_t::OnBeforeclose() handler is called and
+  //     the browser object is destroyed.
+  // 11. Application exits by calling cef_quit_message_loop() if no other
+  // browsers
+  //     exist.
   ///
   int (CEF_CALLBACK *do_close)(struct _cef_life_span_handler_t* self,
       struct _cef_browser_t* browser);
 
   ///
-  // Called just before a window is closed. If this is a modal window and a
-  // custom modal loop implementation was provided in run_modal() 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 functions on the browser
+  // object after this callback returns. If this is a modal window and a custom
+  // modal loop implementation was provided in run_modal() this callback should
+  // be used to exit the custom modal loop. See do_close() documentation for
+  // additional usage information.
   ///
   void (CEF_CALLBACK *on_before_close)(struct _cef_life_span_handler_t* self,
       struct _cef_browser_t* browser);