Bug 1199729 - Part 6: Add some comments to DataTransfer to clarify use of methods, r=baku
authorMichael Layzell <michael@thelayzells.com>
Wed, 06 Sep 2017 11:39:03 -0400
changeset 661577 0ee09b4795cbfc759db5ea7bd0deb2e9674f8c13
parent 661576 83f49da70519de37b7af25f89dcd2883bf4ee441
child 661578 5a69e957b1986e6c2e8ae073dce7c8db5c2f5d9d
push id78830
push userasasaki@mozilla.com
push dateFri, 08 Sep 2017 19:44:43 +0000
Bug 1199729 - Part 6: Add some comments to DataTransfer to clarify use of methods, r=baku
--- a/dom/events/DataTransfer.h
+++ b/dom/events/DataTransfer.h
@@ -71,16 +71,17 @@ public:
   // hide the default constructor
   // this constructor is used only by the Clone method to copy the fields as
   // needed to a new data transfer.
+  // NOTE: Do not call this method directly.
   DataTransfer(nsISupports* aParent,
                EventMessage aEventMessage,
                const uint32_t aEffectAllowed,
                bool aCursorState,
                bool aIsExternal,
                bool aUserCancelled,
                bool aIsCrossDomainSubFrameDrop,
                int32_t aClipboardType,
@@ -293,16 +294,22 @@ public:
   // returns a weak reference to the drag image
   Element* GetDragImage(int32_t* aX, int32_t* aY) const
     *aX = mDragImageX;
     *aY = mDragImageY;
     return mDragImage;
+  // This method makes a copy of the DataTransfer object, with a few properties
+  // changed, and the mode updated to reflect the correct mode for the given
+  // event. This method is used during the drag operation to generate the
+  // DataTransfer objects for each event after `dragstart`. Event objects will
+  // lazily clone the DataTransfer stored in the DragSession (which is a clone
+  // of the DataTransfer used in the `dragstart` event) when requested.
   nsresult Clone(nsISupports* aParent, EventMessage aEventMessage,
                  bool aUserCancelled, bool aIsCrossDomainSubFrameDrop,
                  DataTransfer** aResult);
   // converts some formats used for compatibility in aInFormat into aOutFormat.
   // Text and text/unicode become text/plain, and URL becomes text/uri-list
   void GetRealFormat(const nsAString& aInFormat, nsAString& aOutFormat) const;