DropSite

NAME: DropSite - Commands for Drop facilities
DESCRIPTION
COMMAND: DropSite::register path ?option value...?; DropSite::setcursor cursor; DropSite::setoperation op; DropSite::Dropper ?create? instance ?option value ...?; instance attach path subpath; instance cget option; instance configure ?option ?value ?option value ...???
LEGACY COMMAND: DropSite::include class types; DropSite::setdrop path subpath dropover drop ?force?

NAME

DropSite - Commands for Drop facilities

DESCRIPTION

Commands of this namespace enable the user to define a Tk or Slab widget as a drop site, i.e. as a widget onto which something (e.g. text, an image, or a color), having been "dragged" by the pointer from another widget of the same application, can be "dropped" by releasing the pointer button.

A drop site specifies the type(s) of object that can be dropped, the associated operation (move, copy or link), a command called when an object is dragged over the widget, and a command called when the drop occurs. A drop site must have at least one type of acceptable object and a drop command.

Some Slab widgets (ComboBox, Entry, Label, LabelEntry, ListBox, SpinBox, and Tree) have DropSite built in, and it is used via the widget options -dropcmd, -dropenabled, -dropovercmd, and -droptypes. The widgets that have been ported to Snit and have built-in DropSite delegate to a Snit Abstract Type Slab::DropSite::Dropper, and access DropSite both via this object, and via DropSite::setcursor and DropSite::setoperation. (The Tree widget has built-in DropSite, has not been ported to Snit, and accesses DropSite via the commands DropSite::include, DropSite::setdrop, and DropSite::setcursor.)

Here is the use of DropSite in the Entry widget:

snit::widgetadaptor Slab::Entry {

    # Delegate drop-related options and methods.
    component MyDropper
    delegate option -dropcmd      to MyDropper
    delegate option -dropenabled  to MyDropper
    delegate option -dropovercmd  to MyDropper
    delegate option -droptypes    to MyDropper
    delegate method  dropsite_for_snit to MyDropper

    constructor {args} {
        installhull using entry

        # Define and configure component MyDropper.
        install MyDropper using Slab::DropSite::Dropper ${selfns}::keepDropOpts \  
                -dropovercmd [mymethod _over_cmd] \
                -dropcmd     [mymethod _drop_cmd] \
                -droptypes   {
                                  TEXT    {move {}}
                                  FGCOLOR {move {}}
                                  BGCOLOR {move {}}
                                  COLOR   {move {}}
                             }
        $MyDropper attach $win $win

        $self configurelist $args

        # The rest of the constructor ...
        ...
    }
}

Any other Tk or Slab widget can be defined as a drop site by calling the command DropSite::register. The script must also define the commands whose names are passed as arguments to register, according to the specifications given below.

COMMAND

DropSite::register path ?option value...?

This command is used to declare path as a drop site. Options are:

-dropcmd

This command is called when user release the drag icon over a valid drop target widget. Arguments passed to the command are:

pathname of the drop target (the widget itself),
pathname of the drag source,
root x-coordinate of the pointer,
root y-coordinate of the pointer,
operation,
type of the dragged data,
dragged data.

Its return values is passed as a result to the -dragendcmd command of the drag source widget.

-dropovercmd

This command can be used to provide a dynamic drag during drag-over events. While a drag occurs, events <Enter>, <Motion> and <Leave> are intercepted. Arguments passed to the command are:

pathname of the drop target (the widget itself),
pathname of the drag source,
event over the drop target: enter, motion or leave,
root x-coordinate of the pointer,
root y-coordinate of the pointer,
operation,
type of the dragged data,
dragged data.

Command must the new status of the drag:

0 if widget refuse this drag. Command will not be recalled on motion/leave event.
1 if widget accept this drag. Command will not be recalled on motion/leave event.
2 if widget refuse this drag. Command will be recalled on each motion event to reevaluate.
3 if widget accept this drag. Command will be recalled on each motion event to reevaluate.

