improve dnd interfaces

include/nana/gui/dragdrop.hpp

@@ -22,6 +22,14 @@
 
 namespace nana
 {
+	/// Drag and drop actions
+	enum class dnd_action
+	{
+		copy,	///< Copy the data to target.
+		move, 	///< Move the data to target.
+		link	///< Create a link from source data to target.
+	};
+
 	class simple_dragdrop
 	{
 		struct implementation;
@@ -67,7 +75,12 @@ namespace nana
 			data(const data&) = delete;
 			data& operator=(const data&) = delete;
 		public:
-			data();
+			/// Constructor
+			/**
+			 * Constructs a data object used for drag and drop
+			 * @param requested_action Indicates how the data to be transferred.
+			 */
+			data(dnd_action requested_action = dnd_action::copy);
 			data(data&&);
 			~data();
 
@@ -81,9 +94,29 @@ namespace nana
 		dragdrop(window source);
 		~dragdrop();
 
+		/// Condition of dragging
+		/***
+		 * The preciate function is called when press mouse button on the source window, it returns true to indicate the start of dragging. If the predicate is not set, it always start to drag.
+		 * @param predicate_fn A predicate function to be set.
+		 */
 		void condition(std::function<bool()> predicate_fn);
+
+		/// Transferred data
+		/**
+		 * Set a data generator. When drag begins, it is called to generate a data object for transferring.
+		 * @param generator It returns the data for transferring.
+		 */
 		void prepare_data(std::function<data()> generator);
-		void drop_finished(std::function<void(bool)> finish_fn);
+
+		/// Drop handler
+		/**
+		 * The drop handler is called when the drop operation is completed. There are 3 parameters for the handler
+		 *		dropped Indicates whether the data is accepted by a target window.
+		 *		executed_action Indicates the action returned by target window. Ignore if dropped is false.
+		 *		data_transferred The data object which is generated by the generator.
+		 * @param finish_fn The drop handling function.
+		 */
+		void drop_finished(std::function<void(bool dropped, dnd_action executed_action, data& data_transferred)> finish_fn);
 	private:
 		implementation* const impl_;
 	};