1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
[comment {-*- tcl -*- doctools manpage}]
[vset VERSION 0.1]
[manpage_begin canvas::drag n [vset VERSION]]
[moddesc {Variations on a canvas}]
[titledesc {Manage the dragging of canvas items or item groups}]
[require Tcl 8.5]
[require Tk 8.5]
[require canvas::drag [opt [vset VERSION]]]
[keywords canvas dragging]
[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.
[section API]
[list_begin definitions]
[comment {= = == === ===== ======== ============= =====================}]
[call [cmd ::canvas::drag] [method on] [arg canvas] [arg tagOrId] [arg cmd] [arg option]...]
This command initializes item dragging on the [arg canvas] widget,
with the items used as drag handles identified by [arg tagOrId].
The command prefix [arg cmd], invoked for drag start and movement, is
responsible for the initialization and actual execution of the drag
operation.
[para] The signature of the command prefix is described later, in
section [sectref {Drag callback}].
[para] Similarly, the accepted options and their values are described
in section [sectref Options]
[para] The result of the command is the empty string.
[comment {= = == === ===== ======== ============= =====================}]
[call [cmd ::canvas::drag] [method off] [arg canvas] [arg tagOrId]]
This command removes any drag operation set on the items of canvas
[arg canvas] identified by [arg tagOrId].
[para] The result of the command is the empty string.
[comment {= = == === ===== ======== ============= =====================}]
[call [cmd ::canvas::drag] [method item] [arg canvas] [arg tagOrId] [arg option]...]
This is a convenience command wrapped around method [method on] (see above)
to drag single items of the [arg canvas] widget, identified by [arg tagOrId].
[para] It uses an internal standard callback for this.
[para] The result of the command is the empty string.
[comment {= = == === ===== ======== ============= =====================}]
[call [cmd ::canvas::drag] [method group] [arg canvas] [arg tagOrId] [arg cmd] [arg option]...]
This is a convenience command wrapped around method [method on] (see above)
to drag single items of the [arg canvas] widget, identified by [arg tagOrId].
[para] It uses an internal standard callback for this. The callback
[arg cmd] specified has the same signature as the [sectref {Drag callback}],
except that
[list_begin enumerated]
[enum] The [method move] method is not invoked.
[enum] The result of the [method start] method [emph {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).
[list_end]
[para] The result of the command is the empty string.
[list_end]
[subsection {Drag callback}]
The drag callback is a command prefix invoked in the following two
ways:
[list_begin definitions]
[comment {= = == === ===== ======== ============= =====================}]
[call [cmd "{*}cmd"] [method start] [arg canvas] [arg item]]
This form is invoked when has initiated dragging using drag handle
identified by the canvas [arg item] id.
The callback now has to perform anything necessary for its type of
drag operation.
[para] 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.
[comment {= = == === ===== ======== ============= =====================}]
[call [cmd "{*}cmd"] [method move] [arg canvas] [arg clientdata] [arg dx] [arg 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.
[para] 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.
[comment {= = == === ===== ======== ============= =====================}]
[call [cmd "{*}cmd"] [method done] [arg canvas] [arg 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).
[para] The result of the command is ignored.
[list_end]
[subsection Options]
The commands to create drag operations ([method on], [method item],
and [method group]) all accept the following options to configure the
new drag.
[list_begin options]
[opt_def -event [arg 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:
[para] To initiate a drag operation by pressing mouse button 3 on a
drag handle, use:
[example { -event 3 }]
This is the default as well, if the option is not specified.
[para] To initiate a drag operation by pressing mouse button 2 on a
drag handle while holding down the Control key, use:
[example { -event Control-2 }]
[list_end]
[manpage_end]
|