Here is a list of events and associated actions on a DropSite widget. This example assumes that dragged data type is valid for the drop target. status is the status of the drag on a DropSite. Its value is:

Event	Old status	Action	New status
<Enter>	-	if DropSite has -dropovercmd, call it with enter	result of -dropovercmd
<Enter>	-	else	1
<Motion>	0 or 1		unchanged
<Motion>	2 or 3	call -dropovercmd with motion	result of -dropovercmd
<Leave>	0 or 1		-
<Leave>	2 or 3	call -dropovercmd with leave	-
<Drop>	0	call -dragendcmd of drag source	-
	1	call -dropcmd and call -dragendcmd of drag source
	2	call -dropovercmd with leave and call -dragendcmd of drag source
	3	call -dropcmd and call -dragendcmd of drag source

-droptypes

Specifies a list {type oplist ?type oplist? ...} of acceptable types and associated operations for the drop target. For each type, oplist is a list {descops mod ?descops mod? ...} describing operations and modifier keys for these operations. descops describe an operation. It can be a predefined operations (copy, move or link) or a new user defined operation, of the form {subop baseop ?bitmap?}. subop is the name given to the sub operation, baseop is the name of the base operation (copy, move or link) and bitmap is a bitmap to display for the operation.
If bitmap is empty, the default bitmap of the base operation is used for the sub operation.
subop can be a base operation, in order to change the bitmap of a base operation. In this case, baseop must be empty or equal to subop.
mod is the modifer key for the operation. It can be:

none to specify that no modifier key is pressed. This modifier can only be used with a sub operation named default (and vice versa), which has the behaviour of not display any bitmap operation. For all type, if the modifier none is not given, it is automatically associated to the default sub operation of a copy base operation.
program to specifies a sub operation accessible only by DropSite::setoperation.
A list combining shift, control and alt, which means their corresponding key.

DropSite::setcursor cursor

This command can be used within the script -dragovercmd. It is useful to provide visual effect about the state of the drag.

DropSite::setoperation op

Description text

DropSite::Dropper ?create? instance ?option value ...?

Constructor for a DropSite::Dropper object.

-dropcmd

See DropSite::register, option -dropcmd

-dropovercmd

See DropSite::register, option -dropovercmd

-dropenabled

Specifies whether or not drop is active

-droptypes

See DropSite::register, option -droptypes

instance attach path subpath

Attach the DropSite provided by instance to the widget path (of which this instance is typically a component), and specifically to its subwidget with Tk window path subpath.

instance cget option

Command to return the value of one of the options -dropcmd, -dropovercmd, -dropenabled, -droptypes.

instance configure ?option ?value ?option value ...???

Command to configure the instance via its options -dropcmd, -dropovercmd, -dropenabled, -droptypes.

LEGACY COMMAND

DropSite::include class types

Used only by Slab widgets that have not been ported to Snit, and therefore use the BWidget base class "Widget". This command provides a simple way to include options related to a drop site into a BWidget resources definition. It includes the options needed for register, -dropovercmd and -dropcmd, initialized to empty string, and -droptypes, initialized to types, and one new option:

-dropenabled: See command DropSite::Dropper, option -dropenabled. This specifies whether or not the drop is active, and is initialized to 0.

DropSite::setdrop path subpath dropover drop ?force?

Used only by Slab widgets that have not been ported to Snit, and therefore use the BWidget base class "Widget". This command provides a simple way to call register during a BWidget creation or configuration.

path is the pathname of the widget,
subpath is the pathname of the tk widget where drag event occurs,
dropover is a command for drag-over event,
drop is a command for drop event,
force specifies whether or not to call register whenever no option value has changed (0 by default - for widget configuration, use 1 for widget creation).

setdrop verifies the modification flag of options -dropenabled and -droptypes and calls register if needed according to the options values and dropover and drop arguments. -dropovercmd and -dropcmd are obtained from command arguments.