NAME

DragSite - Commands for Drag facilities

COMMAND

DragSite::register path ?option value...?

DragSite::Dragger ?create? instance ?option value ...?

instance attach path subpath

instance cget option

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

LEGACY COMMAND

DragSite::include class type event

DragSite::setdrag path subpath initcmd endcmd ?force?

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

Some Slab widgets (ComboBox, Entry, Label, LabelEntry, ListBox, SpinBox, and Tree) have DragSite built in, and it is used via the widget options -dragenabled, -dragendcmd, -dragevent, -draginitcmd, and -dragtype. The widgets that have been ported to Snit and have built-in DragSite delegate to a Snit Abstract Type Slab::DragSite::Dragger, and access DragSite exclusively via this object. (The Tree widget has built-in DragSite, has not been ported to Snit, and accesses DragSite via the commands DragSite::include and DragSite::setdrag.)

Here is the use of DragSite in the Entry widget:

snit::widgetadaptor Slab::Entry {

    # Delegate drag-related options and methods.
    component MyDragger
    delegate option -dragenabled  to MyDragger
    delegate option -dragendcmd   to MyDragger
    delegate option -dragevent    to MyDragger
    delegate option -draginitcmd  to MyDragger
    delegate option -dragtype     to MyDragger
    delegate method  dragsite_for_snit to MyDragger

    constructor {args} {
        installhull using entry

        # Define and configure component MyDragger.
        install MyDragger using Slab::DragSite::Dragger ${selfns}::keepDragOpts \
                -draginitcmd [mymethod _init_drag_cmd] \
                -dragtype    {} \
                -dragevent   3
        $MyDragger attach $win $win

        $self configurelist $args

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

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

DragSite::register path ?option value...?

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

-dragendcmd

Command called when drag terminates (ie when user release drag icon). This command is called with the following arguments:

• the pathname of the drag source (the widget itself),
• the pathname of the drop target,
• the operation,
• the type of the dragged data,
• the dragged data,
• result of the drop (result of the call to -dropcmd of the target),

If the drop does not occur, the target and the operation are empty string and the result is 0.

-dragevent

Specifies the number of the mouse button associated to the drag. Must be 1, 2 or 3.

-draginitcmd

Command called when drag initiates. When the event of option dragevent occurs on path, this command is called with the following arguments:

• pathname of the drag source (path),
• root x-coordinate of pointer,
• root y-coordinate of pointer,
• a toplevel created to represent dragged data. When returning, if it has no children, a bitmap is automatically displayed.

If the command returns an empty string, then the drag will be suppressed. Otherwise the command must return a list containing three elements:

• the type of the data,
• the list of acceptable basic operations (copy, move and link)
• and the data.

Note that even if copy does not appear in the list of basic operation, it is considered as an acceptable operation, since copy semantic does not modify the drag source.

DragSite::Dragger ?create? instance ?option value ...?

Constructor for a DragSite::Dragger object.

-draginitcmd

See DragSite::register, option -draginitcmd

-dragendcmd

See DragSite::register, option -dragendcmd

-dragevent

See DragSite::register, option -dragevent

-dragenabled

Specifies whether or not drag is active

-dragtype

Default or alternate dragged data type

instance attach path subpath

Attach the DragSite 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 -dragenabled, -draginitcmd, -dragendcmd, -dragtype, -dragevent.

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

Command to configure the instance via its options -dragenabled, -draginitcmd, -dragendcmd, -dragtype, -dragevent.

DragSite::include class type event

Used only by Slab widgets that have not been ported to Snit, and therefore use the BWidget base class "Widget". The command gives all widgets of a particular BWidget class the options -dragenabled, -draginitcmd, -dragendcmd, -dragtype, -dragevent, by which a DragSite can be requested without calling DragSite::register. Option -dragevent is initialized to event, -dragtype is initialized to type, -draginitcmd and -dragendcmd are initialized to the empty string, and option -dragenabled is initialized to 0.

-dragenabled

See DragSite::Dragger, option -dragenabled

-dragtype

See DragSite::Dragger, option -dragtype

DragSite::setdrag path subpath initcmd endcmd ?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 widget creation or configuration.

• path is the pathname of the BWidget,
• subpath is the pathname of the tk widget where drag event occurs,
• initcmd command for drag-init event,
• endcmd command for drag-end event,
• force (boolean) specifies whether or not to call register whenever no option value has changed (0 by default - for widget configuration, use 1 for widget creation).

setdrag verifies the modification flag of options dragenabled and dragevent and calls register if needed according to the options values and initcmd and endcmd arguments. draginitcmd and dragendcmd are obtained from command arguments.