]> www.wagner.pp.ru Git - oss/fgis.git/blob - man/planchet.n
Added logic to find GDAL installation.
[oss/fgis.git] / man / planchet.n
1 '\" Stuff below is shamelessly borrowed from canvas(n) manual page, and 
2 '\" therefore shares its copyright
3 .if t .wh -1.3i ^B
4 .nr ^l \n(.l
5 .ad b
6 '\"     # Start an argument description
7 .de AP
8 .ie !"\\$4"" .TP \\$4
9 .el \{\
10 .   ie !"\\$2"" .TP \\n()Cu
11 .   el          .TP 15
12 .\}
13 .ie !"\\$3"" \{\
14 .ta \\n()Au \\n()Bu
15 \&\\$1  \\fI\\$2\\fP    (\\$3)
16 .\".b
17 .\}
18 .el \{\
19 .br
20 .ie !"\\$2"" \{\
21 \&\\$1  \\fI\\$2\\fP
22 .\}
23 .el \{\
24 \&\\fI\\$1\\fP
25 .\}
26 .\}
27 ..
28 '\"     # define tabbing values for .AP
29 .de AS
30 .nr )A 10n
31 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
32 .nr )B \\n()Au+15n
33 .\"
34 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
35 .nr )C \\n()Bu+\\w'(in/out)'u+2n
36 ..
37 .AS Tcl_Interp Tcl_CreateInterp in/out
38 '\"     # BS - start boxed text
39 '\"     # ^y = starting y location
40 '\"     # ^b = 1
41 .de BS
42 .br
43 .mk ^y
44 .nr ^b 1u
45 .if n .nf
46 .if n .ti 0
47 .if n \l'\\n(.lu\(ul'
48 .if n .fi
49 ..
50 '\"     # BE - end boxed text (draw box now)
51 .de BE
52 .nf
53 .ti 0
54 .mk ^t
55 .ie n \l'\\n(^lu\(ul'
56 .el \{\
57 .\"     Draw four-sided box normally, but don't draw top of
58 .\"     box if the box started on an earlier page.
59 .ie !\\n(^b-1 \{\
60 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
61 .\}
62 .el \}\
63 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
64 .\}
65 .\}
66 .fi
67 .br
68 .nr ^b 0
69 ..
70 '\"     # VS - start vertical sidebar
71 '\"     # ^Y = starting y location
72 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
73 .de VS
74 .if !"\\$1"" .br
75 .mk ^Y
76 .ie n 'mc \s12\(br\s0
77 .el .nr ^v 1u
78 ..
79 '\"     # VE - end of vertical sidebar
80 .de VE
81 .ie n 'mc
82 .el \{\
83 .ev 2
84 .nf
85 .ti 0
86 .mk ^t
87 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
88 .sp -1
89 .fi
90 .ev
91 .\}
92 .nr ^v 0
93 ..
94 '\"     # Special macro to handle page bottom:  finish off current
95 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
96 '\"     # page bottom macro.
97 .de ^B
98 .ev 2
99 'ti 0
100 'nf
101 .mk ^t
102 .if \\n(^b \{\
103 .\"     Draw three-sided box if this is the box's first page,
104 .\"     draw two sides but no top otherwise.
105 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
106 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
107 .\}
108 .if \\n(^v \{\
109 .nr ^x \\n(^tu+1v-\\n(^Yu
110 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
111 .\}
112 .bp
113 'fi
114 .ev
115 .if \\n(^b \{\
116 .mk ^y
117 .nr ^b 2
118 .\}
119 .if \\n(^v \{\
120 .mk ^Y
121 .\}
122 ..
123 '\"     # DS - begin display
124 .de DS
125 .RS
126 .nf
127 .sp
128 ..
129 '\"     # DE - end display
130 .de DE
131 .fi
132 .RE
133 .sp
134 ..
135 '\"     # SO - start of list of standard options
136 .de SO
137 .SH "STANDARD OPTIONS"
138 .LP
139 .nf
140 .ta 4c 8c 12c
141 .ft B
142 ..
143 '\"     # SE - end of list of standard options
144 .de SE
145 .fi
146 .ft R
147 .LP
148 See the \\fBoptions\\fR manual entry for details on the standard options.
149 ..
150 '\"     # OP - start of full description for a single option
151 .de OP
152 .LP
153 .nf
154 .ta 4c
155 Command-Line Name:      \\fB\\$1\\fR
156 Database Name:  \\fB\\$2\\fR
157 Database Class: \\fB\\$3\\fR
158 .fi
159 .IP
160 ..
161 '\"     # CS - begin code excerpt
162 .de CS
163 .RS
164 .nf
165 .ta .25i .5i .75i 1i
166 ..
167 '\"     # CE - end code excerpt
168 .de CE
169 .fi
170 .RE
171 ..
172 .de UL
173 \\$1\l'|0\(ul'\\$2
174 ..
175 .TH planchet n 1.0 Fgis "user Tcl commands"
176 .BS
177 '\" Note:  do not modify the .SH NAME line immediately below!
178 .SH NAME
179 planchet \- Create and manipulate planchet widgets
180 .SH SYNOPSIS
181 \fBplanchet\fI \fIpathName \fR?\fIoptions\fR?
182 .SO
183 \-background    \-insertwidth   \-state
184 \-insertbackground      \-relief        \-tile
185 \-cursor        \-insertborderwidth     \-selectbackground      \-takefocus
186 \-highlightbackground   \-insertofftime \-selectborderwidth     \-xscrollcommand
187 \-highlightcolor        \-insertontime  \-selectforeground      \-yscrollcommand
188 .SE
189 .PP
190 \fBNote:\fR Standard optiosn \fb\-highlightthickness\fR and \fB\-bordewidth\fR
191 are ignored by planchet, and set to 0. Therefore \fB\-relief\fR options have
192 no effect.
193 .SH "WIDGET-SPECIFIC OPTIONS"
194 .OP \-coordformat coordFormat CoordFormat
195 Specifies format string to display current map coordinates, if no projection
196 defined. Defaults to "X=%0.8g Y=%0.8g"
197 .OP \-orient orient Orient
198 Specifies printing orientation for this planchet. May be either portrait
199 or landscape. Defaults to landscape
200 .OP \-lookwidth lookWidth LookWidth
201 Wraplength of text in popup look window. Defaults to 200.
202 .OP \-shiftfactor shiftFactor ShiftFactor
203 Specifies share of window size to move on \fBshift\fR widget command.
204 Defaults to 0.75
205 .OP \-resizable resizable Resizable
206 Specifies a boolean value that indicates whether or not should planchet
207 adjust its width/height ratio, when coordinate limits are first defined.
208 .OP \-rulerpos rulerPos RulerPos
209 Indicates position of scale ruler in planchet. (its left end). Should be
210 list of two coordinates in any form, acceptable by Tk. Positive values
211 are measured from top and left and negative from lower and right side 
212 of planchet
213 .OP \-scalevar scaleVar Variable
214 Specifies the name of variable. Current scale of map would be stored in
215 this variable automatically upon each change of scale in form 1:denominator.
216 If variable doesn't exist in global scope, it would be created.
217 .OP \-statusline statusLine none
218 Specifies name of label widget which would be used for displaying status
219 information of planchet (i.e. current mouse pointer coordinates).
220 Widget should exist before creating planchet or before passing it to
221 planchet configure command.
222 .OP \-legbox legBox none
223 Specifies name of canvas widget which would display scrollable legend of 
224 base layer. Note, that scrollable legend is not printed automatically by
225 print command. All contents of this widget would be erased each time
226 base layer changed in planchet.
227 .OP \-zoombutton zoomButton none
228 Specifies name of button, which is used to initiate zoom operation on
229 canvas. (usially via \fBzoom\fR) widget command. Planchet controls its
230 state, disabling it, if coordinate system is not defined. It should
231 exist before it passed to planchet.
232 .OP \-unzoombuttons unzoomButtons none
233 Specifies list of buttons, which are used to perform various unzoom operations
234 (like \fBunzoom\fR or \fBlimits default\fR widget commands). Planchet
235 controls their state, disabling them if such operations are impossible.
236 .OP \-shiftbuttons shiftButtons none
237 Specifies list of four buttons for perform shift operation on planchet.
238 Buttons are specified in following order  left(west) down(south) up(north) and
239 right(west), the same way as vi cursor movement keys are situated on keyboard.
240 .OP \-zoombutton zoomButton none
241 Specifies name of button, which is used to initiate zoom operation on
242 canvas. (usially via \fBzoom\fR) widget command. Planchet controls its
243 state, disabling it, if coordinate system is not defined. It should
244 exist before it passed to planchet.
245 .OP \-unzoombuttons unzoomButtons none
246 Specifies list of buttons, which are used to perform various unzoom operations
247 (like \fBunzoom\fR or \fBlimits default\fR widget commands). Planchet
248 controls their state, disabling them if such operations are impossible.
249 .OP \-shiftbuttons shiftButtons none
250 Specifies list of four buttons for perform shift operation on planchet.
251 Buttons are specified in following order  left(west) down(south) up(north) and
252 right(west), the same way as vi cursor movement keys are situated on keyboard.
253 This buttons should be either all be specified or all be empty, in which case
254 list of four empty elements should be passed. Planchet not only controls
255 state of buttons, but also redefines their commands.
256 .OP \-projection projection none
257 Specifies Fgis projection object which is used to convert chartographic 
258 coordinates of planchet into geographic (latitude and longitude) and vice versa.
259
260 .PP
261 In addition to these all options of \fBcanvas\fR widget are supported.
262 .SH INTRODUCTION
263 .PP
264 The \fBplanchet\fR command creates a new window (given by the \fIpathName\fR
265 argument and makes it into planchet widget.
266
267 Additional options, described above, can be given to control its behavoir.
268 Currently they could be specified only in command line, not in option database,
269 but it shoudl change in future.
270
271 \fBplanchet\fR command returns its \fIpathName\fR argument. At the time this
272 command is invoked, there must not exist a window, named \fIpathName\fR,
273 but \fIpathName\fR's parent must exist.
274 \fBplanchet\fR command also creates new Tcl command named \fIpathName\fR
275 which can be used to control widget.
276
277 .PP
278  Planchet widget have all behavoir
279 supported by Tk \fBcanvas\fR widget, but, in addition it could have 
280 chartographic coordinate system and able to visualize and manipulate maps.
281
282 .SH COORDINATE SYSTEM
283
284 Planchet coordinate system is real-world coordinate system. Its coordinates
285 should be in meters of earth surface, not in pixels, millimeters or other
286 map sheet or screen-related units. It can be defined either explicitely
287 via \fBlimits\fR widget command, or implicitely, when first map is shown
288 in planchet.
289
290 There are special commands which allow to recalculate from map (realword)
291 coordinates to screen coordinates. Screen coordinate system of planchet is
292 same as of canvas. 
293 .SH LAYERS
294 Planchet can visualize maps, which are represented as Fgis layer objects.
295 There are two ways of display layer - as base layer or as ovelay.
296 .PP
297 Base layers are opaque, they are typically raster layers, shown by colors.
298 There can be only one base layer in plachet in given time. If \fBlegbox\fR
299 helper widget is defined, and legend for base layer is drawable, it would
300 be displayed in this widget.
301 Several layer types couldn't be displayed as base layers.
302
303 .PP
304 Overlay layers are transparent, although visible. There can be several 
305 overlay layers in planchet at given time. Any layer can be displayed as
306 overlay.
307 .PP
308 When first layer is displayed in planchet, with undefined coordinate system,
309 coordinate system limits for planchet are got from limits of layer. If
310 layer cannot provide this information, it causes an error.
311
312 .SH HELPER WIDGETS
313
314 Planchet can be accompanied with several other widgets, which are used
315 to interact with user. If this widgets are passed to planchet via commandline
316 options (or via widget \fBconfigure\fR) command, it can control them
317 automatically and disable them, if corresponding action is impossible.
318 See \fBOPTIONS ABOVE\fR.
319
320 .SH SCALE INDICATION 
321
322 There are two traditional ways of scale indication - numerical and graphical.
323 As numerical indication, \fB\-scalevar\fR option of planchet widget allows
324 to specfy Tcl global variable, which would always hold current value of map
325 scale.
326 .PP
327 As graphical representation of scale,
328 planchet can display scale ruler which shows how some realword distance
329 is visible in planchet.
330
331 .SH LOOK FEATURE
332
333 Planchet allows to collect information from several layers in given point.
334 By default it pops up window with this information on right button click.
335 Set of layers which included in this information is called \fBlook list\fR.
336
337 .SH "WIDGET COMMAND"
338 .PP
339
340 The \fBplanchet\fR command creates a new Tcl command whose name is
341 \fIpathName\fR. This command can be used to invoke various operaitons on
342 the widget. It has following general form:
343 .CS
344 \fIpathName option \fR?\fIarg arg ..\fR?
345 .CE
346 \fIOption\fR and the \fIarg\fRs
347 determine the exact behavior of the command.
348 Planchet supports all  widget commands, defined for \fBcanvas\fR widget
349 and following special commands, specific to planchet:
350 .TP
351 \fIpathName \fBclear\fR
352 Removes all layers from planchet, and from look list and unsets coordinate
353 system
354 .TP
355 \fIpathName \fBcget\fI option\fR
356 Returns value of specified configuration option. In addition to standard
357 options and widget specific options, supports all options of canvas widget.
358 Several internal variables can also be obtained this way, but it is dirty
359 and undocumented hack.
360 .TP
361 \fIpathName \fBconfigure\fI option arg ?option arg ...?\fR
362 Allows to change value of one or more options. 
363 .TP
364 \fIpathName \fBfit\fI x y\fR
365 Returns 1 if point, given in real world coordinates is inside current
366 planchet limits, and 0 otherwise.
367 .TP
368 \fIpathName \fBhide\fI pattern ?pattern...?\fR
369 Removes all layers which matches pattern from planchet.
370 .TP
371 \fIpathName \fBlayers\fR ?\fIpattern\fR?
372 Return list of all visible layers, either base or overlays, which match given
373 pattern. By default - all layers.
374 .TP
375 \fIpathName \fBlimits\fR
376 Used to control limits of realword coordinate system. Can have one of
377 following form
378 .RS
379 .TP
380 \fBlimits\fR 
381 Without any arguments return list of four double values, representing real
382 world coordinates of window sides. They are given in folowing order:
383 .CS
384 \fIXLeft YBottom XRight YTop
385 .CE
386 .TP
387 \fBlimits \fIlist\fR
388 .TP
389 \fBlimits \fIxleft ybottom xright ytop\fR
390 Given list of four double values or four double values as separate arguments,
391 sets planchet limits for this value. If \fB\-resizable\fR option is true
392 and no coordinate system was defined before, adjusts width/height ratio
393 of planchet to reflect this ratio of given limits. Otherwise expands
394 given limits to have same width/height ratio as widget.
395
396 If directions of axes of given limits doesn't match those of currently
397 defined coordinate system, silently reverts them. Therefore order
398 of coordinates in insignificant, once coordinate system is defined.
399
400 If coordinate system was defined, assumes that zooming operation is
401 performed and stores old limits in zoom stack for subsequent unzoom
402 operation. If scale of given limits is smaller, then
403 of some limits in zoom stack, discards all elements with scale larger
404 than given for unzoom operation shouldn't increase scale. Nevertheless
405 initial limits are never discarded this way.
406 .TP
407 \fBlimits default\fR
408 Clears zoom stack and restores coordinate limits to their initial values.
409 .RE
410  
411 .TP
412 \fIpathName \fBlook\fR
413 Controls \fBLOOK FEATURE\fR of planchet. Can have one of following forms
414 .RS
415 .TP
416 \fBlook add \fIlayer\fR
417 adds layer to look list.
418 .TP
419 \fBlook list \fR?\fIpattern\fR?
420 Returns list of layers in look list, which match pattern. By default all layers
421 .TP
422 \fBlook remove \fIpattern\fR
423 removes layers which match pattern from look list
424 .TP
425 \fBlook remove all\fR
426 clears look list entirely
427 .TP
428 \fBlook \fIx y \fR?\fB-titled|-list|-raw\fR?
429 return list of information for all layers in look list at given point.
430 If \fB-titled\fR option is specified, each element in list is formatted
431 string. Otherwise it is two element list which first element - layer title,
432 and second - layer value. \fB-raw\fR option returns only values, without
433 layer title information. 
434
435 Length of this list not neccesary matches length of look list, becouse if
436 some layers are undefined in given point, they do not create list element.
437 .RE
438 .TP
439 \fIpathName \fBmapx \fIx\fR
440 .TP
441 \fIpathName \fBmapy\fR
442 Given screen coordinate in any form, acceptable by Tk, returns realword
443 coordinate.
444 .TP
445 \fIpathName \fBprint\fR ?option arg ...?
446 Wrapper around \fBpostscript\fR command. Uses default Fgis font mapping and
447 print system, also widget default orientation. By default, send output
448 to default Fgis printer using command, defined in fgis configuration file.
449
450 Following options are supported:
451 .RS
452 \fB-colormode\fI mode\fR
453 Same as \fBcolormode\fR option in canvas \fBpostscript\fR command.
454 .TP
455 .TP
456 \fB-file\fI filename\fR
457 Write postscript representation of planchet into given file, instead of
458 piping it to print command.
459 .TP
460 \fB-fontmap \fIvariable\fR
461 array used to map screen fonts to postscript fonts. See canvas \fBpostscript\fR
462 command for more information.
463 .TP
464 \fB-printer \fIprintername\fR
465 Overrides default printer, specified in fgis.rc file.
466 .RE
467 .TP
468 \fIpathName \fBruler\fI ?on|off?\fR
469 Controls scale ruler.
470 .TP
471 \fIpathName \fBscale\fR ?\fIdenominator\fR?
472 With no arguments returns current scale denominator. If \fIdenominator\fR
473 is given, adjust coordinate limits so that scale would be as specified and
474 center point of widget would have same realworld coordinates as before.
475
476 If any other arguments are specified, behaves as \fBcanvas\fR widget \fBscale\fR
477 command.
478
479 .TP
480 \fIpathName \fBscrx \fIx\fR
481 .TP
482 \fIpathName \fBscry \fIy\fR
483 Given realworld coordinate, returns screen coordinate in pixels.
484 .TP
485 \fIpathName \fBsetstatus\fR
486 Displays message if \fB\-statusline\fR helper widget, if defined, otherwise
487 does nothing. Can have one of two form:
488 .RS
489 .TP
490 \fBsetstatus\fI message\fR
491 displays message as specified
492 .TP
493 \fBsetstatus\fI x y\fR
494 Displays given coordinates. If no projection defined, they would be displayed
495 using Tcl \fBformat\fR command with value of \fB\-coordformat\fR option as
496 first argument. Otherwise they would be displayed using \fBformat\fR object
497 command of current projection.
498 .RE
499 .TP
500 \fIpathName \fBshift \fIdirection\fR
501 Changes current coordinate limits so that current view shifts in specified
502 \fIdirection\fR by share of corresponding widget size, specified by 
503 \fB-shiftfactor\fR option.
504 .TP
505 \fIpathName \fBshow \fIlayer \fR?\fB-base\fR|\fB-overlay\fR?
506 Displays specified layer. If neither \fB-base\fR nor \fB-overlay\fR is specifed,
507 shows layer as base if no base layer currently present and layer can be
508 displayed as base. Otherwise displays it as overlay.
509 .TP
510 \fIpathName \fBunzoom\fR
511 Pops last coordinate limits from zoom stack
512 .TP
513 \fIpathName \fBzoom\fR ?\fI x y\fR? x y\fR??
514 Initiates interactive zoom operation. If no coordinates are specified,
515 prompts user to pick both corners of rectangle to display. If one pair
516 is specified, prompts only for second pair. With two pairs just converts
517 values from canvas to realworld coordinates and performs \fBlimits\fR command
518 on them.
519 .CS
520 \fIpathName \fBzoom cancel\fR
521 .CE
522 can be used to abort interactive zoom operation currently in progress.
523 .CS
524 \fIpathName \fBzoom cancel\fR
525 .CE
526 can be used to abort interactive zoom operation currently in progress.
527 .SH SEE ALSO
528 .BR layer (n)
529 .SH BUGS
530 No care taken to do something useful if interactive zoom operation is
531 performed on two planchets simulateously.
532
533
534
535