May 8, 2013 at 21:56

How to get a list of files transferred from Explorer via drag-and-drop in an application

Original author: Peter Johnson
  • Transfer

What is this article about:


Many programs allow the user to open files by dragging them from the explorer to the application window. As a rule, this is more convenient for the user, in contrast to the standard opening model, by choosing the menu “File -> Open” or by clicking the corresponding button on the toolbar, since in this case the user skips the step of working with the dialog box.
Adding this feature to your application will make it more “professional”.

How it works:


There are two main ways to add this functionality to a Windows application.
The first way is to use the standard Windows Drag-and-Drop API functions and handle the accompanying window messages.
The second method is the use of OLE (COM) technology, which provides advanced methods for transferring data between applications.
This article will discuss the first and easiest way.

Short review:


By default, drag and drop support for files in Windows applications is disabled.
To enable this feature, we must tell Windows that we want to receive drag and drop notifications, as well as specify a window responsible for processing notification data.
This window should be able to process the WM_DROPFILES message that arrives at the moment the user completes the drag and drop operation.
This message provides us with the opportunity to implement the Drop event handler, from which we can call various API functions to obtain information about what was transferred to us.
Upon completion of processing this message, it’s good form to notify Windows that we have processed this operation and no longer want to receive notifications about it.



Security Issues in Windows Vista (and Higher)
For security reasons, Windows Vista may not be able to drag and drop between windows with different security settings.
As a result, the receipt of the WM_DROPFILES message by your application may be blocked.

Let's consider step by step what needs to be done in a Delphi application for implementing file reception via Drag-and-Drop:

1. To get access to the necessary API functions, you need to connect the ShellAPI module:

uses 
  ShellAPI;

2. Call the DragAcceptFiles function, passing the first parameter to the handle of the window that will be responsible for processing the WM_DROPFILES message, and the second to True, indicating that this window is ready to receive notifications.
For example, this window will be the main form of our application:

DragAcceptFiles(Form1.Handle, True);

3. Process the WM_DROPFILES message. In Delphi, we can declare a message handler in the class of the main form of the application:

procedure WMDropFiles(var Msg: TWMDropFiles); message WM_DROPFILES;

4. When receiving the WM_DROPFILES message, use the DragQueryXXX functions to obtain information about the transferred files - see the explanations below.

5. Notify Windows that this message has finished processing.
This is done by calling the DragFinish function, into which the HDROP descriptor received when processing the WM_DROPFILES message is passed as a parameter.
Calling this function will free the resources used to store data about the Drag-and-Drop operation.

DragFinish(DropH);

6. When the application closes, you need to call the DragAcceptFiles function again, but this time pass False as the second parameter, which will notify Windows that the window is no longer processing the WM_DROPFILES message.

DragAcceptFiles(Form1.Handle, False);

Retrieving information about migrated files.


We will use two functions to obtain information about migrated files - DragQueryFile and DragQueryPoint.
Both of these functions require the HDROP descriptor parameter received when processing the WM_DROPFILES message.

Welcome all-trades - DragQueryFile.

Like most functions of the Windows API, DragQueryFile can implement several behaviors, depending on the parameters passed to it.
Such behavior sometimes leads to the fact that it is quite difficult for the programmer to remember the correct variant of using this function.
Let's look at its parameters (taking into account Delphi syntax):

  1. DropHandle: HDROP - operation descriptor transmitted by WM_DROPFILES message.
  2. Index: Integer - index of the file when querying the list of transferred files.
  3. FileName: PChar - pointer to the buffer to which the file name will be transferred.
  4. BufSize: Integer - the size of the FileName buffer.

