Scroll to navigation

canvas::drag(3tk) Variations on a canvas canvas::drag(3tk) 





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.



  

  
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










BUGS, IDEAS, FEEDBACK


This document, and the package it describes, will undoubtedly
    contain bugs and other problems. Please report such in the category
    canvas of the Tklib Trackers
    [http://core.tcl.tk/tklib/reportlist]. Please also report any ideas for
    enhancements you may have for either package and/or documentation.






KEYWORDS


canvas, dragging







  

    0.1
    tklib