NAME

       drag&drop  - facilities for handling drag&drop data trans­
       fers


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  facili­
       ties  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  regis­
       tered  as a drag&drop target.  Note that a particular wid­
       get 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 tar­
       get 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 pro­
       cess 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

       plest 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 par­
       ticular 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 inter­
       act 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  follow­
                     ing 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


                     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 repre­
              sents 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 wid­
              get, 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  com­
              mand  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


                     Specifies the color used to draw  the  back­
                     ground  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  fore­
                     ground  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  com­
                     patible target, then the source will be able
                     to transmit to itself during drag&drop oper­
                     ations.   This  is primarily useful for com­
                     plex 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 win­
                     dow 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 recog­
                     nized by the  target.   The  first  matching
                     dataType  found  determines  the  value that

                     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 con­
                     sidered  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  speci­
                     fied,  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 win­
                             dow 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

              Switch:   -tokenbg color

                     Specifies  the  color used to draw the back­
                     ground 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  accept­
                     able  to Tk_GetPixels.  The default value is
                     "3".

              Name:     tokenCursor
              Class:    Cursor
              Switch:   -tokencursor cursor

                     Specifies the cursor used when a token  win­
                     dow  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 regis­
              tered for the source window.  If only the  dataType
              is  specified, then the dataType is created if nec­
              essary,  and  the  command  associated   with   the
              dataType  is  returned.  Otherwise, it concatenates
              the command and any extra arg strings,  and  regis­
              ters 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" com­
       mands which transfer data to the remote application.   The
       target window is then asked to handle the new data.  What­
       ever value is returned by the source  command  handler  is

       get 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 differ­
       ently.  If an error is encountered during  the  communica­
       tion  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 han­
              dlers registered for the target window, and invokes
              the appropriate command.  If a value is  specified,
              it  is substituted into any "%v" fields in the han­
              dler command associated with the dataType.  If  the
              dataType  name  is  not  recognized,  this  command
              returns  an  error.   This   command   is   invoked

              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 estab­
              lished, its token window must be filled  with  wid­
              gets 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 <Button­
              Press-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  rejec­
              tion  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 <Button­
              Release-n> event for "-button n" of the source wid­
              get.

       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  other­
              wise).

              Specifies  a Tcl proc used to handle errors encoun­
              tered 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


Man(1) output converted with man2html