DragQueryFile 函数的用法

DragQueryFile 函数

Retrieves the names of dropped files that result from a successful drag-and-drop operation.
用于一个成功文件拖拽后获取文件名称。

Syntax 语法

1
2
3
4
5
6
  UINT DragQueryFile(
  HDROP hDrop,
  UINT iFile,
  LPTSTR lpszFile,
  UINT cch
  );

Parameters 参数

hDrop

Identifier of the structure containing the file names of the dropped files.

用于区分”包含被拖拽文件名称结构”的句柄。
即存放所拖放文件名称的数据结构的句柄,也就是文件名缓冲区的句柄

iFile

Index of the file to query. If the value of the iFile parameter is 0xFFFFFFFF, DragQueryFile returns a count of the files dropped. If the value of the iFile parameter is between zero and the total number of files dropped, DragQueryFile copies the file name with the corresponding value to the buffer pointed to by the lpszFile parameter.

文件索引编号(用于指明所要查询文件的序号, 如果拖进多个文件,则索引编号从零开始),如果iFile值为 0xFFFFFFFF 时,返回的是拖曳到窗体上的文件的个数。如果iFile值在0和拖拽文件总数之间时,DragQueryFile拷贝与文件名存储缓冲区大小适应的文件名称到缓冲区中。

lpszFile

Address of a buffer to receive the file name of a dropped file when the function returns. This file name is a null-terminated string. If this parameter is NULL, DragQueryFile returns the required size, in characters, of the buffer.

函数返回时,用于存储拖拽文件名称的缓冲区指针。文件名称是一个以空终止“”结尾的字符串。如果此参数是NULL,DragQueryFile函数返回拖拽的文件数目。函数DragQueryFile得到的文件名,是带完整路径的文件名。

cch

Size, in characters, of the lpszFile buffer.

存储拖拽文件名称缓冲区的大小,即lpszFile指针所指缓冲区的字符数。

Return Value 返回值

hen the function copies a file name to the buffer, the return value is a count of the characters copied, not including the terminating null character.

如果函数拷贝文件名称到缓冲区中,返回值就是拷贝的字符数,不包括终止的NULL字符

If the index value is 0xFFFFFFFF, the return value is a count of the dropped files. Note that the index variable itself returns unchanged, and will therefore remain 0xFFFFFFFF.

如果文件索引值是0xFFFFFFFF,则返回值是被拖拽的文件总数,注意文件索引变量的值将保持不变,依然为0xFFFFFFFF。

If the index value is between zero and the total number of dropped files and the lpszFile buffer address is NULL, the return value is the required size, in characters, of the buffer, not including the terminating null character.

如果文件索引值在0和拖拽文件总数之间时,并且lpszFile值为NULL时 ,返回值是存储此被拖拽文件的名称所需要的缓冲区大小值,此值是不包括终止NULL字符的字符数。

Windows 95/98/Me: DragQueryFile is supported by the Microsoft Layer for Unicode. To use this, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.

Function Information

Minimum DLL Version shell32.dllversion 4.0 or later
Custom Implementation No
Header shellapi.h
Import library shell32.lib
Minimum operating systems Windows NT 3.1, Windows 95
Unicode Implemented as ANSI and Unicode versions.

相关拓展

VC实现文件管理器拖拽(Drag-and-Drop)

在日常的程序中,为了操作的方便,经常需要使用鼠标拖拽的方式把文件管理器中的文件拖拽到我们自己写的程序中,以下就简单介绍以下实现该操作的方法。

其实文件管理器的拖拽方式实现起来很简单,主要通过几个函数来实现,消息WM_DROPFILES的响应函数OnDropFiles,还有三个API函数:DragQueryFile,DragQueryPointDragFinish。 在启动拖拽动作时,操作系统会分配一块内存存储拖拽的文件的信息,并通过一个HDROP类型的句柄把该块内存的地址传递给函数OnDropFiles函数。

文件管理器拖拽方式的实质就是处理WM_DROPFILES消息,要让窗口或控件响应该消息,需要先设置Accept Files属性,可以通过在窗口或控件的属性页中勾选Accept Files,也可以通过调用CWnd类的成员函数DragAcceptFiles(TRUE)或API函数DragAcceptFiles(HWND hWnd,BOOL fAccept),可以在OnCreateOnInitDialog之类的函数中调用,它们的效果都是一样的。

设置了Accept Files属性后,就可以添加WM_DROPFILES消息的响应函数OnDropFiles了,ClassWizard不支持该函数,所以需要手动添加此函数,然后在该函数中调用上述的三个API函数,其代码如下:

void DragDemo::OnDropFiles(HDROP hDrop) 
 { 
 // 定义一个缓冲区来存放读取的文件名信息 
 char szFileName[MAX_PATH + 1] = {0}; 
 // 通过设置iFiles参数为0xFFFFFFFF,可以取得当前拖动的文件数量, 
 // 当设置为0xFFFFFFFF,函数间忽略后面连个参数。 
 UINT nFiles = DragQueryFile(hDrop, 0xFFFFFFFF, NULL, 0); 
 // 通过循环依次取得拖动文件的File Name信息,并把它添加到ListBox中 
 for(UINT i=0; i<nFiles; i++) 
 { 
 DragQueryFile(hDrop, i, szFileName, MAX_PATH); 
 m_listCtrl.AddString(szFileName); 
 } 
 // 结束此次拖拽操作,并释放分配的资源 
 DragFinish(hDrop); 
 } 

其中三个API函数的具体用法可以参照MSDN。由于本例的操作是直接拖拽的对话框上,所以不需要通过DragQueryPoint来取得鼠标松开时的位置,在实际的实现中,最好是为控件派生出一个类,在该类中定义消息响应函数OnDropFiles,这样就不需要查询鼠标的位置,也不需要设置鼠标的指针样式。

热评文章