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
|
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin canvas::sqmap n 0.2]
[moddesc {Variations on a canvas}]
[titledesc {Canvas with map background based on square tiles}]
[require Tcl 8.4]
[require Tk 8.4]
[require canvas::sqmap [opt 0.2]]
[description]
This package provides an extended canvas widget for the display of
maps based on a set of square image tiles. The tiles are the
background of the canvas, with all other canvas items added always
shown in front of them. The number of tiles shown, tile size, and
where to get the images to show are all configurable.
[section API]
[list_begin definitions]
[call [cmd ::canvas::sqmap] [arg pathName] [opt options]]
Creates the canvas [arg pathName] and configures it. The new widget
supports all of the options and methods of a regular canvas, plus the
options and methods described below.
[nl]
The result of the command is [arg pathName].
[list_end]
[subsection Options]
[list_begin options]
[opt_def -grid-cell-width]
The value for this option is a non-negative integer. It specifies the
width of the cells the background is made up of.
[opt_def -grid-cell-height]
The value for this option is a non-negative integer. It specifies the
height of the cells the background is made up of.
[opt_def -grid-cell-command]
The value for this option is a command prefix. It is nvoked whenever
the canvas needs the image for a specific cell of the background, with
two additional arguments, the id of the cell, and a command prefix to
invoke when the image is ready, or known to not exist.
[nl]
The id of the cell is a 2-element list containing the row and column
number of the cell, in this order. The result command prefix (named
"$result" in the example below) has to be invoked with either two or
three arguments, i.e.
[example {
$result set $cellid $image ; # image is known and ready
$result unset $cellid ; # image does not exist
}]
This option may be left undefined, i.e. the canvas can operate without
it. In that case the only images shown in grid cells are those
explicitly set with the method [method {image set}], see the next
section. All other grid cells will simply be empty.
[opt_def -viewport-command]
This option specifies a command prefix to invoke when the viewport of
the canvas is changed, to allow users keep track of where in the
scroll-region we are at all times. This can be used, for example, to
drive derivate displays, or to keep items in view by moving them as
the viewport moves.
[list_end]
[subsection Methods]
[list_begin definitions]
[call [arg canvasName] [method {image set}] [arg cell] [arg image]]
Invoking this method places the [arg image] into the specified
[arg cell] of the background. The cell is given as a 2-element list
containing row and column number, in this order.
[nl]
Note that an image is allowed to be associated with and displayed in
multiple cells of the canvas.
[call [arg canvasName] [method {image unset}] [arg cell]]
Invoking this method declares the specified [arg cell] of the
background as empty, an existing image shown by this cell will be
forgotten. The cell is given as a 2-element list containing row and
column number, in this order.
[call [arg canvasName] [method flush]]
Invoking this method forces the canvas to completely reload the images
for all cells. Do not use this method if the canvas is operated
without a [option -grid-cell-command], as in that case the canvas will
simply forget all images without being able to reload them.
[list_end]
[section {Image ownership}]
Note that the canvas [emph {does not}] take ownership of the images it
shows in the background. In other words, when we say that the canvas
forgets an image this means only that the association between a grid
cell and shown image is broken. The image is [emph not]
deleted. Managing the lifecycle of the images shown by the canvas is
responsibility of the user of the canvas.
[keywords map {square map} canvas tile grid cell image]
[manpage_end]
|
