windows.dropfiles[-docs]: implement the file-drop gesture

[factor.git] / basis / windows / dropfiles / dropfiles-docs.factor

diff --git a/basis/windows/dropfiles/dropfiles-docs.factor b/basis/windows/dropfiles/dropfiles-docs.factor
index 80292b3951d7c2216465b8a047d2dc0c2e5374d9..661f8215dd6e7f0431760ea660288d85826665cc 100644 (file)
--- a/basis/windows/dropfiles/dropfiles-docs.factor
+++ b/basis/windows/dropfiles/dropfiles-docs.factor
@@ -1,18 +1,53 @@
 ! Copyright (C) 2017 Alexander Ilin.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: help.markup help.syntax kernel windows.ole32 ;
+USING: arrays help.markup help.syntax kernel math
+ui.backend.windows ui.gestures windows.types ;
 IN: windows.dropfiles
 
+ABOUT: "windows-dropfiles"
+
+ARTICLE: "windows-dropfiles" "File drop gesture for Windows"
+"A window has to declare whether it wants to accept dropped files. By default files are rejected:"
+{ $subsections
+    accept-files
+    reject-files
+    world-accept-files
+    world-reject-files
+}
+"When user drops files onto a window, the target gadget may handle the corresponding gesture:"
+{ $subsections file-drop }
+"Implementation details:"
+{ $subsections
+    "about-dragdrop"
+    init-message-filter
+} ;
+
+ARTICLE: "about-dragdrop" "File drag-and-drop in Windows"
+"There are two mechanisms in Windows that can be used to drag-and-drop files across applications:"
+{ $list
+    { { $snippet "WM_DROPFILES" } " - was introduced back in the early days, it is a message that's posted to a window's message queue after the user has dropped some files on it. While handling the message, the application can fetch the list of the dropped files and the mouse position of the drop." }
+    { { $snippet "IDropTarget" } " - an OLE reinvention of the same. It provides more fine-grained capabilities of dynamically accepting or rejecting the drop based on the mouse location and the contents of the drop, while the user still drags the files over the window." }
+}
+"Windows Vista has introduced some security features that made it impossible for the OLE to work between two applications with different security tokens. E.g. if one of the applications is ran with administrative privileges, and the other is without, the OLE drag-and-drop will not work between them."
+$nl
+"By default, WM_DROPFILES doesn't work either, because the necessary window messages are filtered out from the queue, but it is possible to configure the filters and make it work, see " { $link init-message-filter } "." ;
+
+HELP: init-message-filter
+{ $description "Call " { $snippet "ChangeWindowMessageFilter" } " to allow the window messages necessary for file dropping pass through the filters. This will have a process-wide effect, and will only be called once (when " { $link init-message-filter-done? } " is " { $link POSTPONE: f } ")."
+$nl
+"The API function is only available since Windows Vista, and is not needed in earlier versions. On Windows XP the missing function will cause an exception on the first call, which will be suppressed, and no more calls will be made." }
+{ $notes "It is generally preferrable to use " { $snippet "ChangeWindowMessageFilterEx" } ", because it has a per-window-handle effect, thus gives a more fine-grained security control. Unfortunately, the " { $snippet "Ex" } "-version is only available since Windows 7, and in any case the " { $link add-wm-handler } " has global effect for all Factor native windows, so it's not like we are exposing any additional code to potential exploitation." } ;
+
 HELP: filecount-from-hdrop
 { $values
-    { "hdrop" null }
-    { "n" null }
+    { "hdrop" HDROP }
+    { "n" number }
 }
-{ $description "" } ;
+{ $description "Return the number of files in the drop." } ;
 
 HELP: filenames-from-hdrop
 { $values
-    { "hdrop" null }
-    { "filenames" null }
+    { "hdrop" HDROP }
+    { "filenames" array }
 }
-{ $description "" } ;
+{ $description "Return an array of file names in the drop. Each file name is a string with a full path to a file or a folder." } ;