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/.

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. 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.

cpanm Win32::GUI

perl -MCPAN -e shell
install Win32::GUI