DropFiles(3) User Contributed Perl Documentation DropFiles(3)NAME
Win32::GUI::DropFiles - Extension to Win32::GUI for shell Drag&Drop
integration
SYNOPSIS
use Win32::GUI;
use Win32::GUI::DropFiles;
# Create droppable window:
my $win = Win32::GUI::Window->new(
-name => 'win',
...
-acceptfiles => 1,
-onDropFiles => \&dropfiles_callback,
...
);
# Change the drop state of a window
$win->AcceptFiles(1);
$win->AcceptFiles(0);
# In the DropFiles callback
sub win_DropFiles {
my ($self, $dropObj) = @_;
# Get the number of dropped files
my $count = $dropObj->GetDroppedFiles();
# Get a list of the dropped file names
my @files = $dropObj->GetDroppedFiles();
# Get a particular file name (0 based index)
my $file = $dropObj->GetDroppedFile($index);
# determine if the drop happened in the client or
# non-client area of the window
my $clientarea = $dropObj->GetDropPos();
# get the mouse co-ordinates of the drop point,
# in client co-ordinates
my ($x, $y) = $dropObj->GetDropPos();
# get the drop point and (non-)client area information
my ($x, $y, $client) = $dropObj->GetDropPos();
return 0;
}
DESCRIPTION
Win32::GUI::DropFiles provides integration with the windows shell,
allowing files to be dragged from the shell (e.g. explorer.exe),
dropped onto a Win32::GUI window/control, and the path and filename of
the dropped files to be retrieved.
In order for a window to become a 'drop target' it must be created with
the -acceptfiles option set, or have called its AcceptFiles() method.
Once the window has been correctly initialised, then dropping a dragged
file on the window results in a DropFiles event being triggered. The
parameter to the event callback function is a Win32::GUI::DropFiles
object that can be used to retrieve the names and paths of the dropped
files.
Drop Object Methods
This section documents the public API for Win32::GUI::DropFiles
objects.
Constructor
The constructor is not public: Win32::GUI creates Win32::GUI::DropFiles
object when necessary, to pass to the DropFiles event handler
subroutine.
GetDroppedFiles
my $count = $dropObj->GetDroppedFiles();
my @files = $dropObj->GetDroppedFiles();
In scalar context returns the number of files dropped. In list context
returns a list of fully qualified path/filename for each dropped file.
GetDroppedFile
my $file = $dropObj->GetDroppedFile($index);
returns the fully qualified path/filename for the file referenced by
the zero-based "index".
If "index" is out of range, returns undef and sets $! and $^E.
GetDropPos
my $client = $dropObj->GetDropPos();
my ($x, $y, $client) = $dropObj->GetDropPos();
In scalar context returns a flag indicating whether the mouse was in
the client or non-client area of the window when the files were
dropped. In list context returns the x and y co-ordinates of the mouse
when the files were dropped (in client co-ordinates), as well as a flag
indicating whether the mouse was in the client or non-client area of
the window.
Destructor
The destructor is called automatically when the object goes out of
scope, and releases resources used by the system to store the filnames.
Typically the object goes out of scope at the end of the DropFiles
callback. Care should be taken to ensure that if a reference is taken
to the object that does not go out of scope at that time, that it is
eventually released, otherwise a memory leak will occur.
Win32 API functions
This section documents the Win32 API wrappers implemented by
Win32::GUI::DropFiles. Although these APIs are available, their use is
not recommended - the public Object Methods should provide better
access to these APIs.
See MSDN (<http://msdn.microsoft.com/>) for further details of the
Win32 API functions.
DragQueryFile
Win32::GUI::DropFiles::DragQueryFile($dropHandle, [$item]);
"dropHandle" is a win32 "HDROP" handle. "item" is a zero-based index
to the filename to be retrieved.
Returns the number of files dropped if "item" is omitted. Returns the
filenmame if "item" is provided.
Returns undef and sets $! and $^E on error.
DragQueryPoint
Win32::GUI::DropFiles::DragQueryPoint($dropHandle);
"dropHandle" is a win32 "HDROP" handle.
Returns a 3 element list of the x-position and y-position (in client
co-ordinates) and a flag that indicates whether the drop happened in
the client or non-client area of the window.
DragFinish
Win32::GUI::DropFiles::DragFinish($dropHandle);
"dropHandle" is a win32 "HDROP" handle.
Releases the resources and invalidates "dropHandle".
Does not return any value.
Unicode filenmame support
Supports unicode filenames under WinNT, Win2k, WinXP and higher.
Backwards compatibility with Win32::GUI::DragDrop
The GUI Loft includes a Win32::GUI::DragDrop module that exposes
similar functionality. If you want to continue to use that module,
then ensure that Win32::GUI::DropFiles is not used anywhere in your
program (even by other modules that you use). Loading
Win32::GUI::DropFiles changes the DropFiles event callback signature,
and will result in Win32::GUI::DragDrop failing.
It is recommended to upgrade to Win32::GUI::DropFiles.
SEE ALSO
MSDN <http://msdn.microsoft.com> for more information on
DragAcceptFiles, DragQueryFiles, DragQueryPos, DragFinish,
WS_EX_ACCEPTFILES, WM_DROPFILES
Win32::GUI
SUPPORT
Homepage: http://perl-win32-gui.sourceforge.net/ <http://perl-
win32-gui.sourceforge.net/>.
For further support join the users mailing list
("perl-win32-gui-users@lists.sourceforge.net") from the website at
http://lists.sourceforge.net/lists/listinfo/perl-win32-gui-users
<http://lists.sourceforge.net/lists/listinfo/perl-win32-gui-users>.
There is a searchable list archive at
<http://sourceforge.net/mail/?group_id=16572>
AUTHORS
Robert May ("robertemay@users.sourceforge.net") Reini Urban
("rurban@xray.net")
COPYRIGHT AND LICENSE
Copyright (C) 2006 by Robert May
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.2 2006-10-15 DropFiles(3)
