dragdrop

drag&drop(BLT 2.4)                                          drag&drop(BLT 2.4)



______________________________________________________________________________

NAME
       drag&drop - facilities for handling drag&drop data transfers

SYNOPSIS
       drag&drop source
       drag&drop source window ?options?
       drag&drop source window handler ?dataType? ?command arg arg...?

       drag&drop target
       drag&drop target window handler ?dataType command arg arg...?

       drag&drop target window handle dataType ?value?

       drag&drop token window

       drag&drop drag window x y
       drag&drop drop window x y
       drag&drop active
       drag&drop errors ?proc?
       drag&drop location ?x y?
______________________________________________________________________________


DESCRIPTION
       The drag&drop command provides access to a set of facilities for
       managing drag-and-drop data transfers.  Any of the usual Tk widgets can
       be registered to participate in the drag-and-drop process.  Widgets
       registered as a drag&drop source can export data to other widgets
       registered as a drag&drop target.  Note that a particular widget can be
       registered as a source, as a target, or as both.

       The drag-and-drop process begins when the user clicks and holds a mouse
       button in a source window; a token window appears with an icon or
       message to represent the data being transferred.  As the user moves the
       mouse pointer, the token window follows along, acting as a movable
       packet of data.  Whenever the mouse pointer falls on a valid target
       window, the border of the token window is changed to a raised (active)
       state.  When the mouse button is released over the target window, a Tcl
       routine is invoked to send the data to the desired application, and the
       target window is asked to "handle" the data.  If this communication
       process fails, a rejection symbol (a circle with a line through it) is
       displayed on the token window to indicate failure.

       The details of the communication process are fully configurable by the
       application developer.  In the simplest case, the value that is sent to
       the target window is a simple string.  The target window is simply
       asked to "handle" that string value.  In general, the source window can
       have a special "handler" procedure to transfer a particular data type
       by issuing a series of "send" commands.  After this, the target window
       is again asked to "handle" the result.

       Both sources and targets can have a list of "handlers" for different
       data types.  As a token window is dragged from its source to various
       targets, each target is checked to see if it recognizes a handler
       offered by the source.  If it does, it is treated as a valid target.
       Otherwise, it is ignored.  This scheme allows the same source to
       interact with many different kinds of targets.  For example, a source
       for RGB color samples might have "color" and "string" handlers.  This
       would allow it to communicate with "color" targets (sending RGB data)
       as well as entry widgets (sending strings of the form "#rrggbb").

       This introduction was presented as a brief overview of the
       communication process; further details are presented below:

       drag&drop source
              Returns a list of path names for widgets registered as drag&drop
              sources.  Returns an empty string if no widgets have been
              registered.

       drag&drop source window ?options?
              Registers a new drag&drop source window with the given options,
              or modifies the options for an existing window:

              Name:     buttonBinding
              Class:    ButtonBinding
              Switch:   -button n

                     Specifies the mouse button (integer 1-5) that will invoke
                     the drag&drop operation on the source window.  This
                     causes the following bindings to be added to the widget:

                     bind win <ButtonPress-n> {drag&drop drag %W %X %Y}
                     bind win <Bn-Motion> {drag&drop drag %W %X %Y}
                     bind win <ButtonRelease-n> {drag&drop drop %W %X %Y}

              The default value is button 3.  If the value "0" is specified,
              then no bindings are added; this enables the user to establish
              bindings manually.

              Name:     packageCommand
              Class:    Command
              Switch:   -packagecmd command

                     Specifies a Tcl command used to establish the appearance
                     of the token window at the start of each drag&drop
                     operation.  This command is automatically invoked by the
                     drag&drop drag command whenever the token window is about
                     to be mapped for a drag operation.  It should update the
                     appearance of the token window to represent the data that
                     is being moved.

              The following substitutions are made in the command string
              before it is executed:

                     %t     Replaced with the window path name for the token
                            which represents the data being dragged.

                     %W     Replaced with the window path name for the
                            drag&drop source.

              The return value from the package command represents the data
              being transferred.  If the package command returns an empty
              string, the drag operation is quietly aborted.  This can be used
              to disallow drag&drop operations from certain parts of a widget,
              if the drag position is inappropriate.

              For example, the following package routine will select an item
              from a listbox and configure the token window to display the
              selected string.  It uses the drag&drop location command to
              determine the entry in the listbox that the user has selected
              and it returns this as the data value:

                     proc package_list_item {lbox token} {
                         set xy [drag&drop location]
                         set y  [expr [lindex $xy 1]-[winfo rooty $lbox]]

                         set str [$lbox get [$lbox nearest $y]]
                         $token.value configure -text $str
                         return $str
                     }

              The return value is available later when the source and target
              communicate.  If the source has a command associated with its
              data handler, then this value is substituted in place of "%v" in
              the source handler.  Otherwise, it is substituted in place of
              "%v" in the target handler.

              Name:     rejectBackground
              Class:    Background
              Switch:   -rejectbg color

                     Specifies the color used to draw the background of the
                     rejection symbol on the token window.  The rejection
                     symbol (a circle with a line through it--the
                     international "no") appears whenever communication fails.

              Name:     rejectForeground
              Class:    Foreground
              Switch:   -rejectfg color

                     Specifies the color used to draw the foreground of the
                     rejection symbol on the token window.

              Name:     rejectStipple
              Class:    Stipple
              Switch:   -rejectstipple pattern

                     Specifies a stipple pattern used to draw the foreground
                     of the rejection symbol on the token window.  Any of the
                     forms acceptable to Tk_GetBitmap can be used.

              Name:     selfTarget
              Class:    SelfTarget
              Switch:   -selftarget boolean

                     If the boolean value is true, and if a source widget is
                     also registered as a compatible target, then the source
                     will be able to transmit to itself during drag&drop
                     operations.  This is primarily useful for complex sources
                     such as a canvas widget, where items may be moved from
                     place to place within the same widget.  By default, this
                     option is disabled.

              Name:     send
              Class:    Send
              Switch:   -send list

                     Specifies a list of dataTypes enabled for communication.
                     Only dataTypes defined by commands of the form "drag&drop
                     source window handler ?dataType ?command arg arg...?" are
                     allowed.  This list also determines the priority of the
                     various dataTypes.  When a token window is over a
                     potential drag&drop target, this list is searched from
                     start to finish for a dataType that is also recognized by
                     the target.  The first matching dataType found determines
                     the value that will be sent if the token is dropped.  If
                     no matching dataType is found, then the target is
                     incompatible, and is ignored.  By default, this option
                     has the value "all", indicating that all dataTypes should
                     be considered in the order that they were defined for the
                     source.

              Note that this option makes it easy to control a drag&drop
              source.  Setting the value to an empty string disables the
              source; setting the value back to "all" restores communication.

              Name:     siteCommand
              Class:    Command
              Switch:   -sitecmd command

                     Specifies a Tcl command used to update the appearance of
                     the token window.  If specified, this command is
                     automatically invoked by the drag&drop drag command
                     whenever the token window is over a compatible drag&drop
                     target.

              The following substitutions are made in the command string
              before it is executed:

                     %s     Replaced with "1" if the token window is over a
                            compatible target, and "0" otherwise.

                     %t     Replaced with the window path name for the token
                            which represents the data being dragged.

              Regardless of this command, border of the token window will
              become raised whenever the token is over a valid target.  This
              command can be used to display other visual cues.

              Name:     tokenAnchor
              Class:    Anchor
              Switch:   -tokenanchor anchor

                     Specifies how the token window is positioned relative to
                     the mouse pointer coordinates passed to the drag&drop
                     drag command.  Must be one of the values n, s, e, w,
                     center, nw, ne, sw or se.  For example, "nw" means to
                     position the token such that its upper-left corner is at
                     the mouse pointer.  The default value is "center".

              Name:     tokenBackground
              Class:    Background
              Switch:   -tokenbg color

                     Specifies the color used to draw the background of the
                     token window.

              Name:     tokenBorderWidth
              Class:    BorderWidth
              Switch:   -tokenborderwidth size

                     Specifies the width in pixels of the border around the
                     token window.  This border becomes raised to indicate
                     when the token is over a compatible drag&drop target
                     site.  The value may have any of the forms acceptable to
                     Tk_GetPixels.  The default value is "3".

              Name:     tokenCursor
              Class:    Cursor
              Switch:   -tokencursor cursor

                     Specifies the cursor used when a token window is active.
                     The value may have any of the forms acceptable to
                     Tk_GetCursor.  The default value is "center_ptr".

       drag&drop source window handler ?dataType? ?command arg arg...?
              With no extra arguments, this command returns a list of all
              dataType names that have been registered for the source window.
              If only the dataType is specified, then the dataType is created
              if necessary, and the command associated with the dataType is
              returned.  Otherwise, it concatenates the command and any extra
              arg strings, and registers a new dataType with this command.

       The following substitutions are made in the command string before it is
       executed:

              %i     Replaced with the name of the interpreter for the target
                     application.

              %v     Replaced with the value returned from the "-packagecmd"
                     command.

              %w     Replaced with the window path name for the target window.

       A typical source handler contains one or more "send" commands which
       transfer data to the remote application.  The target window is then
       asked to handle the new data.  Whatever value is returned by the source
       command handler is automatically substituted into the "%v" fields of
       the target handler.

       This separation between the transfer and the handling of the data is
       important.  It allows the same source handler to transfer data for many
       different targets, and it allows each of the targets to handle the
       incoming data differently.  If an error is encountered during the
       communication process, the rejection symbol is posted on the token
       window to indicate failure.


       drag&drop target
              Returns a list of path names for widgets registered as drag&drop
              targets.  Returns an empty string if no widgets have been
              registered.

       drag&drop target window handler ?dataType command arg arg...?
              Registers a new drag&drop target window with a given handler, or
              modifies the handlers for an existing window.  If no dataType is
              specified, this command returns the current list of recognized
              dataType strings.  Each dataType is a symbolic name representing
              a form of data, and the corresponding command is a Tcl command
              that specifies how the target will make use of the data.  This
              command is invoked indirectly after a source has transferred
              data to a target application.

       The following substitutions are made in the command string before it is
       executed:

              %v     In the simplest case, the source window does not have a
                     handler command for the selected dataType, and this field
                     is replaced with the result from the "-packagecmd"
                     command.  When the source does have a handler command,
                     the result from the "-packagecmd" command is substituted
                     into its "%v" field, and the result from this command is
                     substituted into this field in the target command.

              %W     Replaced with the window path name for the target window.

       drag&drop target window handle dataType ?value?
              Searches for the given dataType name among the handlers
              registered for the target window, and invokes the appropriate
              command.  If a value is specified, it is substituted into any
              "%v" fields in the handler command associated with the dataType.
              If the dataType name is not recognized, this command returns an
              error.  This command is invoked automatically by the drag&drop
              facility when data is being transferred from a source to a
              target.

       drag&drop token window
              Returns the token window associated with a drag&drop source
              window.  The token window is used to represent data as it is
              being dragged from the source to a target.  When a source is
              first established, its token window must be filled with widgets
              to display the source data.  For example,

              drag&drop source .foo

              set win [drag&drop token .foo]
              label $win.label -text "Data"
              pack $win.label


       drag&drop drag window x y
              Marks the start of (or movement during) a drag&drop operation.
              If the token window is unmapped when this command is invoked,
              then the -packagecmd for the source window is executed.  If this
              command is successful and returns a non-null string, the token
              window is mapped.  On subsequent calls, the token window is
              moved to the new x y location.  Unless the "-button 0" option is
              specified for the source, this command is automatically bound to
              <ButtonPress-n> and <Bn-Motion> events for "-button n" of the
              source widget.

       drag&drop drop window x y
              Marks the end of a drag&drop operation.  If the mouse pointer is
              over a compatible target window, then the appropriate send
              handler for the first compatible dataType is invoked to handle
              the data transfer.  If the data transfer is successful, then the
              token window is unmapped; otherwise, a rejection symbol is drawn
              on the token window, and the window is unmapped after a small
              delay.  Unless the "-button 0" option is specified for the
              source, this command is automatically bound to the
              <ButtonRelease-n> event for "-button n" of the source widget.

       drag&drop active
              Returns "1" if a drag&drop operation is in progress, and "0"
              otherwise.  A drag&drop operation officially starts after the
              package command has been executed successfully, and ends after
              the send handler has been executed (successfully or otherwise).

       drag&drop errors ?proc?
              Specifies a Tcl proc used to handle errors encountered during
              drag&drop operations.  If a proc is not specified, this command
              returns the current error handler.  By default, all errors are
              sent to the usual tkerror command, and therefore appear in a
              dialog box to the user.  This behavior is quite useful when
              debugging communication protocols, but may not be desirable in a
              finished application.  Errors can be suppressed entirely
              (leaving the rejection symbol as the only error indicator) by
              specifying a null string in place of the proc name.

       drag&drop location ?x y?
              Used to set or query the pointer location during a drag&drop
              operation.  The x y arguments specify the current location; if
              these arguments are missing, then the last reported (x,y)
              location is returned as a list with two elements.  This command
              is issued automatically within the drag&drop drag and drag&drop
              drop commands, to keep track of pointer movement.


KEYWORDS
       drag&drop, send, bind, widget



                                                            drag&drop(BLT 2.4)