Calling this function gives us the opportunity to obtain the following data:

  • Getting the number of transferred files. We can get this information by passing $ FFFFFFFF or DWORD (-1) in the Index parameter, while the FileName parameter must be “nil”, and the BufSize parameter, which controls the size of the FileName buffer, must be zero. The value returned by the function will be equal to the number of transferred files. Obviously enough.
  • Obtaining the size of the memory area required to store the file name based on the Index parameter (counting starts from zero, i.e. the first file is indexed in the list by zero). To do this, you need to specify the necessary file in the list using the Index parameter, leaving the FileName and BufSize parameters the same as in the previous paragraph. As a result, the function will return the number of bytes required to store the file name.
  • Getting the file name based on the passed index. To do this, in addition to specifying the file index via the Index parameter, prepare a buffer (slightly larger than the required size) that can receive data about the file path, plus a terminating zero.

So far, all this looks rather unclear, but at the end of the article we will consider all these stages in the form of independent code implemented in the form of a class.

Dragquerypoint

This function, in principle, is an alternative to DragQueryFile, by calling it, we can find out the coordinates at which the drag and drop files ended.

Consider its parameters:
  • DropHandle: HDROP - operation descriptor transmitted by WM_DROPFILES message.
  • var Point: TPoint - TPoint structure in which data about the point of completion of the Drag-and-Drop operation is returned. If the operation completed in the client area of ​​the window, then it will return a non-zero value, otherwise the function will return zero.

Consider everything in its entirety.


Create a new project.
We have a “fish” Delphi application and we need to add to it the ability to receive information about transferred files through Drag-and-Drop.
In our form, we will register the handler of the event of interest to us:

procedure TForm1.FormCreate(Sender: TObject);
begin
  // ... здесь некий код
  DragAcceptFiles(Self.Handle, True);
  // ... здесь некий код
end;

With this code, we signed up to receive WM_DROPFILES messages.
This is what the message handler looks like:

procedure TForm1.WMDropFiles(var Msg: TWMDropFiles);
var
  DropH: HDROP;               // дескриптор операции перетаскивания
  DroppedFileCount: Integer;  // количество переданных файлов
  FileNameLength: Integer;    // длина имени файла
  FileName: string;           // буфер, принимающий имя файла
  I: Integer;                 // итератор для прохода по списку
  DropPoint: TPoint;          // структура с координатами операции Drop
begin
  inherited;
  // Сохраняем дескриптор
  DropH := Msg.Drop;
  try
    // Получаем количество переданных файлов
    DroppedFileCount := DragQueryFile(DropH, $FFFFFFFF, nil, 0);
    // Получаем имя каждого файла и обрабатываем его
    for I := 0 to Pred(DroppedFileCount) do
    begin
      // получаем размер буфера
      FileNameLength := DragQueryFile(DropH, I, nil, 0);
      // создаем буфер, который может принять в себя строку с именем файла
      // (Delphi добавляет терминирующий ноль автоматически в конец строки)
      SetLength(FileName, FileNameLength);
      // получаем имя файла
      DragQueryFile(DropH, I, PChar(FileName), FileNameLength + 1);
      // что-то делаем с данным именем (все зависит от вашей фантазии)
      // ... код обработки пишем здесь
    end;
    // Опционально: получаем координаты, по которым произошла операция Drop
    DragQueryPoint(DropH, DropPoint);
    // ... что-то делаем с данными координатами здесь
  finally
    // Финализация - разрушаем дескриптор
    // не используйте DropH после выполнения данного кода...
    DragFinish(DropH);
  end;
  // Говорим о том, что сообщение обработано
  Msg.Result := 0;
end;

At the very beginning, we remember the handle of the Drop operation in a local variable.
This is done just for convenience, in the future we will use this value for calls to the DragQueryFile function (as well as for the rest of DragXXX), the first call of which we will get the number of files in the list.
Our next step is to get the name of each file in the loop by its index (files in the list are indexed from zero - do not forget this).
For each file, it is necessary to first find out the size of the buffer, which can be obtained using the second method of using DragQueryFile, which was described above, and then allocate memory for a line that will store the path to the file.
In conclusion, you need to read the file path to the allocated buffer by calling DragQueryFile in the third way.

After reading all the information about the file names, we can get the coordinates of the point where the user dragged the files.
After we have completed all the operations, we will call the DragFinish function to release the handle.
Please note that we must perform this action anyway, even when raising an exception.
Well, at the very end, we will indicate the result of processing the message by setting the value 0 in the Msg.Result structure, indicating, in such a way, that we successfully processed this message.

