Provided by: blt-dev_2.4z-7ubuntu2_amd64 bug

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