First checked in version

[oss/fgis.git] / man / planchet.n

'\" Stuff below is shamelessly borrowed from canvas(n) manual page, and 
'\" therefore shares its copyright
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"     # Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ie !"\\$3"" \{\
.ta \\n()Au \\n()Bu
\&\\$1  \\fI\\$2\\fP    (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1  \\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"     # define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"     # BS - start boxed text
'\"     # ^y = starting y location
'\"     # ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"     # BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"     Draw four-sided box normally, but don't draw top of
.\"     box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"     # VS - start vertical sidebar
'\"     # ^Y = starting y location
'\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$1"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"     # VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"     # Special macro to handle page bottom:  finish off current
'\"     # box/sidebar if in box/sidebar mode, then invoked standard
'\"     # page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"     Draw three-sided box if this is the box's first page,
.\"     draw two sides but no top otherwise.
.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
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"     # DS - begin display
.de DS
.RS
.nf
.sp
..
'\"     # DE - end display
.de DE
.fi
.RE
.sp
..
'\"     # SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"     # SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"     # OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:      \\fB\\$1\\fR
Database Name:  \\fB\\$2\\fR
Database Class: \\fB\\$3\\fR
.fi
.IP
..
'\"     # CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"     # CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH planchet n 1.0 Fgis "user Tcl commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
planchet \- Create and manipulate planchet widgets
.SH SYNOPSIS
\fBplanchet\fI \fIpathName \fR?\fIoptions\fR?
.SO
\-background    \-insertwidth   \-state
\-insertbackground      \-relief        \-tile
\-cursor        \-insertborderwidth     \-selectbackground      \-takefocus
\-highlightbackground   \-insertofftime \-selectborderwidth     \-xscrollcommand
\-highlightcolor        \-insertontime  \-selectforeground      \-yscrollcommand
.SE
.PP
\fBNote:\fR Standard optiosn \fb\-highlightthickness\fR and \fB\-bordewidth\fR
are ignored by planchet, and set to 0. Therefore \fB\-relief\fR options have
no effect.
.SH "WIDGET-SPECIFIC OPTIONS"
.OP \-coordformat coordFormat CoordFormat
Specifies format string to display current map coordinates, if no projection
defined. Defaults to "X=%0.8g Y=%0.8g"
.OP \-orient orient Orient
Specifies printing orientation for this planchet. May be either portrait
or landscape. Defaults to landscape
.OP \-lookwidth lookWidth LookWidth
Wraplength of text in popup look window. Defaults to 200.
.OP \-shiftfactor shiftFactor ShiftFactor
Specifies share of window size to move on \fBshift\fR widget command.
Defaults to 0.75
.OP \-resizable resizable Resizable
Specifies a boolean value that indicates whether or not should planchet
adjust its width/height ratio, when coordinate limits are first defined.
.OP \-rulerpos rulerPos RulerPos
Indicates position of scale ruler in planchet. (its left end). Should be
list of two coordinates in any form, acceptable by Tk. Positive values
are measured from top and left and negative from lower and right side 
of planchet
.OP \-scalevar scaleVar Variable
Specifies the name of variable. Current scale of map would be stored in
this variable automatically upon each change of scale in form 1:denominator.
If variable doesn't exist in global scope, it would be created.
.OP \-statusline statusLine none
Specifies name of label widget which would be used for displaying status
information of planchet (i.e. current mouse pointer coordinates).
Widget should exist before creating planchet or before passing it to
planchet configure command.
.OP \-legbox legBox none
Specifies name of canvas widget which would display scrollable legend of 
base layer. Note, that scrollable legend is not printed automatically by
print command. All contents of this widget would be erased each time
base layer changed in planchet.
.OP \-zoombutton zoomButton none
Specifies name of button, which is used to initiate zoom operation on
canvas. (usially via \fBzoom\fR) widget command. Planchet controls its
state, disabling it, if coordinate system is not defined. It should
exist before it passed to planchet.
.OP \-unzoombuttons unzoomButtons none
Specifies list of buttons, which are used to perform various unzoom operations
(like \fBunzoom\fR or \fBlimits default\fR widget commands). Planchet
controls their state, disabling them if such operations are impossible.
.OP \-shiftbuttons shiftButtons none
Specifies list of four buttons for perform shift operation on planchet.
Buttons are specified in following order  left(west) down(south) up(north) and
right(west), the same way as vi cursor movement keys are situated on keyboard.
.OP \-zoombutton zoomButton none
Specifies name of button, which is used to initiate zoom operation on
canvas. (usially via \fBzoom\fR) widget command. Planchet controls its
state, disabling it, if coordinate system is not defined. It should
exist before it passed to planchet.
.OP \-unzoombuttons unzoomButtons none
Specifies list of buttons, which are used to perform various unzoom operations
(like \fBunzoom\fR or \fBlimits default\fR widget commands). Planchet
controls their state, disabling them if such operations are impossible.
.OP \-shiftbuttons shiftButtons none
Specifies list of four buttons for perform shift operation on planchet.
Buttons are specified in following order  left(west) down(south) up(north) and
right(west), the same way as vi cursor movement keys are situated on keyboard.
This buttons should be either all be specified or all be empty, in which case
list of four empty elements should be passed. Planchet not only controls
state of buttons, but also redefines their commands.
.OP \-projection projection none
Specifies Fgis projection object which is used to convert chartographic 
coordinates of planchet into geographic (latitude and longitude) and vice versa.

.PP
In addition to these all options of \fBcanvas\fR widget are supported.
.SH INTRODUCTION
.PP
The \fBplanchet\fR command creates a new window (given by the \fIpathName\fR
argument and makes it into planchet widget.

Additional options, described above, can be given to control its behavoir.
Currently they could be specified only in command line, not in option database,
but it shoudl change in future.

\fBplanchet\fR command returns its \fIpathName\fR argument. At the time this
command is invoked, there must not exist a window, named \fIpathName\fR,
but \fIpathName\fR's parent must exist.
\fBplanchet\fR command also creates new Tcl command named \fIpathName\fR
which can be used to control widget.

.PP
 Planchet widget have all behavoir
supported by Tk \fBcanvas\fR widget, but, in addition it could have 
chartographic coordinate system and able to visualize and manipulate maps.

.SH COORDINATE SYSTEM

Planchet coordinate system is real-world coordinate system. Its coordinates
should be in meters of earth surface, not in pixels, millimeters or other
map sheet or screen-related units. It can be defined either explicitely
via \fBlimits\fR widget command, or implicitely, when first map is shown
in planchet.

There are special commands which allow to recalculate from map (realword)
coordinates to screen coordinates. Screen coordinate system of planchet is
same as of canvas. 
.SH LAYERS
Planchet can visualize maps, which are represented as Fgis layer objects.
There are two ways of display layer - as base layer or as ovelay.
.PP
Base layers are opaque, they are typically raster layers, shown by colors.
There can be only one base layer in plachet in given time. If \fBlegbox\fR
helper widget is defined, and legend for base layer is drawable, it would
be displayed in this widget.
Several layer types couldn't be displayed as base layers.

.PP
Overlay layers are transparent, although visible. There can be several 
overlay layers in planchet at given time. Any layer can be displayed as
overlay.
.PP
When first layer is displayed in planchet, with undefined coordinate system,
coordinate system limits for planchet are got from limits of layer. If
layer cannot provide this information, it causes an error.

.SH HELPER WIDGETS

Planchet can be accompanied with several other widgets, which are used
to interact with user. If this widgets are passed to planchet via commandline
options (or via widget \fBconfigure\fR) command, it can control them
automatically and disable them, if corresponding action is impossible.
See \fBOPTIONS ABOVE\fR.

.SH SCALE INDICATION 

There are two traditional ways of scale indication - numerical and graphical.
As numerical indication, \fB\-scalevar\fR option of planchet widget allows
to specfy Tcl global variable, which would always hold current value of map
scale.
.PP
As graphical representation of scale,
planchet can display scale ruler which shows how some realword distance
is visible in planchet.

.SH LOOK FEATURE

Planchet allows to collect information from several layers in given point.
By default it pops up window with this information on right button click.
Set of layers which included in this information is called \fBlook list\fR.

.SH "WIDGET COMMAND"
.PP

The \fBplanchet\fR command creates a new Tcl command whose name is
\fIpathName\fR. This command can be used to invoke various operaitons on
the widget. It has following general form:
.CS
\fIpathName option \fR?\fIarg arg ..\fR?
.CE
\fIOption\fR and the \fIarg\fRs
determine the exact behavior of the command.
Planchet supports all  widget commands, defined for \fBcanvas\fR widget
and following special commands, specific to planchet:
.TP
\fIpathName \fBclear\fR
Removes all layers from planchet, and from look list and unsets coordinate
system
.TP
\fIpathName \fBcget\fI option\fR
Returns value of specified configuration option. In addition to standard
options and widget specific options, supports all options of canvas widget.
Several internal variables can also be obtained this way, but it is dirty
and undocumented hack.
.TP
\fIpathName \fBconfigure\fI option arg ?option arg ...?\fR
Allows to change value of one or more options. 
.TP
\fIpathName \fBfit\fI x y\fR
Returns 1 if point, given in real world coordinates is inside current
planchet limits, and 0 otherwise.
.TP
\fIpathName \fBhide\fI pattern ?pattern...?\fR
Removes all layers which matches pattern from planchet.
.TP
\fIpathName \fBlayers\fR ?\fIpattern\fR?
Return list of all visible layers, either base or overlays, which match given
pattern. By default - all layers.
.TP
\fIpathName \fBlimits\fR
Used to control limits of realword coordinate system. Can have one of
following form
.RS
.TP
\fBlimits\fR 
Without any arguments return list of four double values, representing real
world coordinates of window sides. They are given in folowing order:
.CS
\fIXLeft YBottom XRight YTop
.CE
.TP
\fBlimits \fIlist\fR
.TP
\fBlimits \fIxleft ybottom xright ytop\fR
Given list of four double values or four double values as separate arguments,
sets planchet limits for this value. If \fB\-resizable\fR option is true
and no coordinate system was defined before, adjusts width/height ratio
of planchet to reflect this ratio of given limits. Otherwise expands
given limits to have same width/height ratio as widget.

If directions of axes of given limits doesn't match those of currently
defined coordinate system, silently reverts them. Therefore order
of coordinates in insignificant, once coordinate system is defined.

If coordinate system was defined, assumes that zooming operation is
performed and stores old limits in zoom stack for subsequent unzoom
operation. If scale of given limits is smaller, then
of some limits in zoom stack, discards all elements with scale larger
than given for unzoom operation shouldn't increase scale. Nevertheless
initial limits are never discarded this way.
.TP
\fBlimits default\fR
Clears zoom stack and restores coordinate limits to their initial values.
.RE
 
.TP
\fIpathName \fBlook\fR
Controls \fBLOOK FEATURE\fR of planchet. Can have one of following forms
.RS
.TP
\fBlook add \fIlayer\fR
adds layer to look list.
.TP
\fBlook list \fR?\fIpattern\fR?
Returns list of layers in look list, which match pattern. By default all layers
.TP
\fBlook remove \fIpattern\fR
removes layers which match pattern from look list
.TP
\fBlook remove all\fR
clears look list entirely
.TP
\fBlook \fIx y \fR?\fB-titled|-list|-raw\fR?
return list of information for all layers in look list at given point.
If \fB-titled\fR option is specified, each element in list is formatted
string. Otherwise it is two element list which first element - layer title,
and second - layer value. \fB-raw\fR option returns only values, without
layer title information. 

Length of this list not neccesary matches length of look list, becouse if
some layers are undefined in given point, they do not create list element.
.RE
.TP
\fIpathName \fBmapx \fIx\fR
.TP
\fIpathName \fBmapy\fR
Given screen coordinate in any form, acceptable by Tk, returns realword
coordinate.
.TP
\fIpathName \fBprint\fR ?option arg ...?
Wrapper around \fBpostscript\fR command. Uses default Fgis font mapping and
print system, also widget default orientation. By default, send output
to default Fgis printer using command, defined in fgis configuration file.

Following options are supported:
.RS
\fB-colormode\fI mode\fR
Same as \fBcolormode\fR option in canvas \fBpostscript\fR command.
.TP
.TP
\fB-file\fI filename\fR
Write postscript representation of planchet into given file, instead of
piping it to print command.
.TP
\fB-fontmap \fIvariable\fR
array used to map screen fonts to postscript fonts. See canvas \fBpostscript\fR
command for more information.
.TP
\fB-printer \fIprintername\fR
Overrides default printer, specified in fgis.rc file.
.RE
.TP
\fIpathName \fBruler\fI ?on|off?\fR
Controls scale ruler.
.TP
\fIpathName \fBscale\fR ?\fIdenominator\fR?
With no arguments returns current scale denominator. If \fIdenominator\fR
is given, adjust coordinate limits so that scale would be as specified and
center point of widget would have same realworld coordinates as before.

If any other arguments are specified, behaves as \fBcanvas\fR widget \fBscale\fR
command.

.TP
\fIpathName \fBscrx \fIx\fR
.TP
\fIpathName \fBscry \fIy\fR
Given realworld coordinate, returns screen coordinate in pixels.
.TP
\fIpathName \fBsetstatus\fR
Displays message if \fB\-statusline\fR helper widget, if defined, otherwise
does nothing. Can have one of two form:
.RS
.TP
\fBsetstatus\fI message\fR
displays message as specified
.TP
\fBsetstatus\fI x y\fR
Displays given coordinates. If no projection defined, they would be displayed
using Tcl \fBformat\fR command with value of \fB\-coordformat\fR option as
first argument. Otherwise they would be displayed using \fBformat\fR object
command of current projection.
.RE
.TP
\fIpathName \fBshift \fIdirection\fR
Changes current coordinate limits so that current view shifts in specified
\fIdirection\fR by share of corresponding widget size, specified by 
\fB-shiftfactor\fR option.
.TP
\fIpathName \fBshow \fIlayer \fR?\fB-base\fR|\fB-overlay\fR?
Displays specified layer. If neither \fB-base\fR nor \fB-overlay\fR is specifed,
shows layer as base if no base layer currently present and layer can be
displayed as base. Otherwise displays it as overlay.
.TP
\fIpathName \fBunzoom\fR
Pops last coordinate limits from zoom stack
.TP
\fIpathName \fBzoom\fR ?\fI x y\fR? x y\fR??
Initiates interactive zoom operation. If no coordinates are specified,
prompts user to pick both corners of rectangle to display. If one pair
is specified, prompts only for second pair. With two pairs just converts
values from canvas to realworld coordinates and performs \fBlimits\fR command
on them.
.CS
\fIpathName \fBzoom cancel\fR
.CE
can be used to abort interactive zoom operation currently in progress.
.CS
\fIpathName \fBzoom cancel\fR
.CE
can be used to abort interactive zoom operation currently in progress.
.SH SEE ALSO
.BR layer (n)
.SH BUGS
No care taken to do something useful if interactive zoom operation is
performed on two planchets simulateously.