1 <!-- manual page source format generated by PolyglotMan v3.0.4, -->
2 <!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
6 <TITLE>planchet(n) manual page</TITLE>
9 <A HREF="#toc">Table of Contents</A><P>
13 <H2><A NAME="sect0" HREF="#toc0">NAME </A></H2>
14 planchet - Create and manipulate planchet widgets
15 <H2><A NAME="sect1" HREF="#toc1">SYNOPSIS
17 <B>planchet<I> <I>pathName </I></I></B>?<I>options </I>?
18 <H2><A NAME="sect2" HREF="#toc2">STANDARD OPTIONS </A></H2>
21 <B> -background<tt> </tt> <tt> </tt> -insertwidth<tt> </tt> <tt> </tt> -state
23 -insertbackground<tt> </tt> <tt> </tt> -relief<tt> </tt> <tt> </tt> -tile <BR>
24 -cursor<tt> </tt> <tt> </tt> -insertborderwidth<tt> </tt> <tt> </tt> -selectbackground<tt> </tt> <tt> </tt> -takefocus
26 -highlightbackground<tt> </tt> <tt> </tt> -insertofftime<tt> </tt> <tt> </tt> -selectborderwidth<tt> </tt> <tt> </tt> -xscrollcommand <BR>
27 -highlightcolor<tt> </tt> <tt> </tt> -insertontime<tt> </tt> <tt> </tt> -selectforeground<tt> </tt> <tt> </tt> -yscrollcommand
30 </B>See the <B>options </B> manual entry for details on the standard options. <P>
32 </B> Standard optiosn -highlightthickness and <B>-bordewidth </B> are ignored by planchet,
33 and set to 0. Therefore <B>-relief </B> options have no effect.
34 <H2><A NAME="sect3" HREF="#toc3">WIDGET-SPECIFIC
38 Command-Line Name:<tt> </tt> <tt> </tt> <B>-coordformat </B> <BR>
39 Database Name:<tt> </tt> <tt> </tt> <B>coordFormat </B> <BR>
41 Class:<tt> </tt> <tt> </tt> <B>CoordFormat </B> <BR>
45 <DT> Specifies format string to display current map coordinates,
46 if no projection </DT>
47 <DD>defined. Defaults to "X=%0.8g Y=%0.8g" </DD>
51 Command-Line Name:<tt> </tt> <tt> </tt> <B>-orient
53 Database Name:<tt> </tt> <tt> </tt> <B>orient </B> <BR>
54 Database Class:<tt> </tt> <tt> </tt> <B>Orient </B> <BR>
58 <DT> Specifies printing orientation
59 for this planchet. May be either portrait </DT>
60 <DD>or landscape. Defaults to landscape
65 Command-Line Name:<tt> </tt> <tt> </tt> <B>-lookwidth </B> <BR>
66 Database Name:<tt> </tt> <tt> </tt> <B>lookWidth </B> <BR>
67 Database Class:<tt> </tt> <tt> </tt> <B>LookWidth
72 <DT> Wraplength of text in popup look window. Defaults to 200. </DT>
78 Name:<tt> </tt> <tt> </tt> <B>-shiftfactor </B> <BR>
79 Database Name:<tt> </tt> <tt> </tt> <B>shiftFactor </B> <BR>
80 Database Class:<tt> </tt> <tt> </tt> <B>ShiftFactor
85 <DT> Specifies share of window size to move on <B>shift </B> widget command. </DT>
91 Command-Line Name:<tt> </tt> <tt> </tt> <B>-resizable </B> <BR>
92 Database Name:<tt> </tt> <tt> </tt> <B>resizable </B> <BR>
94 Class:<tt> </tt> <tt> </tt> <B>Resizable </B> <BR>
98 <DT> Specifies a boolean value that indicates whether or
99 not should planchet </DT>
100 <DD>adjust its width/height ratio, when coordinate limits
101 are first defined. </DD>
105 Command-Line Name:<tt> </tt> <tt> </tt> <B>-rulerpos </B> <BR>
106 Database Name:<tt> </tt> <tt> </tt> <B>rulerPos </B>
108 Database Class:<tt> </tt> <tt> </tt> <B>RulerPos </B> <BR>
112 <DT> Indicates position of scale ruler in planchet.
113 (its left end). Should be </DT>
114 <DD>list of two coordinates in any form, acceptable
115 by Tk. Positive values are measured from top and left and negative from
116 lower and right side of planchet </DD>
120 Command-Line Name:<tt> </tt> <tt> </tt> <B>-scalevar </B> <BR>
122 Name:<tt> </tt> <tt> </tt> <B>scaleVar </B> <BR>
123 Database Class:<tt> </tt> <tt> </tt> <B>Variable </B> <BR>
127 <DT> Specifies the name of variable.
128 Current scale of map would be stored in </DT>
129 <DD>this variable automatically upon
130 each change of scale in form 1:denominator. If variable doesn't exist in
131 global scope, it would be created. </DD>
135 Command-Line Name:<tt> </tt> <tt> </tt> <B>-statusline </B> <BR>
137 Name:<tt> </tt> <tt> </tt> <B>statusLine </B> <BR>
138 Database Class:<tt> </tt> <tt> </tt> <B>none </B> <BR>
142 <DT> Specifies name of label widget
143 which would be used for displaying status </DT>
144 <DD>information of planchet (i.e.
145 current mouse pointer coordinates). Widget should exist before creating
146 planchet or before passing it to planchet configure command. </DD>
151 Name:<tt> </tt> <tt> </tt> <B>-legbox </B> <BR>
152 Database Name:<tt> </tt> <tt> </tt> <B>legBox </B> <BR>
153 Database Class:<tt> </tt> <tt> </tt> <B>none </B> <BR>
158 name of canvas widget which would display scrollable legend of </DT>
160 layer. Note, that scrollable legend is not printed automatically by print
161 command. All contents of this widget would be erased each time base layer
162 changed in planchet. </DD>
166 Command-Line Name:<tt> </tt> <tt> </tt> <B>-zoombutton </B> <BR>
167 Database Name:<tt> </tt> <tt> </tt> <B>zoomButton
169 Database Class:<tt> </tt> <tt> </tt> <B>none </B> <BR>
173 <DT> Specifies name of button, which is used to initiate
174 zoom operation on </DT>
175 <DD>canvas. (usially via <B>zoom </B>) widget command. Planchet
176 controls its state, disabling it, if coordinate system is not defined.
177 It should exist before it passed to planchet. </DD>
181 Command-Line Name:<tt> </tt> <tt> </tt> <B>-unzoombuttons
183 Database Name:<tt> </tt> <tt> </tt> <B>unzoomButtons </B> <BR>
184 Database Class:<tt> </tt> <tt> </tt> <B>none </B> <BR>
189 of buttons, which are used to perform various unzoom operations </DT>
191 <B>unzoom </B> or <B>limits default </B> widget commands). Planchet controls their state,
192 disabling them if such operations are impossible. </DD>
196 Command-Line Name:<tt> </tt> <tt> </tt> <B>-shiftbuttons
198 Database Name:<tt> </tt> <tt> </tt> <B>shiftButtons </B> <BR>
199 Database Class:<tt> </tt> <tt> </tt> <B>none </B> <BR>
203 <DT> Specifies list of
204 four buttons for perform shift operation on planchet. </DT>
205 <DD>Buttons are specified
206 in following order left(west) down(south) <A HREF="up.north.html">up(north)</A>
208 the same way as vi cursor movement keys are situated on keyboard. </DD>
213 Name:<tt> </tt> <tt> </tt> <B>-zoombutton </B> <BR>
214 Database Name:<tt> </tt> <tt> </tt> <B>zoomButton </B> <BR>
215 Database Class:<tt> </tt> <tt> </tt> <B>none </B> <BR>
220 name of button, which is used to initiate zoom operation on </DT>
222 via <B>zoom </B>) widget command. Planchet controls its state, disabling it, if
223 coordinate system is not defined. It should exist before it passed to planchet.
228 Command-Line Name:<tt> </tt> <tt> </tt> <B>-unzoombuttons </B> <BR>
229 Database Name:<tt> </tt> <tt> </tt> <B>unzoomButtons </B> <BR>
231 Class:<tt> </tt> <tt> </tt> <B>none </B> <BR>
235 <DT> Specifies list of buttons, which are used to perform various
236 unzoom operations </DT>
237 <DD>(like <B>unzoom </B> or <B>limits default </B> widget commands). Planchet
238 controls their state, disabling them if such operations are impossible.
243 Command-Line Name:<tt> </tt> <tt> </tt> <B>-shiftbuttons </B> <BR>
244 Database Name:<tt> </tt> <tt> </tt> <B>shiftButtons </B> <BR>
246 Class:<tt> </tt> <tt> </tt> <B>none </B> <BR>
250 <DT> Specifies list of four buttons for perform shift operation
252 <DD>Buttons are specified in following order left(west) down(south)
253 <A HREF="up.north.html">up(north)</A>
254 and right(west), the same way as vi cursor movement keys are
255 situated on keyboard. This buttons should be either all be specified or
256 all be empty, in which case list of four empty elements should be passed.
257 Planchet not only controls state of buttons, but also redefines their
262 Command-Line Name:<tt> </tt> <tt> </tt> <B>-projection </B> <BR>
263 Database Name:<tt> </tt> <tt> </tt> <B>projection </B> <BR>
265 Class:<tt> </tt> <tt> </tt> <B>none </B> <BR>
269 <DT> Specifies Fgis projection object which is used to convert
271 <DD>coordinates of planchet into geographic (latitude and
272 longitude) and vice versa. </DD>
276 In addition to these all options of <B>canvas
277 </B> widget are supported.
278 <H2><A NAME="sect4" HREF="#toc4">INTRODUCTION </A></H2>
280 The <B>planchet </B> command creates a new
281 window (given by the <I>pathName </I> argument and makes it into planchet widget.
283 Additional options, described above, can be given to control its behavoir.
284 Currently they could be specified only in command line, not in option
285 database, but it shoudl change in future. <P>
286 <B>planchet </B> command returns its
287 <I>pathName </I> argument. At the time this command is invoked, there must not
288 exist a window, named <I>pathName </I>, but <I>pathName </I>'s parent must exist. <B>planchet
289 </B> command also creates new Tcl command named <I>pathName </I> which can be used
290 to control widget. <P>
292 Planchet widget have all behavoir supported by Tk
293 <B>canvas </B> widget, but, in addition it could have chartographic coordinate
294 system and able to visualize and manipulate maps. <P>
296 <H2><A NAME="sect5" HREF="#toc5">COORDINATE SYSTEM </A></H2>
299 Planchet coordinate system is real-world coordinate system. Its coordinates
300 should be in meters of earth surface, not in pixels, millimeters or other
301 map sheet or screen-related units. It can be defined either explicitely
302 via <B>limits </B> widget command, or implicitely, when first map is shown in
304 There are special commands which allow to recalculate from map
305 (realword) coordinates to screen coordinates. Screen coordinate system
306 of planchet is same as of canvas.
307 <H2><A NAME="sect6" HREF="#toc6">LAYERS </A></H2>
308 Planchet can visualize maps,
309 which are represented as Fgis layer objects. There are two ways of display
310 layer - as base layer or as ovelay. <P>
311 Base layers are opaque, they are typically
312 raster layers, shown by colors. There can be only one base layer in plachet
313 in given time. If <B>legbox </B> helper widget is defined, and legend for base
314 layer is drawable, it would be displayed in this widget. Several layer
315 types couldn't be displayed as base layers. <P>
317 Overlay layers are transparent,
318 although visible. There can be several overlay layers in planchet at given
319 time. Any layer can be displayed as overlay. <P>
320 When first layer is displayed
321 in planchet, with undefined coordinate system, coordinate system limits
322 for planchet are got from limits of layer. If layer cannot provide this
323 information, it causes an error. <P>
325 <H2><A NAME="sect7" HREF="#toc7">HELPER WIDGETS </A></H2>
327 Planchet can be accompanied
328 with several other widgets, which are used to interact with user. If this
329 widgets are passed to planchet via commandline options (or via widget
330 <B>configure </B>) command, it can control them automatically and disable them,
331 if corresponding action is impossible. See <B>OPTIONS ABOVE </B>. <P>
333 <H2><A NAME="sect8" HREF="#toc8">SCALE INDICATION
336 There are two traditional ways of scale indication - numerical and graphical.
337 As numerical indication, <B>-scalevar </B> option of planchet widget allows to
338 specfy Tcl global variable, which would always hold current value of map
340 As graphical representation of scale, planchet can display scale
341 ruler which shows how some realword distance is visible in planchet. <P>
344 <H2><A NAME="sect9" HREF="#toc9">LOOK FEATURE </A></H2>
346 Planchet allows to collect information from several layers
347 in given point. By default it pops up window with this information on right
348 button click. Set of layers which included in this information is called
349 <B>look list </B>. <P>
351 <H2><A NAME="sect10" HREF="#toc10">WIDGET COMMAND </A></H2>
354 The <B>planchet </B> command creates a new Tcl command
355 whose name is <I>pathName </I>. This command can be used to invoke various operaitons
356 on the widget. It has following general form: <blockquote><P>
357 <I>pathName option </I>?<I>arg arg
360 <I>Option </I> and the <I>arg </I>s determine the exact behavior of the command.
361 Planchet supports all widget commands, defined for <B>canvas </B> widget and
362 following special commands, specific to planchet:
365 <DT><I>pathName <B>clear </B></I> </DT>
367 all layers from planchet, and from look list and unsets coordinate system
370 <DT><I>pathName <B>cget<I> option </I></B></I> </DT>
371 <DD>Returns value of specified configuration option.
372 In addition to standard options and widget specific options, supports
373 all options of canvas widget. Several internal variables can also be obtained
374 this way, but it is dirty and undocumented hack. </DD>
376 <DT><I>pathName <B>configure<I> option
377 arg ?option arg ...? </I></B></I> </DT>
378 <DD>Allows to change value of one or more options. </DD>
381 <B>fit<I> x y </I></B></I> </DT>
382 <DD>Returns 1 if point, given in real world coordinates is inside
383 current planchet limits, and 0 otherwise. </DD>
385 <DT><I>pathName <B>hide<I> pattern ?pattern...?
387 <DD>Removes all layers which matches pattern from planchet. </DD>
389 <DT><I>pathName <B>layers
390 </B></I> ?<I>pattern </I>? </DT>
391 <DD>Return list of all visible layers, either base or overlays,
392 which match given pattern. By default - all layers. </DD>
394 <DT><I>pathName <B>limits </B></I> </DT>
396 to control limits of realword coordinate system. Can have one of following
397 form <blockquote></DD>
399 <DT><B>limits </B> </DT>
400 <DD>Without any arguments return list of four double values,
401 representing real world coordinates of window sides. They are given in
402 folowing order: <blockquote><P>
403 <I>XLeft YBottom XRight YTop </I><BR>
410 <DT><B>limits <I>list </I></B> </DT>
413 <DT><B>limits <I>xleft
414 ybottom xright ytop </I></B> </DT>
415 <DD>Given list of four double values or four double
416 values as separate arguments, sets planchet limits for this value. If <B>-resizable
417 </B> option is true and no coordinate system was defined before, adjusts width/height
418 ratio of planchet to reflect this ratio of given limits. Otherwise expands
419 given limits to have same width/height ratio as widget. </DD>
423 of axes of given limits doesn't match those of currently defined coordinate
424 system, silently reverts them. Therefore order of coordinates in insignificant,
425 once coordinate system is defined. <P>
426 If coordinate system was defined, assumes
427 that zooming operation is performed and stores old limits in zoom stack
428 for subsequent unzoom operation. If scale of given limits is smaller, then
429 of some limits in zoom stack, discards all elements with scale larger
430 than given for unzoom operation shouldn't increase scale. Nevertheless initial
431 limits are never discarded this way.
434 <DT><B>limits default </B> </DT>
435 <DD>Clears zoom stack
436 and restores coordinate limits to their initial values. </DD>
442 <DT><I>pathName <B>look
444 <DD>Controls <B>LOOK FEATURE </B> of planchet. Can have one of following forms
447 <DT><B>look add <I>layer </I></B> </DT>
448 <DD>adds layer to look list. </DD>
450 <DT><B>look list </B>?<I>pattern </I>? </DT>
452 list of layers in look list, which match pattern. By default all layers
455 <DT><B>look remove <I>pattern </I></B> </DT>
456 <DD>removes layers which match pattern from look list
459 <DT><B>look remove all </B> </DT>
460 <DD>clears look list entirely </DD>
462 <DT><B>look <I>x y </I></B>?<B>-titled|-list|-raw </B>?
464 <DD>return list of information for all layers in look list at given point.
465 If <B>-titled </B> option is specified, each element in list is formatted string.
466 Otherwise it is two element list which first element - layer title, and
467 second - layer value. <B>-raw </B> option returns only values, without layer title
471 Length of this list not neccesary matches length of look
472 list, becouse if some layers are undefined in given point, they do not
473 create list element. </blockquote>
477 <DT><I>pathName <B>mapx <I>x </I></B></I> </DT>
480 <DT><I>pathName <B>mapy </B></I> </DT>
481 <DD>Given screen coordinate
482 in any form, acceptable by Tk, returns realword coordinate. </DD>
484 <DT><I>pathName <B>print
485 </B></I> ?option arg ...? </DT>
486 <DD>Wrapper around <B>postscript </B> command. Uses default Fgis font
487 mapping and print system, also widget default orientation. By default,
488 send output to default Fgis printer using command, defined in fgis configuration
492 Following options are supported: <blockquote><B>-colormode<I> mode </I></B> Same as <B>colormode
493 </B> option in canvas <B>postscript </B> command.
496 <DT><B>-file<I> filename </I></B> </DT>
498 representation of planchet into given file, instead of piping it to print
501 <DT><B>-fontmap <I>variable </I></B> </DT>
502 <DD>array used to map screen fonts to postscript
503 fonts. See canvas <B>postscript </B> command for more information. </DD>
505 <DT><B>-printer <I>printername
507 <DD>Overrides default printer, specified in fgis.rc file. </DD>
513 <DT><I>pathName <B>ruler<I>
514 ?on|off? </I></B></I> </DT>
515 <DD>Controls scale ruler. </DD>
517 <DT><I>pathName <B>scale </B></I> ?<I>denominator </I>? </DT>
519 arguments returns current scale denominator. If <I>denominator </I> is given,
520 adjust coordinate limits so that scale would be as specified and center
521 point of widget would have same realworld coordinates as before. </DD>
525 other arguments are specified, behaves as <B>canvas </B> widget <B>scale </B> command.
530 <DT><I>pathName <B>scrx <I>x </I></B></I> </DT>
533 <DT><I>pathName <B>scry <I>y </I></B></I> </DT>
534 <DD>Given realworld coordinate, returns
535 screen coordinate in pixels. </DD>
537 <DT><I>pathName <B>setstatus </B></I> </DT>
538 <DD>Displays message if <B>-statusline
539 </B> helper widget, if defined, otherwise does nothing. Can have one of two
540 form: <blockquote></DD>
542 <DT><B>setstatus<I> message </I></B> </DT>
543 <DD>displays message as specified </DD>
545 <DT><B>setstatus<I> x y
547 <DD>Displays given coordinates. If no projection defined, they would be displayed
548 using Tcl <B>format </B> command with value of <B>-coordformat </B> option as first argument.
549 Otherwise they would be displayed using <B>format </B> object command of current
556 <DT><I>pathName <B>shift <I>direction </I></B></I> </DT>
557 <DD>Changes current coordinate limits
558 so that current view shifts in specified <I>direction </I> by share of corresponding
559 widget size, specified by <B>-shiftfactor </B> option. </DD>
561 <DT><I>pathName <B>show <I>layer </I></B></I>?<B>-base
562 </B>|<B>-overlay </B>? </DT>
563 <DD>Displays specified layer. If neither <B>-base </B> nor <B>-overlay </B> is specifed,
564 shows layer as base if no base layer currently present and layer can be
565 displayed as base. Otherwise displays it as overlay. </DD>
567 <DT><I>pathName <B>unzoom </B></I> </DT>
569 last coordinate limits from zoom stack </DD>
571 <DT><I>pathName <B>zoom </B></I> ?<I> x y </I>? x y ??
573 <DD>Initiates interactive zoom operation. If no coordinates are specified,
574 prompts user to pick both corners of rectangle to display. If one pair
575 is specified, prompts only for second pair. With two pairs just converts
576 values from canvas to realworld coordinates and performs <B>limits </B> command
577 on them. <blockquote><P>
578 <I>pathName <B>zoom cancel </B></I> <BR>
582 can be used to abort interactive zoom
583 operation currently in progress. <blockquote><P>
584 <I>pathName <B>zoom cancel </B></I> <BR>
587 to abort interactive zoom operation currently in progress.
588 <H2><A NAME="sect11" HREF="#toc11">SEE ALSO </A></H2>
589 <B><A HREF="layer.n.html">layer</B>(n)</A>
592 <H2><A NAME="sect12" HREF="#toc12">BUGS </A></H2>
593 No care taken to do something useful if interactive zoom operation
594 is performed on two planchets simulateously. <P>
601 <A NAME="toc"><B>Table of Contents</B></A><P>
603 <LI><A NAME="toc0" HREF="#sect0">NAME</A></LI>
604 <LI><A NAME="toc1" HREF="#sect1">SYNOPSIS</A></LI>
605 <LI><A NAME="toc2" HREF="#sect2">STANDARD OPTIONS</A></LI>
606 <LI><A NAME="toc3" HREF="#sect3">WIDGET-SPECIFIC OPTIONS</A></LI>
607 <LI><A NAME="toc4" HREF="#sect4">INTRODUCTION</A></LI>
608 <LI><A NAME="toc5" HREF="#sect5">COORDINATE SYSTEM</A></LI>
609 <LI><A NAME="toc6" HREF="#sect6">LAYERS</A></LI>
610 <LI><A NAME="toc7" HREF="#sect7">HELPER WIDGETS</A></LI>
611 <LI><A NAME="toc8" HREF="#sect8">SCALE INDICATION</A></LI>
612 <LI><A NAME="toc9" HREF="#sect9">LOOK FEATURE</A></LI>
613 <LI><A NAME="toc10" HREF="#sect10">WIDGET COMMAND</A></LI>
614 <LI><A NAME="toc11" HREF="#sect11">SEE ALSO</A></LI>
615 <LI><A NAME="toc12" HREF="#sect12">BUGS</A></LI>