1canvas::sqmap(n) Variations on a canvas canvas::sqmap(n)
2______________________________________________________________________________
6
8 canvas::sqmap - Canvas with map background based on square tiles
9
11 package require Tcl 8.4
12 package require Tk 8.4
14 package require canvas::sqmap ?0.2?
16 ::canvas::sqmap pathName ?options?
18 canvasName image set cell image
20 canvasName image unset cell
22 canvasName flush
24______________________________________________________________________________
26
28 This package provides an extended canvas widget for the display of maps
29 based on a set of square image tiles. The tiles are the background of
30 the canvas, with all other canvas items added always shown in front of
31 them. The number of tiles shown, tile size, and where to get the images
32 to show are all configurable.
33
35 ::canvas::sqmap pathName ?options?
36 Creates the canvas pathName and configures it. The new widget
37 supports all of the options and methods of a regular canvas,
38 plus the options and methods described below.
39 The result of the command is pathName.
41 OPTIONS
43 -grid-cell-width
44 The value for this option is a non-negative integer. It speci‐
45 fies the width of the cells the background is made up of.
46 -grid-cell-height
48 The value for this option is a non-negative integer. It speci‐
49 fies the height of the cells the background is made up of.
50 -grid-cell-command
52 The value for this option is a command prefix. It is nvoked
53 whenever the canvas needs the image for a specific cell of the
54 background, with two additional arguments, the id of the cell,
55 and a command prefix to invoke when the image is ready, or known
56 to not exist.
57 The id of the cell is a 2-element list containing the row and
59 column number of the cell, in this order. The result command
60 prefix (named "$result" in the example below) has to be invoked
61 with either two or three arguments, i.e.
62 $result set $cellid $image ; # image is known and ready
65 $result unset $cellid ; # image does not exist
66 This option may be left undefined, i.e. the canvas can operate
69 without it. In that case the only images shown in grid cells are
70 those explicitly set with the method image set, see the next
71 section. All other grid cells will simply be empty.
72 -viewport-command
74 This option specifies a command prefix to invoke when the view‐
75 port of the canvas is changed, to allow users keep track of
76 where in the scroll-region we are at all times. This can be
77 used, for example, to drive derivate displays, or to keep items
78 in view by moving them as the viewport moves.
79 METHODS
81 canvasName image set cell image
82 Invoking this method places the image into the specified cell of
83 the background. The cell is given as a 2-element list containing
84 row and column number, in this order.
85 Note that an image is allowed to be associated with and dis‐
87 played in multiple cells of the canvas.
88 canvasName image unset cell
90 Invoking this method declares the specified cell of the back‐
91 ground as empty, an existing image shown by this cell will be
92 forgotten. The cell is given as a 2-element list containing row
93 and column number, in this order.
94 canvasName flush
96 Invoking this method forces the canvas to completely reload the
97 images for all cells. Do not use this method if the canvas is
98 operated without a -grid-cell-command, as in that case the can‐
99 vas will simply forget all images without being able to reload
100 them.
101
103 Note that the canvas does not take ownership of the images it shows in
104 the background. In other words, when we say that the canvas forgets an
105 image this means only that the association between a grid cell and
106 shown image is broken. The image is not deleted. Managing the lifecycle
107 of the images shown by the canvas is responsibility of the user of the
108 canvas.
109
111 canvas, cell, grid, image, map, square map, tile
112canvas 0.2 canvas::sqmap(n)