basis/windows/dropfiles/dropfiles-docs.factor

   1 ! Copyright (C) 2017-2018 Alexander Ilin.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: arrays help.markup help.syntax kernel math
   4 ui.backend.windows ui.gestures windows.types ;
   5 IN: windows.dropfiles
   6
   7 ABOUT: "windows-dropfiles"
   8
   9 ARTICLE: "windows-dropfiles" "File drop gesture for Windows"
  10 "A window has to declare whether it wants to accept dropped files. By default files are rejected:"
  11 { $subsections
  12     accept-files
  13     reject-files
  14     world-accept-files
  15     world-reject-files
  16 }
  17 "When user drops files onto a window, the target gadget may handle the corresponding gesture:"
  18 { $subsections file-drop }
  19 "Implementation details:"
  20 { $subsections
  21     "about-dragdrop"
  22     init-message-filter
  23 } ;
  24
  25 ARTICLE: "about-dragdrop" "File drag-and-drop in Windows"
  26 "There are two mechanisms in Windows that can be used to drag-and-drop files across applications:"
  27 { $list
  28     { { $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." }
  29     { { $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." }
  30 }
  31 "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."
  32 $nl
  33 "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 } "." ;
  34
  35 HELP: init-message-filter
  36 { $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."
  37 $nl
  38 "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." }
  39 { $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." } ;
  40
  41 HELP: filecount-from-hdrop
  42 { $values
  43     { "hdrop" HDROP }
  44     { "n" number }
  45 }
  46 { $description "Return the number of files in the drop." } ;
  47
  48 HELP: filenames-from-hdrop
  49 { $values
  50     { "hdrop" HDROP }
  51     { "filenames" array }
  52 }
  53 { $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." } ;