Bug 792565 - Clarify the documentation on nsITransferable::Init; irc-r=jdm
authorEhsan Akhgari <ehsan@mozilla.com>
Fri, 21 Sep 2012 14:18:25 -0400
changeset 107746 cf885613df289c0786c2a42a1903ebd7e360aa89
parent 107745 081b9207fe4ea2862fc7e1283faee6b019b322b2
child 107747 bbe80d33bbcd3e4900088eb5d059e6f1cd944ccb
push id1106
push userttaubert@mozilla.com
push dateSat, 22 Sep 2012 07:33:20 +0000
treeherderfx-team@9cfb80a82883 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
bugs792565
milestone18.0a1
Bug 792565 - Clarify the documentation on nsITransferable::Init; irc-r=jdm DONTBUILD
widget/nsITransferable.idl
--- a/widget/nsITransferable.idl
+++ b/widget/nsITransferable.idl
@@ -86,16 +86,31 @@ interface nsITransferable : nsISupports
 {
   const long kFlavorHasDataProvider = 0;
 
   /**
    * Initializes a transferable object.  This should be called on all
    * transferable objects.  Failure to do so will result in fatal assertions in
    * debug builds.
    *
+   * The load context is used to track whether the transferable is storing privacy-
+   * sensitive information.  For example, we try to delete data that you copy
+   * to the clipboard when you close a Private Browsing window.
+   *
+   * To get the appropriate load context in Javascript callers, one needs to get
+   * to the document that the transferable corresponds to, and then get the load
+   * context from the document like this:
+   *
+   * var loadContext = doc.defaultView.QueryInterface(Ci.nsIInterfaceRequestor)
+   *                                  .getInterface(Ci.nsIWebNavigation)
+   *                                  .QueryInterface(Ci.nsILoadContext);
+   *
+   * In C++ callers, if you have the corresponding document, you can just call
+   * nsIDocument::GetLoadContext to get to the load context object.
+   *
    * @param aContext the load context associated with the transferable object.
    *        This can be set to null if a load context is not available.
    */
   void init(in nsILoadContext aContext);
 
   /**
     * Computes a list of flavors (mime types as nsISupportsCString) that the transferable 
     * can export, either through intrinsic knowledge or output data converters.