NAME

DragDrop - create and manipulate widgets whose selections can be dragged and dropped

DropSite - create and manipulate DropSites for Dragged selections

SYNOPSIS

    use Tk::DragDrop;
    use Tk::DropSite;

    $source = $widget->DragDrop(-event => '<Event>',
                                -sitetypes => ['Local'],
                                -handlers => [[\&callback],
                                              [-type => 'TYPENAME',
                                                \&callback]],
                                );

    $drop = $widget->DropSite(-droptypes => ['Local'],
                              -dropcommand => [\&Dropit,?params?],
                              );

DESCRIPTION

NB This is unofficial documentation, believed to be correct but neither complete not definitive. Caveat programmer!

DragDrop implements drag-and-drop for Tk apps. It should work on any platform for local (within one application) droptypes, but only the Sun interface is defined for global (interapplication) droptypes.

User can drag objects with the mouse (Button-1 by default) from DragDrop sources, and drop them on DropSites. By default, pressing any key during the Drag operation will abort it. There is support for different types of information transfer (eg STRING, ATOM, INTEGER - see Tk::Selection and/or the X Inter-Client Communication Conventions Manual (ICCCM) for details) and also user-defined types (eg FILE_NAME in the example code below) via user-defined handlers.

Local (intra-application) transfer is via the X Selection mechanism. Global (interapplication) transfer uses the Sun protocols defined in the Tk::DragDrop::Sunconstant module.

Example Code

 use Tk;
 use Tk::DragDrop;
 use Tk::DropSite;

 @data = ('One','Two','Three', 'Four');

 $w = MainWindow->new();
 $lb = $w->Listbox->pack;
 $lb->insert('end', @data);
 $lab = $w->Label(-text => "Drop here!")->pack;

 $source = $lb->DragDrop(-event => '<B1-Motion>',
                         -sitetypes => [qw(Local)],
                         -handlers => [[\&send_string],
                                       [-type => 'FILE_NAME',
                                        \&send_file]]);
 $drop = $lab->DropSite(-droptypes => [qw(Local)],
                        -dropcommand => [\&Dropit, $lb],
                        -entercommand => [\&SiteEntry, $lab],
                        );
 MainLoop();

 sub send_file {
     my ($offset,$max) = @_;

     return __FILE__;
 }

 sub send_string {
    my ($offset,$max) = @_;

    my ($lb_sel) = $lb->curselection;
    my ($req) = $lb->get($lb_sel);
    return $req;
 }

 sub Dropit {
    my ($lb,$seln) = @_;

    my ($req) = $lb->SelectionGet('-selection'=>$seln,'STRING');
    print "$req\n";
 }

 sub SiteEntry {
     my ($w, $entry, @data) = @_;
     $w->configure(-relief => $entry == 1 ? 'raised' : 'sunken');
 }

CONFIGURATION

The non-standard options recognised by DragDrop are as follows:-

-event

The event which will initiate dragging.

-sitetypes

Whether the applications served by this source will be local ('local'), global ('Sun') or both (undef).

-handlers

Handler routines for each supported type of data to be transferred

-image

Optionally a (bitmap) image to display instead of text when an item is being dragged.

-startcommand

Optionally a callback invoked before dragging is initiated. Subroutine (which is called without any parameters) must return 0 if Drag is to be allowed, otherwise the event will be ignored. Defaults to undef.

-predropcommand

Optionally a callback invoked before dropping occurs. Subroutine (which will be called with the source application ID string and the dropsite widget as parameters) must return 0 if Drop is allowed, otherwise no handler is called. Defaults to undef.

-postdropcommand

Optionally a callback invoked after dropping occurs. Subroutine will be called with the source application ID string and need not return any specific value. Defaults to undef.

-cursor

Optionally the cursor to use whilst dragging. Defaults to 'hand2'

-text

Optionally some fixed text to display in the drag window. Defaults to the classname of the parent widget.

The non-standard options recognised by DropSite are as follows:-

-droptypes

Whether items will be dropped from local ('local'), global ('Sun') or both (undef) applications

-dropcommand

Callback subroutine to invoke when something is dropped here

-entercommand

Optionally, callback routine to invoke whenever dragged object enters or leaves the DropSite. Defaults to undef.

METHODS

DragDrop supports the following methods:-

DropSite supports the following methods:-

-delete

Remove this object from the list of registered DropSites

DEFAULT BINDINGS

When the window representing the dragged object is mapped, the Mapped method is called (class binding).

Any button motion invokes the Drag method (class binding).

Any button release invokes the Drop method (class binding).

Any keypress whilst dragging invokes the Done method, aborting the drag (class binding).

Button 1 invokes the StartDrag method (instance binding).

BUGS

There is currently no way a DragDrop source can remove an event binding once it has been installed (however this can be done manually by removing the binding from the parent widget).

Destroying a DragDrop source doesn't remove the binding from the parent widget, causing Tk to complain if the bound callback is later invoked.

DropSites can't be within a scrolling Table (this is a Table bug, not a DragDrop one).

AUTHORS

Nick Ing-Simmons nik@tiuk.ti.com : Original module code

John Attwood ja1@sanger.ac.uk : This demo and draft pod docs