1[comment {-*- tcl -*- doctools manpage}]
2[manpage_begin map::slippy::cache n 0.2]
3[moddesc   {Mapping utilities}]
4[titledesc {Management of a tile cache in the local filesystem}]
5[require Tcl 8.4]
6[require Tk 8.4]
7[require img::png]
8[require map::slippy]
9[require map::slippy::cache [opt 0.2]]
10[description]
11
12This package provides a class for managing a cache of tiles for
13slippy-based maps in the local filesystem.
14
15[section API]
16
17[list_begin definitions]
18
19[call [cmd ::map::slippy::cache] [arg cacheName] [arg cachedir] [arg provider]]
20
21Creates the cache [arg cacheName] and configures it with both the path
22to the directory contaiing the locally cached tiles ([arg cachedir]),
23and the command prefix from which it will pull tiles asked for and not
24yet known to the cache itself ([arg provider]).
25
26[para]
27
28The result of the command is [arg cacheName].
29
30[list_end]
31
32
33[subsection Methods]
34
35[list_begin definitions]
36
37[call [arg cacheName] [method valid] [arg tile] [opt [arg msgvar]]]
38
39This method checks the validity of a the given [arg tile] identifier.
40This is a convenience wrapper to [cmd {::map::slippy tile valid}] and
41has the same interface.
42
43
44
45[call [arg cacheName] [method exists] [arg tile]]
46
47This methods tests whether the cache contains the specified [arg tile]
48or not. The result is a boolean value, [const true] if the tile is
49known, and [const false] otherwise. The tile is identified by a list
50containing three elements, zoom level, row, and column number, in this
51order.
52
53
54
55[call [arg cacheName] [method get] [arg tile] [arg donecmd]]
56
57This is the main method of the cache, retrieving the image for the
58specified [arg tile] from the cache. The tile identifier is a list
59containing three elements, the zoom level, row, and column number of
60the tile, in this order.
61
62[para]
63
64The command refix [arg donecmd] will be invoked when the cache
65either knows the image for the tile or that no image will forthcoming.
66It will be invoked with either 2 or 3 arguments, i.e.
67
68[list_begin enum]
69[enum] The string [const set], the [arg tile], and the image.
70[enum] The string [const unset], and the [arg tile].
71[list_end]
72
73These two possibilities are used to either signal the image for the
74[arg tile], or that the [arg tile] has no image defined for it.
75
76[para]
77
78When the cache has no information about the tile it will invoke the
79[arg provider] command prefix specified during its construction,
80adding three arguments: The string [const get], the [arg tile], and a
81callback into the cache. The latter will be invoked by the provider to
82either transfer the image to the cache, or signal that the tile has no
83image.
84
85[para]
86
87When multiple requests for the same tile are made only one request
88will be issued to the provider.
89
90[list_end]
91
92[section References]
93
94[list_begin enum]
95[enum]	[uri http://wiki.openstreetmap.org/wiki/Main_Page]
96[list_end]
97
98
99[keywords cache tile slippy map location zoom filesystem]
100[manpage_end]
101
102