WebUI: Add JavaScript lifecycle-control to WebUIMessageHandler.

content/public/browser/web_ui.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef CONTENT_PUBLIC_BROWSER_WEB_UI_H_
 #define CONTENT_PUBLIC_BROWSER_WEB_UI_H_
 
 #include <vector>
 
 #include "base/callback.h"
@@ skipping 73 matching lines @@
   typedef base::Callback<void(const base::ListValue*)> MessageCallback;
   virtual void RegisterMessageCallback(const std::string& message,
                                        const MessageCallback& callback) = 0;
 
   // This is only needed if an embedder overrides handling of a WebUIMessage and
   // then later wants to undo that, or to route it to a different WebUI object.
   virtual void ProcessWebUIMessage(const GURL& source_url,
                                    const std::string& message,
                                    const base::ListValue& args) = 0;
 
+  // Calling these functions directly is discouraged. It's generally preferred
+  // to call WebUIMessageHandler::CallJavascriptFunction, as that has
+  // lifecycle controls to prevent calling JavaScript before the page is ready.
+  //
   // Call a Javascript function by sending its name and arguments down to
   // the renderer.  This is asynchronous; there's no way to get the result
   // of the call, and should be thought of more like sending a message to
   // the page.
+  //
   // All function names in WebUI must consist of only ASCII characters.
   // There are variants for calls with more arguments.
   virtual void CallJavascriptFunction(const std::string& function_name) = 0;
   virtual void CallJavascriptFunction(const std::string& function_name,
                                       const base::Value& arg) = 0;
   virtual void CallJavascriptFunction(const std::string& function_name,
                                       const base::Value& arg1,
                                       const base::Value& arg2) = 0;
   virtual void CallJavascriptFunction(const std::string& function_name,
                                       const base::Value& arg1,
                                       const base::Value& arg2,
                                       const base::Value& arg3) = 0;
   virtual void CallJavascriptFunction(const std::string& function_name,
                                       const base::Value& arg1,
                                       const base::Value& arg2,
                                       const base::Value& arg3,
                                       const base::Value& arg4) = 0;
   virtual void CallJavascriptFunction(
       const std::string& function_name,
       const std::vector<const base::Value*>& args) = 0;
 };
 
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_BROWSER_WEB_UI_H_