When the application finishes, we will disconnect the main window from receiving WM_DROPFILES messages.

procedure TForm1.FormDestroy(Sender: TObject);
begin
  // ... здесь некий код
  DragAcceptFiles(Self.Handle, False);
  // ... здесь некий код
end;

We implement this as a class (The Delphi Way)


If you agree that using the API directly, directly in the code of the base application, introduces some confusion, then I think you will agree that it is much more convenient to bring this functionality out, in the form of some auxiliary class.
As an example, here's a small class that can handle the WM_DROPFILES message.
It hides in itself a lot of code that we would have to implement ourselves without using it.
True, there is a nuance - we still need to notify Windows of the presence of a window that processes the WM_DROPFILES message.

The declaration of this class looks like this:

type
  TFileCatcher = class(TObject)
  private
    fDropHandle: HDROP;
    function GetFile(Idx: Integer): string;
    function GetFileCount: Integer;
    function GetPoint: TPoint;
  public
    constructor Create(DropHandle: HDROP);
    destructor Destroy; override;
    property FileCount: Integer read GetFileCount;
    property Files[Idx: Integer]: string read GetFile;
    property DropPoint: TPoint read GetPoint;
  end;

... well, and its implementation:

constructor TFileCatcher.Create(DropHandle: HDROP);
begin
  inherited Create;
  fDropHandle := DropHandle;
end;
destructor TFileCatcher.Destroy;
begin
  DragFinish(fDropHandle);
  inherited;
end;
function TFileCatcher.GetFile(Idx: Integer): string;
var
  FileNameLength: Integer;
begin
  FileNameLength := DragQueryFile(fDropHandle, Idx, nil, 0);
  SetLength(Result, FileNameLength);
  DragQueryFile(fDropHandle, Idx, PChar(Result), FileNameLength + 1);
end;
function TFileCatcher.GetFileCount: Integer;
begin
  Result := DragQueryFile(fDropHandle, $FFFFFFFF, nil, 0);
end;
function TFileCatcher.GetPoint: TPoint;
begin
  DragQueryPoint(fDropHandle, Result);
end;

In principle, there is nothing that has not been said before. You have already seen all the code.
The constructor accepts the HDROP descriptor, the destructor finalizes it with a call to DragFinish.
The list of files and their number are represented by the class properties.
All class methods are essentially a wrapper over the DragQueryFile and DragQueryPoint APIs.

Let's rewrite the WM_DROPFILES message handler, taking into account the use of TFileCatcher:

procedure TForm1.WMDropFiles(var Msg: TWMDropFiles);
var
  I: Integer;                 // итератор для прохода по списку
  DropPoint: TPoint;          // структура с координатами операции Drop
  Catcher: TFileCatcher;      // экземпляр класса TFileCatcher
begin
  inherited;
  Catcher := TFileCatcher.Create(Msg.Drop);
  try
    for I := 0 to Pred(Catcher.FileCount) do
    begin
      // ... код обработки пишем здесь
    end;
    DropPoint := Catcher.DropPoint;
    // ... что-то делаем с данными координатами здесь
  finally
    Catcher.Free;
  end;
  Msg.Result := 0;
end;

Future plans


The TFileCatcher class can be extended to hide all the APIs used in drag-and-drop operations. True, this will require access to the form window to intercept the WM_DROPFILES message.
One option for this implementation is to subclass the form window. True, this is beyond the scope of this article. However, if you want more information, check out my set of Drop Files components .

Demo app


The source code for the demo application is based on the code published in this article. The code was tested in versions four through seven of Delphi.

This source code is merely a proof of concept and is intended only to illustrate this article. It is not designed for use in its current form in finished applications. The code is provided on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. The code may be used in any way providing it is not sold or passed off as the work of another person. If you agree to all this then please download the code using the following link.


Download demo
Tags:

Also popular now: