NAME

       canvas::drag - Manage the dragging of canvas items or item groups

SYNOPSIS

       package require Tcl  8.5

       package require Tk  8.5

       package require canvas::drag  ?0.1?

       ::canvas::drag on canvas tagOrId cmd option...

       ::canvas::drag off canvas tagOrId

       ::canvas::drag item canvas tagOrId option...

       ::canvas::drag group canvas tagOrId cmd option...

       {*}cmd start canvas item

       {*}cmd move canvas clientdata dx dy

       {*}cmd done canvas clientdata

_________________________________________________________________

DESCRIPTION

       This  package  provides  utility  commands  to  setup and rmeove dragging of items or item
       groups on a canvas, hiding all complexity regarding bindings from the user.

API

       ::canvas::drag on canvas tagOrId cmd option...
              This command initializes item dragging on the canvas widget, with the items used as
              drag handles identified by tagOrId.  The command prefix cmd, invoked for drag start
              and movement, is responsible for the initialization and  actual  execution  of  the
              drag operation.

              The signature of the command prefix is described later, in section Drag callback.

              Similarly, the accepted options and their values are described in section Options

              The result of the command is the empty string.

       ::canvas::drag off canvas tagOrId
              This  command  removes  any  drag  operation  set  on  the  items  of canvas canvas
              identified by tagOrId.

              The result of the command is the empty string.

       ::canvas::drag item canvas tagOrId option...
              This is a convenience command wrapped around method on (see above) to  drag  single
              items of the canvas widget, identified by tagOrId.

              It uses an internal standard callback for this.

              The result of the command is the empty string.

       ::canvas::drag group canvas tagOrId cmd option...
              This  is  a convenience command wrapped around method on (see above) to drag single
              items of the canvas widget, identified by tagOrId.

              It uses an internal standard callback for this. The callback cmd specified has  the
              same signature as the Drag callback, except that

              [1]    The move method is not invoked.

              [2]    The  result of the start method has to be a canvas tag refering to the whole
                     group of items to move. In other words, it must  convert  from  drag  handle
                     (item id) to dragged groupt (tag).

       The result of the command is the empty string.

   DRAG CALLBACK
       The drag callback is a command prefix invoked in the following two ways:

       {*}cmd start canvas item
              This  form  is  invoked when has initiated dragging using drag handle identified by
              the canvas item id.  The callback now has to perform  anything  necessary  for  its
              type of drag operation.

              The  result  of  the  command can be anything. It is stored by the system as client
              information and passed unchanged to the movement callback  for  its  use.  In  this
              manner the drag callback is able to maintain custom state from start to movement.

       {*}cmd move canvas clientdata dx dy
              This  form  is invoked when the mouse moved during a drag operation.  It is invoked
              with the client data from the start callback (or the previous  move  callback)  and
              the distances the mouse has traveled in horizontal and vertical directions.

              The  result  of  the  command can be anything. It is stored by the system as client
              information and passed unchanged to the next movement callback for its use. In this
              manner  the  drag  callback  is  able  to  maintain  custom  state from movement to
              movement.

       {*}cmd done canvas clientdata
              This form is invoked when the drag operation ends.  It is invoked with  the  client
              data  from  the  last  movement  callback  (or  start callback if there had been no
              motion).

              The result of the command is ignored.

   OPTIONS
       The commands to create drag operations (on, item, and  group)  all  accept  the  following
       options to configure the new drag.

       -event spec
              The  value  of  this  option  specifies  the mouse button used to initiate the drag
              operation, and the keyboard modifier, if any. Examples of specifications:

              To initiate a drag operation by pressing mouse button 3 on a drag handle, use:

               -event 3

              This is the default as well, if the option is not specified.

              To initiate a drag operation by pressing mouse button 2  on  a  drag  handle  while
              holding down the Control key, use:

               -event Control-2

KEYWORDS

       canvas, dragging