'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/apps/bitmap-editor.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c)
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "bitmap-editor" n 1.0 tklib "Bitmap handling"
.BS
.SH NAME
bitmap-editor \- Editor for XBM images
.SH SYNOPSIS
\fBbitmap-editor\fR ?\fIxbmfile\fR?
.sp
.BE
.SH DESCRIPTION
.PP
The application described by this document, \fBbitmap-editor\fR, is
a simple editor for XBM based bitmap images.
Written by Keith Vetter the original code can be found at
\fIhttp://wiki.tcl.tk/6298\fR.
.SS "COMMAND LINE"
.TP
\fBbitmap-editor\fR ?\fIxbmfile\fR?
Invoked without argument the editor GUI will be opened and show a
standard bitmap to edit. Invoked with an argument it is expected to be
the path to a bitmap file in XBM format, and the contained bitmap is
shown.
.RS
.TP
path \fIxbmfile\fR (in/out)
This argument specifies the path to a bitmap file in XBM format, whose
contents is to shown and edited by the application.
.RE
.sp
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the application it describes, will undoubtedly
contain bugs and other problems.
Please report such in the category \fIbitmap\fR of the
\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either
application and/or documentation.
.SH KEYWORDS
bitmap, editor, image, pixel, xbm
.SH CATEGORY
Image processing
.SH COPYRIGHT
.nf
Copyright (c)

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/apps/bitmap-editor\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c)
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "bitmap-editor" n 1\&.0 tklib "Bitmap handling"
.BS
.SH NAME
bitmap-editor \- Editor for XBM images
.SH SYNOPSIS
\fBbitmap-editor\fR ?\fIxbmfile\fR?
.sp
.BE
.SH DESCRIPTION
.PP
The application described by this document, \fBbitmap-editor\fR, is
a simple editor for XBM based bitmap images\&.
Written by Keith Vetter the original code can be found at
\fIhttp://wiki\&.tcl\&.tk/6298\fR\&.
.SS "COMMAND LINE"
.TP
\fBbitmap-editor\fR ?\fIxbmfile\fR?
Invoked without argument the editor GUI will be opened and show a
standard bitmap to edit\&. Invoked with an argument it is expected to be
the path to a bitmap file in XBM format, and the contained bitmap is
shown\&.
.RS
.TP
path \fIxbmfile\fR (in/out)
This argument specifies the path to a bitmap file in XBM format, whose
contents is to shown and edited by the application\&.
.RE
.sp
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the application it describes, will undoubtedly
contain bugs and other problems\&.
Please report such in the category \fIbitmap\fR of the
\fITcllib SF Trackers\fR [http://sourceforge\&.net/tracker/?group_id=12883]\&.
Please also report any ideas for enhancements you may have for either
application and/or documentation\&.
.SH KEYWORDS
bitmap, editor, image, pixel, xbm
.SH CATEGORY
Image processing
.SH COPYRIGHT
.nf
Copyright (c)

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/apps/dia.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "dia" n 1.0 tklib "Documentation toolbox"
.BS
.SH NAME
dia \- Lightweight Diagram Processor
.SH SYNOPSIS
\fBdia\fR \fBshow\fR \fIinputfile\fR...
.sp
\fBdia\fR \fBconvert\fR \fB-o\fR \fIoutput\fR \fIformat\fR \fIinputfile\fR...
.sp
.BE
.SH DESCRIPTION
.PP
The application described by this document, \fBdia\fR, is a
lightweight processor for tklib diagram files
.PP
\fBdia\fR is based upon the package \fBdiagram\fR.
See it for examples and language reference.
.SS "USE CASES"
\fBdia\fR was written with the following two use cases in
mind.
.PP
.IP [1]
Processing and display of one or more diagram files.
.IP [2]
Batch conversion of one or more diagram files into raster image files.
.PP
.PP
.SS "COMMAND LINE"
.TP
\fBdia\fR \fBshow\fR \fIinputfile\fR...
This is the form for use case [1]. The application opens a gui
showing the list of input files to the left, allowing the user to
choose which of them to render to the canvas on the right.
.TP
\fBdia\fR \fBconvert\fR \fB-o\fR \fIoutput\fR \fIformat\fR \fIinputfile\fR...
This is the form for use case [2]. The application converts
the input files into raster image of the specified \fIformat\fR.
.RS
.TP
path \fIoutput\fR (in)
This argument specifies where to write the generated image. It can
be the path to a file or directory.
.sp
If the \fIoutput\fR does not exist then [file dirname $output]
has to exist and must be a writable directory.
.sp
In case of multiple input files the generated image will be written to
a file in the directory, and the name of that file will be derived
from the \fIinputfile\fR, and \fIformat\fR.
.sp
In case of a single input file the generated image will be written to
the file.
.TP
(handle) \fIformat\fR (in)
This argument specifies the image format to convert the diagrams into
when processing the input. The application recognizes all formats
supported by the \fBImg\fR package, i.e. for which it can load a
package \fBimg::\fBformat\fR\fR
.TP
path \fIinputfile\fR (in)
This argument specifies the path to the diagram file to process. It
has to exist, must be readable, and written in \fIdiagram\fR format.
.RE
.sp
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the application it describes, will undoubtedly
contain bugs and other problems.
Please report such in the category \fIdiagram\fR of the
\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either
application and/or documentation.
.SH KEYWORDS
canvas, conversion, diagram, vector
.SH CATEGORY
Documentation tools
.SH COPYRIGHT
.nf
Copyright (c) 2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/apps/dia\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2010 Andreas Kupries <andreas_kupries@users\&.sourceforge\&.net>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "dia" n 1\&.0 tklib "Documentation toolbox"
.BS
.SH NAME
dia \- Lightweight Diagram Processor
.SH SYNOPSIS
\fBdia\fR \fBshow\fR \fIinputfile\fR\&.\&.\&.
.sp
\fBdia\fR \fBconvert\fR \fB-o\fR \fIoutput\fR \fIformat\fR \fIinputfile\fR\&.\&.\&.
.sp
.BE
.SH DESCRIPTION
.PP
The application described by this document, \fBdia\fR, is a
lightweight processor for tklib diagram files
.PP
\fBdia\fR is based upon the package \fBdiagram\fR\&.
See it for examples and language reference\&.
.SS "USE CASES"
\fBdia\fR was written with the following two use cases in
mind\&.
.PP
.IP [1]
Processing and display of one or more diagram files\&.
.IP [2]
Batch conversion of one or more diagram files into raster image files\&.
.PP
.PP
.SS "COMMAND LINE"
.TP
\fBdia\fR \fBshow\fR \fIinputfile\fR\&.\&.\&.
This is the form for use case [1]\&. The application opens a gui
showing the list of input files to the left, allowing the user to
choose which of them to render to the canvas on the right\&.
.TP
\fBdia\fR \fBconvert\fR \fB-o\fR \fIoutput\fR \fIformat\fR \fIinputfile\fR\&.\&.\&.
This is the form for use case [2]\&. The application converts
the input files into raster image of the specified \fIformat\fR\&.
.RS
.TP
path \fIoutput\fR (in)
This argument specifies where to write the generated image\&. It can
be the path to a file or directory\&.
.sp
If the \fIoutput\fR does not exist then [file dirname $output]
has to exist and must be a writable directory\&.
.sp
In case of multiple input files the generated image will be written to
a file in the directory, and the name of that file will be derived
from the \fIinputfile\fR, and \fIformat\fR\&.
.sp
In case of a single input file the generated image will be written to
the file\&.
.TP
(handle) \fIformat\fR (in)
This argument specifies the image format to convert the diagrams into
when processing the input\&. The application recognizes all formats
supported by the \fBImg\fR package, i\&.e\&. for which it can load a
package \fBimg::\fBformat\fR\fR
.TP
path \fIinputfile\fR (in)
This argument specifies the path to the diagram file to process\&. It
has to exist, must be readable, and written in \fIdiagram\fR format\&.
.RE
.sp
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the application it describes, will undoubtedly
contain bugs and other problems\&.
Please report such in the category \fIdiagram\fR of the
\fITcllib SF Trackers\fR [http://sourceforge\&.net/tracker/?group_id=12883]\&.
Please also report any ideas for enhancements you may have for either
application and/or documentation\&.
.SH KEYWORDS
canvas, conversion, diagram, vector
.SH CATEGORY
Documentation tools
.SH COPYRIGHT
.nf
Copyright (c) 2010 Andreas Kupries <andreas_kupries@users\&.sourceforge\&.net>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/autoscroll/autoscroll.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "autoscroll" n 1.1 tklib "Automatic mapping of scrollbars"
.BS
.SH NAME
autoscroll \- Provides for a scrollbar to automatically mapped and unmapped as needed
.SH SYNOPSIS
package require \fBTcl \fR
.sp
package require \fBautoscroll  ?1.1?\fR
.sp
\fB::autoscroll::autoscroll\fR \fIscrollbar\fR
.sp
\fB::autoscroll::unautoscroll\fR \fIscrollbar\fR
.sp
\fB::autoscroll::wrap\fR
.sp
\fB::autoscroll::unwrap\fR
.sp
.BE
.SH DESCRIPTION
This package allows scrollbars to be mapped and
unmapped as needed depending on the size and
content of the scrollbars scrolled widget. The
scrollbar must be managed by either pack or grid,
other geometry managers are not supported.
.PP
When managed by pack, any geometry changes made in the
scrollbars parent between the time a scrollbar is
unmapped, and when it is mapped will be lost. It is
an error to destroy any of the scrollbars siblings while the
scrollbar is unmapped. When managed by grid, if anything
becomes gridded in the same row and column the scrollbar
occupied it will be replaced by the scrollbar when remapped.
.PP
This package may be used on any scrollbar-like widget
as long as it supports the \fBset\fR subcommand in the same
style as scrollbar. If the \fBset\fR subcommand is not used
then this package will have no effect.
.PP
.TP
\fB::autoscroll::autoscroll\fR \fIscrollbar\fR
Arranges for the already existing scrollbar \fBscrollbar\fR
to be mapped and unmapped as needed.
.TP
\fB::autoscroll::unautoscroll\fR \fIscrollbar\fR
Returns the named scrollbar to its original static state.
.TP
\fB::autoscroll::wrap\fR
Arranges for all scrollbars created after this command is run
to be automatically mapped and unmapped as needed.
.TP
\fB::autoscroll::unwrap\fR
Turns off the automatic autoscrolling of all new scrollbars.
Does not effect existing scrollbars
.PP
.CS


text .t -yscrollcommand ".scrolly set"
scrollbar .scrolly -orient v -command ".t yview"
pack .scrolly -side right -fill y
pack .t -side left -fill both -expand 1
::autoscroll::autoscroll .scrolly

.CE
.SH KEYWORDS
scroll, scrollbar

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/autoscroll/autoscroll\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "autoscroll" n 1\&.1 tklib "Automatic mapping of scrollbars"
.BS
.SH NAME
autoscroll \- Provides for a scrollbar to automatically mapped and unmapped as needed
.SH SYNOPSIS
package require \fBTcl \fR
.sp
package require \fBautoscroll  ?1\&.1?\fR
.sp
\fB::autoscroll::autoscroll\fR \fIscrollbar\fR
.sp
\fB::autoscroll::unautoscroll\fR \fIscrollbar\fR
.sp
\fB::autoscroll::wrap\fR
.sp
\fB::autoscroll::unwrap\fR
.sp
.BE
.SH DESCRIPTION
This package allows scrollbars to be mapped and
unmapped as needed depending on the size and
content of the scrollbars scrolled widget\&. The
scrollbar must be managed by either pack or grid,
other geometry managers are not supported\&.
.PP
When managed by pack, any geometry changes made in the
scrollbars parent between the time a scrollbar is
unmapped, and when it is mapped will be lost\&. It is
an error to destroy any of the scrollbars siblings while the
scrollbar is unmapped\&. When managed by grid, if anything
becomes gridded in the same row and column the scrollbar
occupied it will be replaced by the scrollbar when remapped\&.
.PP
This package may be used on any scrollbar-like widget
as long as it supports the \fBset\fR subcommand in the same
style as scrollbar\&. If the \fBset\fR subcommand is not used
then this package will have no effect\&.
.PP
.TP
\fB::autoscroll::autoscroll\fR \fIscrollbar\fR
Arranges for the already existing scrollbar \fBscrollbar\fR
to be mapped and unmapped as needed\&.
.TP
\fB::autoscroll::unautoscroll\fR \fIscrollbar\fR
Returns the named scrollbar to its original static state\&.
.TP
\fB::autoscroll::wrap\fR
Arranges for all scrollbars created after this command is run
to be automatically mapped and unmapped as needed\&.
.TP
\fB::autoscroll::unwrap\fR
Turns off the automatic autoscrolling of all new scrollbars\&.
Does not effect existing scrollbars
.PP
.CS


text \&.t -yscrollcommand "\&.scrolly set"
scrollbar \&.scrolly -orient v -command "\&.t yview"
pack \&.scrolly -side right -fill y
pack \&.t -side left -fill both -expand 1
::autoscroll::autoscroll \&.scrolly

.CE
.SH KEYWORDS
scroll, scrollbar

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_drag.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::drag" n 0.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::drag \- Manage the dragging of canvas items or item groups
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBcanvas::drag  ?0.1?\fR
.sp
\fB::canvas::drag\fR \fBon\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR \fIoption\fR...
.sp
\fB::canvas::drag\fR \fBoff\fR \fIcanvas\fR \fItagOrId\fR
.sp
\fB::canvas::drag\fR \fBitem\fR \fIcanvas\fR \fItagOrId\fR \fIoption\fR...
.sp
\fB::canvas::drag\fR \fBgroup\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR \fIoption\fR...
.sp
\fB{*}cmd\fR \fBstart\fR \fIcanvas\fR \fIitem\fR
.sp
\fB{*}cmd\fR \fBmove\fR \fIcanvas\fR \fIclientdata\fR \fIdx\fR \fIdy\fR
.sp
\fB{*}cmd\fR \fBdone\fR \fIcanvas\fR \fIclientdata\fR
.sp
.BE
.SH DESCRIPTION
This package provides utility commands to setup and rmeove dragging of
items or item groups on a canvas, hiding all complexity regarding
bindings from the user.
.SH API
.TP
\fB::canvas::drag\fR \fBon\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR \fIoption\fR...
This command initializes item dragging on the \fIcanvas\fR widget,
with the items used as drag handles identified by \fItagOrId\fR.
The command prefix \fIcmd\fR, invoked for drag start and movement, is
responsible for the initialization and actual execution of the drag
operation.
.sp
The signature of the command prefix is described later, in
section \fBDrag callback\fR.
.sp
Similarly, the accepted options and their values are described
in section \fBOptions\fR
.sp
The result of the command is the empty string.
.TP
\fB::canvas::drag\fR \fBoff\fR \fIcanvas\fR \fItagOrId\fR
This command removes any drag operation set on the items of canvas
\fIcanvas\fR identified by \fItagOrId\fR.
.sp
The result of the command is the empty string.
.TP
\fB::canvas::drag\fR \fBitem\fR \fIcanvas\fR \fItagOrId\fR \fIoption\fR...
This is a convenience command wrapped around method \fBon\fR (see above)
to drag single items of the \fIcanvas\fR widget, identified by \fItagOrId\fR.
.sp
It uses an internal standard callback for this.
.sp
The result of the command is the empty string.
.TP
\fB::canvas::drag\fR \fBgroup\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR \fIoption\fR...
This is a convenience command wrapped around method \fBon\fR (see above)
to drag single items of the \fIcanvas\fR widget, identified by \fItagOrId\fR.
.sp
It uses an internal standard callback for this. The callback
\fIcmd\fR specified has the same signature as the \fBDrag callback\fR,
except that
.RS
.IP [1]
The \fBmove\fR method is not invoked.
.IP [2]
The result of the \fBstart\fR method \fIhas to be\fR a
canvas tag refering to the whole group of items to move. In other words,
it must convert from drag handle (item id) to dragged groupt (tag).
.RE
.sp
The result of the command is the empty string.
.PP
.SS "DRAG CALLBACK"
The drag callback is a command prefix invoked in the following two
ways:
.TP
\fB{*}cmd\fR \fBstart\fR \fIcanvas\fR \fIitem\fR
This form is invoked when has initiated dragging using drag handle
identified by the canvas \fIitem\fR id.
The callback now has to perform anything necessary for its type of
drag operation.
.sp
The result of the command can be anything. It is stored by the
system as client information and passed unchanged to the movement
callback for its use. In this manner the drag callback is able to
maintain custom state from start to movement.
.TP
\fB{*}cmd\fR \fBmove\fR \fIcanvas\fR \fIclientdata\fR \fIdx\fR \fIdy\fR
This form is invoked when the mouse moved during a drag operation.
It is invoked with the client data from the start callback (or the
previous move callback) and the distances the mouse has traveled in
horizontal and vertical directions.
.sp
The result of the command can be anything. It is stored by the
system as client information and passed unchanged to the next movement
callback for its use. In this manner the drag callback is able to
maintain custom state from movement to movement.
.TP
\fB{*}cmd\fR \fBdone\fR \fIcanvas\fR \fIclientdata\fR
This form is invoked when the drag operation ends.
It is invoked with the client data from the last movement callback (or
start callback if there had been no motion).
.sp
The result of the command is ignored.
.PP
.SS OPTIONS
The commands to create drag operations (\fBon\fR, \fBitem\fR,
and \fBgroup\fR) all accept the following options to configure the
new drag.
.TP
\fB-event\fR \fIspec\fR
The value of this option specifies the mouse button used to initiate
the drag operation, and the keyboard modifier, if any. Examples of
specifications:
.sp
To initiate a drag operation by pressing mouse button 3 on a
drag handle, use:
.CS

 -event 3
.CE
.IP
This is the default as well, if the option is not specified.
.sp
To initiate a drag operation by pressing mouse button 2 on a
drag handle while holding down the Control key, use:
.CS

 -event Control-2
.CE
.PP
.SH KEYWORDS
canvas, dragging

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_drag\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::drag" n 0\&.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::drag \- Manage the dragging of canvas items or item groups
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBcanvas::drag  ?0\&.1?\fR
.sp
\fB::canvas::drag\fR \fBon\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR \fIoption\fR\&.\&.\&.
.sp
\fB::canvas::drag\fR \fBoff\fR \fIcanvas\fR \fItagOrId\fR
.sp
\fB::canvas::drag\fR \fBitem\fR \fIcanvas\fR \fItagOrId\fR \fIoption\fR\&.\&.\&.
.sp
\fB::canvas::drag\fR \fBgroup\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR \fIoption\fR\&.\&.\&.
.sp
\fB{*}cmd\fR \fBstart\fR \fIcanvas\fR \fIitem\fR
.sp
\fB{*}cmd\fR \fBmove\fR \fIcanvas\fR \fIclientdata\fR \fIdx\fR \fIdy\fR
.sp
\fB{*}cmd\fR \fBdone\fR \fIcanvas\fR \fIclientdata\fR
.sp
.BE
.SH DESCRIPTION
This package provides utility commands to setup and rmeove dragging of
items or item groups on a canvas, hiding all complexity regarding
bindings from the user\&.
.SH API
.TP
\fB::canvas::drag\fR \fBon\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR \fIoption\fR\&.\&.\&.
This command initializes item dragging on the \fIcanvas\fR widget,
with the items used as drag handles identified by \fItagOrId\fR\&.
The command prefix \fIcmd\fR, invoked for drag start and movement, is
responsible for the initialization and actual execution of the drag
operation\&.
.sp
The signature of the command prefix is described later, in
section \fBDrag callback\fR\&.
.sp
Similarly, the accepted options and their values are described
in section \fBOptions\fR
.sp
The result of the command is the empty string\&.
.TP
\fB::canvas::drag\fR \fBoff\fR \fIcanvas\fR \fItagOrId\fR
This command removes any drag operation set on the items of canvas
\fIcanvas\fR identified by \fItagOrId\fR\&.
.sp
The result of the command is the empty string\&.
.TP
\fB::canvas::drag\fR \fBitem\fR \fIcanvas\fR \fItagOrId\fR \fIoption\fR\&.\&.\&.
This is a convenience command wrapped around method \fBon\fR (see above)
to drag single items of the \fIcanvas\fR widget, identified by \fItagOrId\fR\&.
.sp
It uses an internal standard callback for this\&.
.sp
The result of the command is the empty string\&.
.TP
\fB::canvas::drag\fR \fBgroup\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR \fIoption\fR\&.\&.\&.
This is a convenience command wrapped around method \fBon\fR (see above)
to drag single items of the \fIcanvas\fR widget, identified by \fItagOrId\fR\&.
.sp
It uses an internal standard callback for this\&. The callback
\fIcmd\fR specified has the same signature as the \fBDrag callback\fR,
except that
.RS
.IP [1]
The \fBmove\fR method is not invoked\&.
.IP [2]
The result of the \fBstart\fR method \fIhas to be\fR a
canvas tag refering to the whole group of items to move\&. In other words,
it must convert from drag handle (item id) to dragged groupt (tag)\&.
.RE
.sp
The result of the command is the empty string\&.
.PP
.SS "DRAG CALLBACK"
The drag callback is a command prefix invoked in the following two
ways:
.TP
\fB{*}cmd\fR \fBstart\fR \fIcanvas\fR \fIitem\fR
This form is invoked when has initiated dragging using drag handle
identified by the canvas \fIitem\fR id\&.
The callback now has to perform anything necessary for its type of
drag operation\&.
.sp
The result of the command can be anything\&. It is stored by the
system as client information and passed unchanged to the movement
callback for its use\&. In this manner the drag callback is able to
maintain custom state from start to movement\&.
.TP
\fB{*}cmd\fR \fBmove\fR \fIcanvas\fR \fIclientdata\fR \fIdx\fR \fIdy\fR
This form is invoked when the mouse moved during a drag operation\&.
It is invoked with the client data from the start callback (or the
previous move callback) and the distances the mouse has traveled in
horizontal and vertical directions\&.
.sp
The result of the command can be anything\&. It is stored by the
system as client information and passed unchanged to the next movement
callback for its use\&. In this manner the drag callback is able to
maintain custom state from movement to movement\&.
.TP
\fB{*}cmd\fR \fBdone\fR \fIcanvas\fR \fIclientdata\fR
This form is invoked when the drag operation ends\&.
It is invoked with the client data from the last movement callback (or
start callback if there had been no motion)\&.
.sp
The result of the command is ignored\&.
.PP
.SS OPTIONS
The commands to create drag operations (\fBon\fR, \fBitem\fR,
and \fBgroup\fR) all accept the following options to configure the
new drag\&.
.TP
\fB-event\fR \fIspec\fR
The value of this option specifies the mouse button used to initiate
the drag operation, and the keyboard modifier, if any\&. Examples of
specifications:
.sp
To initiate a drag operation by pressing mouse button 3 on a
drag handle, use:
.CS

 -event 3
.CE
.IP
This is the default as well, if the option is not specified\&.
.sp
To initiate a drag operation by pressing mouse button 2 on a
drag handle while holding down the Control key, use:
.CS

 -event Control-2
.CE
.PP
.SH KEYWORDS
canvas, dragging

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_epoints.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::edit::points" n 0.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::edit::points \- Editing a cloud of points on a canvas
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBcanvas::edit::points  ?0.1?\fR
.sp
\fB::canvas::edit\fR \fBpoints\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR...
.sp
\fBobjectName\fR \fBdestroy\fR
.sp
\fBobjectName\fR \fBenable\fR
.sp
\fBobjectName\fR \fBdisable\fR
.sp
................................................................................
\fBdataCmd\fR \fBmove delta\fR \fIeditorObj\fR \fIid\fR \fIx\fR \fIy\fR \fIdx\fR \fIdy\fR
.sp
\fBdataCmd\fR \fBmove done\fR \fIeditorObj\fR \fIid\fR
.sp
.BE
.SH DESCRIPTION
This package provides a class whose instances handle editing a cloud
of point markers on a canvas. Instances can be configured with regard
to the visual appearance of markers (regular, and highlighted). Note
that instances do not store the edited points themselves, but delegate
this to a configurable object.
.SH "CLASS API"
.TP
\fB::canvas::edit\fR \fBpoints\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR...
This, the class command, creates and configures a new instance of a
point cloud editor, named \fIobjectName\fR. The instance will be
connected to the specified \fIcanvas\fR widget.
.sp
The result of the command is the fully qualified name of the
instance command.
.sp
The options accepted here, and their values, are explained in
the section \fBOptions\fR.
.PP
.SH "INSTANCE API"
Instances of the point cloud editors provide the following API:
.TP
\fBobjectName\fR \fBdestroy\fR
This method destroys the point cloud editor and releases all its
internal resources.
.sp
Note that this operation does not destroy the items of the
point markers the editor managed on the attached canvas, nor the
canvas itself.
.sp
The result of the method is an empty string.
.TP
\fBobjectName\fR \fBenable\fR
This method activates editing of the point cloud on the canvas. This
is the default after instance creation. A call is ignored if the
editor is already active.
.sp
The result of the method is an empty string.
.sp
The complementary method is \fBdisable\fR. The interogatory
method for the current state is \fBactive\fR.
.TP
\fBobjectName\fR \fBdisable\fR
This method disables editing of the point cloud on the canvas. A call
is ignored if the editor is already disabled.
.sp
The result of the method is an empty string.
.sp
The complementary method is \fBenable\fR. The interogatory
method for the current state is \fBactive\fR.
.TP
\fBobjectName\fR \fBactive\fR
This method queries the editor state.
.sp
The result of the method is a boolean value, \fBtrue\fR if
the editor is active, and \fBfalse\fR otherwise, i.e. disabled.
.sp
The methods to change the state are \fBenable\fR and
\fBdisable\fR.
.TP
\fBobjectName\fR \fBadd\fR \fIx\fR \fIy\fR
This method programmatically creates a point at the specified location.
.sp
The result of the method is an empty string.
.sp
Note that this method goes through the whole set of callbacks
invoked when the user interactively creates a point, i.e.
\fB-create-cmd\fR, and, more importantly, \fB-data-cmd\fR.
.sp
This is the method through which to load pre-existing points
into an editor instance.
.TP
\fBobjectName\fR \fBclear\fR
This method programmatically removes all points from the editor.
.sp
The result of the method is an empty string.
.sp
Note that this method goes through the same callback invoked
when the user interactively removes a point, i.e. \fB-data-cmd\fR.
.PP
.SH OPTIONS
The class command accepts the following options
.TP
\fB-tag\fR \fIstring\fR
The value of this option is the name of the canvas tag with which to
identify all items of all points managed by the editor.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to \fBPOINT\fR
.TP
\fB-create-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to create a new point.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to a command which will create a
black-bordered blue circle of radius 3 centered on the location of the
new point.
.sp
The signature of this command prefix is
.RS
.TP
\fBcreateCmd\fR \fIcanvas\fR \fIx\fR \fIy\fR
The result of the command prefix \fImust\fR be a list of the canvas
items it created to represent the marker. Note here that the visual
representation of a "point" may consist of multiple canvas items in an
arbitrary shape.
.sp
The returned list of items is allowed to be empty, and such is
taken as signal that the callback vetoed the creation of the point.
.RE
.TP
\fB-highlight-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to (un)highlight a point.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to a command which will re-color
the item to highlight in red (and restores the color for
unhighlighting).
.sp
The two signatures of this command prefix are
.RS
.TP
\fBhighlightCmd\fR \fBon\fR \fIcanvas\fR \fIitem\fR
.sp
This method of the command prefix has to perform whatever is
needed to highlight the point the \fIitem\fR is a part of (remember
the note above about points allowed to be constructed from multiple
canvas items).
.sp
The result of the command can be anything and will be passed as
is as argument \fIstate\fR to the \fBoff\fR method.
.TP
\fBhighlightCmd\fR \fBoff\fR \fIcanvas\fR \fIstate\fR
.sp
This method is invoked to unhighlight a point described by the
\fIstate\fR, which is the unchanged result of the \fBon\fR method
of the command prefix. The result of this method is ignored.
.sp
Note any interaction between dragging and highlighting of
points is handled within the editor, and that the callback bears no
responsibility for doing such.
.RE
.TP
\fB-data-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when a point was edited in some way. This is how the editor delegates
the actual storage of point information to an outside object.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to an empty string and is ignored
by the editor, i.e. not invoked.
.sp
The signatures of this command prefix are
.RS
.TP
\fBdataCmd\fR \fBadd\fR \fIeditorObj\fR \fIid\fR \fIx\fR \fIy\fR
This callback is invoked when a new point was added to the instance,
either interactively, or programmatically.
See instance method \fBadd\fR for the latter.
.sp
The \fIid\fR identifies the point within the editor and will be
used by the two other callbacks to specify which point to modify.
.sp
The last two arguments \fIx\fR and \fIy\fR specify the location
of the new point in canvas coordinates.
.sp
The result of this method is ignored.
.TP
\fBdataCmd\fR \fBremove\fR \fIeditorObj\fR \fIid\fR
This callback is invoked when a point removed from the editor
instance.
.sp
The \fIid\fR identifies the removed point within the editor.
.sp
The result of this method is ignored.
.TP
\fBdataCmd\fR \fBmove start\fR \fIeditorObj\fR \fIid\fR
This callback is invoked when the movement of a point in the editor
instance has started.
.sp
The \fIid\fR identifies the point within the editor about to be
moved.
.sp
The result of this method is ignored.
.TP
\fBdataCmd\fR \fBmove delta\fR \fIeditorObj\fR \fIid\fR \fIx\fR \fIy\fR \fIdx\fR \fIdy\fR
This callback is invoked when the point moved in the editor instance.
.sp
The \fIid\fR identifies the moved point within the editor, and
the remaining arguments \fIx\fR, \fIy\fR, \fIdx\fR, and \fIdy\fR
provide the new absolute location of the point, and full delta to the
original location.
.sp
At the time of the calls the system is \fInot\fR committed to
the move yet. Only after method \fBmove done\fR was invoked and
has accepted or rejected the last position will the editor update its
internal data structures, either committing to the new location, or
rolling the move back to the original one.
.sp
Given this the location data provided here should be saved only
in temporary storage until then.
.sp
The result of this method is ignored.
.TP
\fBdataCmd\fR \fBmove done\fR \fIeditorObj\fR \fIid\fR
This callback is invoked when the movement of a point in the editor
instance is complete.
.sp
The \fIid\fR identifies the moved point within the editor.
.sp
The result of this method must be a boolean value. If the
method returns \fBfalse\fR the move is vetoed and rollbed back.
.RE
.PP
.SH KEYWORDS
canvas, editing, point cloud, points

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_epoints\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::edit::points" n 0\&.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::edit::points \- Editing a cloud of points on a canvas
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBcanvas::edit::points  ?0\&.1?\fR
.sp
\fB::canvas::edit\fR \fBpoints\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR\&.\&.\&.
.sp
\fBobjectName\fR \fBdestroy\fR
.sp
\fBobjectName\fR \fBenable\fR
.sp
\fBobjectName\fR \fBdisable\fR
.sp
................................................................................
\fBdataCmd\fR \fBmove delta\fR \fIeditorObj\fR \fIid\fR \fIx\fR \fIy\fR \fIdx\fR \fIdy\fR
.sp
\fBdataCmd\fR \fBmove done\fR \fIeditorObj\fR \fIid\fR
.sp
.BE
.SH DESCRIPTION
This package provides a class whose instances handle editing a cloud
of point markers on a canvas\&. Instances can be configured with regard
to the visual appearance of markers (regular, and highlighted)\&. Note
that instances do not store the edited points themselves, but delegate
this to a configurable object\&.
.SH "CLASS API"
.TP
\fB::canvas::edit\fR \fBpoints\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR\&.\&.\&.
This, the class command, creates and configures a new instance of a
point cloud editor, named \fIobjectName\fR\&. The instance will be
connected to the specified \fIcanvas\fR widget\&.
.sp
The result of the command is the fully qualified name of the
instance command\&.
.sp
The options accepted here, and their values, are explained in
the section \fBOptions\fR\&.
.PP
.SH "INSTANCE API"
Instances of the point cloud editors provide the following API:
.TP
\fBobjectName\fR \fBdestroy\fR
This method destroys the point cloud editor and releases all its
internal resources\&.
.sp
Note that this operation does not destroy the items of the
point markers the editor managed on the attached canvas, nor the
canvas itself\&.
.sp
The result of the method is an empty string\&.
.TP
\fBobjectName\fR \fBenable\fR
This method activates editing of the point cloud on the canvas\&. This
is the default after instance creation\&. A call is ignored if the
editor is already active\&.
.sp
The result of the method is an empty string\&.
.sp
The complementary method is \fBdisable\fR\&. The interogatory
method for the current state is \fBactive\fR\&.
.TP
\fBobjectName\fR \fBdisable\fR
This method disables editing of the point cloud on the canvas\&. A call
is ignored if the editor is already disabled\&.
.sp
The result of the method is an empty string\&.
.sp
The complementary method is \fBenable\fR\&. The interogatory
method for the current state is \fBactive\fR\&.
.TP
\fBobjectName\fR \fBactive\fR
This method queries the editor state\&.
.sp
The result of the method is a boolean value, \fBtrue\fR if
the editor is active, and \fBfalse\fR otherwise, i\&.e\&. disabled\&.
.sp
The methods to change the state are \fBenable\fR and
\fBdisable\fR\&.
.TP
\fBobjectName\fR \fBadd\fR \fIx\fR \fIy\fR
This method programmatically creates a point at the specified location\&.
.sp
The result of the method is an empty string\&.
.sp
Note that this method goes through the whole set of callbacks
invoked when the user interactively creates a point, i\&.e\&.
\fB-create-cmd\fR, and, more importantly, \fB-data-cmd\fR\&.
.sp
This is the method through which to load pre-existing points
into an editor instance\&.
.TP
\fBobjectName\fR \fBclear\fR
This method programmatically removes all points from the editor\&.
.sp
The result of the method is an empty string\&.
.sp
Note that this method goes through the same callback invoked
when the user interactively removes a point, i\&.e\&. \fB-data-cmd\fR\&.
.PP
.SH OPTIONS
The class command accepts the following options
.TP
\fB-tag\fR \fIstring\fR
The value of this option is the name of the canvas tag with which to
identify all items of all points managed by the editor\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to \fBPOINT\fR
.TP
\fB-create-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to create a new point\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to a command which will create a
black-bordered blue circle of radius 3 centered on the location of the
new point\&.
.sp
The signature of this command prefix is
.RS
.TP
\fBcreateCmd\fR \fIcanvas\fR \fIx\fR \fIy\fR
The result of the command prefix \fImust\fR be a list of the canvas
items it created to represent the marker\&. Note here that the visual
representation of a "point" may consist of multiple canvas items in an
arbitrary shape\&.
.sp
The returned list of items is allowed to be empty, and such is
taken as signal that the callback vetoed the creation of the point\&.
.RE
.TP
\fB-highlight-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to (un)highlight a point\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to a command which will re-color
the item to highlight in red (and restores the color for
unhighlighting)\&.
.sp
The two signatures of this command prefix are
.RS
.TP
\fBhighlightCmd\fR \fBon\fR \fIcanvas\fR \fIitem\fR
.sp
This method of the command prefix has to perform whatever is
needed to highlight the point the \fIitem\fR is a part of (remember
the note above about points allowed to be constructed from multiple
canvas items)\&.
.sp
The result of the command can be anything and will be passed as
is as argument \fIstate\fR to the \fBoff\fR method\&.
.TP
\fBhighlightCmd\fR \fBoff\fR \fIcanvas\fR \fIstate\fR
.sp
This method is invoked to unhighlight a point described by the
\fIstate\fR, which is the unchanged result of the \fBon\fR method
of the command prefix\&. The result of this method is ignored\&.
.sp
Note any interaction between dragging and highlighting of
points is handled within the editor, and that the callback bears no
responsibility for doing such\&.
.RE
.TP
\fB-data-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when a point was edited in some way\&. This is how the editor delegates
the actual storage of point information to an outside object\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to an empty string and is ignored
by the editor, i\&.e\&. not invoked\&.
.sp
The signatures of this command prefix are
.RS
.TP
\fBdataCmd\fR \fBadd\fR \fIeditorObj\fR \fIid\fR \fIx\fR \fIy\fR
This callback is invoked when a new point was added to the instance,
either interactively, or programmatically\&.
See instance method \fBadd\fR for the latter\&.
.sp
The \fIid\fR identifies the point within the editor and will be
used by the two other callbacks to specify which point to modify\&.
.sp
The last two arguments \fIx\fR and \fIy\fR specify the location
of the new point in canvas coordinates\&.
.sp
The result of this method is ignored\&.
.TP
\fBdataCmd\fR \fBremove\fR \fIeditorObj\fR \fIid\fR
This callback is invoked when a point removed from the editor
instance\&.
.sp
The \fIid\fR identifies the removed point within the editor\&.
.sp
The result of this method is ignored\&.
.TP
\fBdataCmd\fR \fBmove start\fR \fIeditorObj\fR \fIid\fR
This callback is invoked when the movement of a point in the editor
instance has started\&.
.sp
The \fIid\fR identifies the point within the editor about to be
moved\&.
.sp
The result of this method is ignored\&.
.TP
\fBdataCmd\fR \fBmove delta\fR \fIeditorObj\fR \fIid\fR \fIx\fR \fIy\fR \fIdx\fR \fIdy\fR
This callback is invoked when the point moved in the editor instance\&.
.sp
The \fIid\fR identifies the moved point within the editor, and
the remaining arguments \fIx\fR, \fIy\fR, \fIdx\fR, and \fIdy\fR
provide the new absolute location of the point, and full delta to the
original location\&.
.sp
At the time of the calls the system is \fInot\fR committed to
the move yet\&. Only after method \fBmove done\fR was invoked and
has accepted or rejected the last position will the editor update its
internal data structures, either committing to the new location, or
rolling the move back to the original one\&.
.sp
Given this the location data provided here should be saved only
in temporary storage until then\&.
.sp
The result of this method is ignored\&.
.TP
\fBdataCmd\fR \fBmove done\fR \fIeditorObj\fR \fIid\fR
This callback is invoked when the movement of a point in the editor
instance is complete\&.
.sp
The \fIid\fR identifies the moved point within the editor\&.
.sp
The result of this method must be a boolean value\&. If the
method returns \fBfalse\fR the move is vetoed and rollbed back\&.
.RE
.PP
.SH KEYWORDS
canvas, editing, point cloud, points

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_epolyline.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::edit::polyline" n 0.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::edit::polyline \- Editing a polyline on a canvas
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBcanvas::edit::points  ?0.1?\fR
.sp
package require \fBcanvas::edit::polyline  ?0.1?\fR
.sp
\fB::canvas::edit\fR \fBpolyline\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR...
.sp
\fBobjectName\fR \fBdestroy\fR
.sp
\fBobjectName\fR \fBenable\fR
.sp
\fBobjectName\fR \fBdisable\fR
.sp
................................................................................
\fBhighlightCmd\fR \fBoff\fR \fIcanvas\fR \fIstate\fR
.sp
\fBdataCmd\fR \fIeditorObj\fR \fIcoordinates\fR
.sp
.BE
.SH DESCRIPTION
This package provides a class whose instances handle editing a single
poly-line on a canvas. Instances can be configured with regard to the
visual appearance (regular, and highlighted) of the markers denoting
the line's vertices. Note that instances do not store the edited
polyline themselves, but delegate this to a configurable object.
.SH "CLASS API"
.TP
\fB::canvas::edit\fR \fBpolyline\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR...
This, the class command, creates and configures a new instance of a
polyline editor, named \fIobjectName\fR. The instance will be
connected to the specified \fIcanvas\fR widget.
.sp
The result of the command is the fully qualified name of the
instance command.
.sp
The options accepted here, and their values, are explained in
the section \fBOptions\fR.
.PP
.SH "INSTANCE API"
Instances of the polyline editors provide the following API:
.TP
\fBobjectName\fR \fBdestroy\fR
This method destroys the polyline editor and releases all its
internal resources.
.sp
Note that this operation does not destroy the items the editor
managed on the attached canvas, nor the canvas itself.
.sp
The result of the method is an empty string.
.TP
\fBobjectName\fR \fBenable\fR
This method activates editing of the polyline on the canvas. This
is the default after instance creation. A call is ignored if the
editor is already active.
.sp
The result of the method is an empty string.
.sp
The complementary method is \fBdisable\fR. The interogatory
method for the current state is \fBactive\fR.
.TP
\fBobjectName\fR \fBdisable\fR
This method disables editing of the polyline on the canvas. A call
is ignored if the editor is already disabled.
.sp
The result of the method is an empty string.
.sp
The complementary method is \fBenable\fR. The interogatory
method for the current state is \fBactive\fR.
.TP
\fBobjectName\fR \fBactive\fR
This method queries the editor state.
.sp
The result of the method is a boolean value, \fBtrue\fR if
the editor is active, and \fBfalse\fR otherwise, i.e. disabled.
.sp
The methods to change the state are \fBenable\fR and
\fBdisable\fR.
.TP
\fBobjectName\fR \fBadd\fR \fIx\fR \fIy\fR
This method programmatically adds a vertex at the specified location to the line.
.sp
The result of the method is an empty string.
.sp
Note that this method goes through the whole set of callbacks
invoked when the user interactively creates a vertex, i.e.
\fB-create-cmd\fR, and, more importantly, \fB-data-cmd\fR.
.sp
One important difference however. The new vertex is always added
at the end of the line, whereas interactive creation uses heuristics
to splice it into the line at a suitable location.
.sp
This is the method through which to load the vertices of a
pre-existing line into an editor instance.
.TP
\fBobjectName\fR \fBclear\fR
This method programmatically removes all vertices from the editor,
essentially removing the whole line.
.sp
The result of the method is an empty string.
.sp
Note that this method goes through the same callbacks invoked
when the user interactively removes a vertex, i.e. \fB-data-cmd\fR.
.PP
.SH OPTIONS
The class command accepts the following options
.TP
\fB-tag\fR \fIstring\fR
The value of this option is the name of the canvas tag with which to
identify all items of all vertices managed by the editor.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to \fBPOLYLINE\fR
.TP
\fB-create-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to create a new vertex.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to a command which will create a
black-bordered blue circle of radius 3 centered on the location of the
new point.
.sp
The signature of this command prefix is
.RS
.TP
\fBcreateCmd\fR \fIcanvas\fR \fIx\fR \fIy\fR
The result of the command prefix \fImust\fR be a list of the canvas
items it created to represent the marker. Note here that the visual
representation of a "vertex" may consist of multiple canvas items in
an arbitrary shape.
.sp
The returned list of items is allowed to be empty, and such is
taken as signal that the callback vetoed the creation of the vertex.
.RE
.TP
\fB-highlight-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to (un)highlight a vertex.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to a command which will re-color
the item to highlight in red (and restores the color for
unhighlighting).
.sp
The two signatures of this command prefix are
.RS
.TP
\fBhighlightCmd\fR \fBon\fR \fIcanvas\fR \fIitem\fR
.sp
This method of the command prefix has to perform whatever is
needed to highlight the vertex the \fIitem\fR is a part of (remember
the note above about points allowed to be constructed from multiple
canvas items).
.sp
The result of the command can be anything and will be passed as
is as argument \fIstate\fR to the \fBoff\fR method.
.TP
\fBhighlightCmd\fR \fBoff\fR \fIcanvas\fR \fIstate\fR
.sp
This method is invoked to unhighlight a vertex described by the
\fIstate\fR, which is the unchanged result of the \fBon\fR method
of the command prefix. The result of this method is ignored.
.sp
Note any interaction between dragging and highlighting of
vertices is handled within the editor, and that the callback bears no
responsibility for doing such.
.RE
.TP
\fB-data-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when the line was edited in some way (vertex added, removed,
moved). This is how the editor delegates the actual storage of the
line information to an outside object.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to an empty string and is ignored
by the editor, i.e. not invoked.
.sp
The signature of this command prefix is
.RS
.TP
\fBdataCmd\fR \fIeditorObj\fR \fIcoordinates\fR
This callback is invoked when the line was changed either interactively,
or programmatically.
See instance method \fBadd\fR for the latter.
.sp
The \fIeditorObj\fR identifies the instance invoking the
callback, whereas \fIcoordinates\fR is a list of vertex locations,
with each location a pair of x- and y-coordinates.
.sp
The result of this method is ignored.
.RE
.PP
.SH KEYWORDS
canvas, editing, polyline

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_epolyline\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::edit::polyline" n 0\&.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::edit::polyline \- Editing a polyline on a canvas
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBcanvas::edit::points  ?0\&.1?\fR
.sp
package require \fBcanvas::edit::polyline  ?0\&.1?\fR
.sp
\fB::canvas::edit\fR \fBpolyline\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR\&.\&.\&.
.sp
\fBobjectName\fR \fBdestroy\fR
.sp
\fBobjectName\fR \fBenable\fR
.sp
\fBobjectName\fR \fBdisable\fR
.sp
................................................................................
\fBhighlightCmd\fR \fBoff\fR \fIcanvas\fR \fIstate\fR
.sp
\fBdataCmd\fR \fIeditorObj\fR \fIcoordinates\fR
.sp
.BE
.SH DESCRIPTION
This package provides a class whose instances handle editing a single
poly-line on a canvas\&. Instances can be configured with regard to the
visual appearance (regular, and highlighted) of the markers denoting
the line's vertices\&. Note that instances do not store the edited
polyline themselves, but delegate this to a configurable object\&.
.SH "CLASS API"
.TP
\fB::canvas::edit\fR \fBpolyline\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR\&.\&.\&.
This, the class command, creates and configures a new instance of a
polyline editor, named \fIobjectName\fR\&. The instance will be
connected to the specified \fIcanvas\fR widget\&.
.sp
The result of the command is the fully qualified name of the
instance command\&.
.sp
The options accepted here, and their values, are explained in
the section \fBOptions\fR\&.
.PP
.SH "INSTANCE API"
Instances of the polyline editors provide the following API:
.TP
\fBobjectName\fR \fBdestroy\fR
This method destroys the polyline editor and releases all its
internal resources\&.
.sp
Note that this operation does not destroy the items the editor
managed on the attached canvas, nor the canvas itself\&.
.sp
The result of the method is an empty string\&.
.TP
\fBobjectName\fR \fBenable\fR
This method activates editing of the polyline on the canvas\&. This
is the default after instance creation\&. A call is ignored if the
editor is already active\&.
.sp
The result of the method is an empty string\&.
.sp
The complementary method is \fBdisable\fR\&. The interogatory
method for the current state is \fBactive\fR\&.
.TP
\fBobjectName\fR \fBdisable\fR
This method disables editing of the polyline on the canvas\&. A call
is ignored if the editor is already disabled\&.
.sp
The result of the method is an empty string\&.
.sp
The complementary method is \fBenable\fR\&. The interogatory
method for the current state is \fBactive\fR\&.
.TP
\fBobjectName\fR \fBactive\fR
This method queries the editor state\&.
.sp
The result of the method is a boolean value, \fBtrue\fR if
the editor is active, and \fBfalse\fR otherwise, i\&.e\&. disabled\&.
.sp
The methods to change the state are \fBenable\fR and
\fBdisable\fR\&.
.TP
\fBobjectName\fR \fBadd\fR \fIx\fR \fIy\fR
This method programmatically adds a vertex at the specified location to the line\&.
.sp
The result of the method is an empty string\&.
.sp
Note that this method goes through the whole set of callbacks
invoked when the user interactively creates a vertex, i\&.e\&.
\fB-create-cmd\fR, and, more importantly, \fB-data-cmd\fR\&.
.sp
One important difference however\&. The new vertex is always added
at the end of the line, whereas interactive creation uses heuristics
to splice it into the line at a suitable location\&.
.sp
This is the method through which to load the vertices of a
pre-existing line into an editor instance\&.
.TP
\fBobjectName\fR \fBclear\fR
This method programmatically removes all vertices from the editor,
essentially removing the whole line\&.
.sp
The result of the method is an empty string\&.
.sp
Note that this method goes through the same callbacks invoked
when the user interactively removes a vertex, i\&.e\&. \fB-data-cmd\fR\&.
.PP
.SH OPTIONS
The class command accepts the following options
.TP
\fB-tag\fR \fIstring\fR
The value of this option is the name of the canvas tag with which to
identify all items of all vertices managed by the editor\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to \fBPOLYLINE\fR
.TP
\fB-create-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to create a new vertex\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to a command which will create a
black-bordered blue circle of radius 3 centered on the location of the
new point\&.
.sp
The signature of this command prefix is
.RS
.TP
\fBcreateCmd\fR \fIcanvas\fR \fIx\fR \fIy\fR
The result of the command prefix \fImust\fR be a list of the canvas
items it created to represent the marker\&. Note here that the visual
representation of a "vertex" may consist of multiple canvas items in
an arbitrary shape\&.
.sp
The returned list of items is allowed to be empty, and such is
taken as signal that the callback vetoed the creation of the vertex\&.
.RE
.TP
\fB-highlight-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to (un)highlight a vertex\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to a command which will re-color
the item to highlight in red (and restores the color for
unhighlighting)\&.
.sp
The two signatures of this command prefix are
.RS
.TP
\fBhighlightCmd\fR \fBon\fR \fIcanvas\fR \fIitem\fR
.sp
This method of the command prefix has to perform whatever is
needed to highlight the vertex the \fIitem\fR is a part of (remember
the note above about points allowed to be constructed from multiple
canvas items)\&.
.sp
The result of the command can be anything and will be passed as
is as argument \fIstate\fR to the \fBoff\fR method\&.
.TP
\fBhighlightCmd\fR \fBoff\fR \fIcanvas\fR \fIstate\fR
.sp
This method is invoked to unhighlight a vertex described by the
\fIstate\fR, which is the unchanged result of the \fBon\fR method
of the command prefix\&. The result of this method is ignored\&.
.sp
Note any interaction between dragging and highlighting of
vertices is handled within the editor, and that the callback bears no
responsibility for doing such\&.
.RE
.TP
\fB-data-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when the line was edited in some way (vertex added, removed,
moved)\&. This is how the editor delegates the actual storage of the
line information to an outside object\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to an empty string and is ignored
by the editor, i\&.e\&. not invoked\&.
.sp
The signature of this command prefix is
.RS
.TP
\fBdataCmd\fR \fIeditorObj\fR \fIcoordinates\fR
This callback is invoked when the line was changed either interactively,
or programmatically\&.
See instance method \fBadd\fR for the latter\&.
.sp
The \fIeditorObj\fR identifies the instance invoking the
callback, whereas \fIcoordinates\fR is a list of vertex locations,
with each location a pair of x- and y-coordinates\&.
.sp
The result of this method is ignored\&.
.RE
.PP
.SH KEYWORDS
canvas, editing, polyline

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_equad.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::edit::quadrilateral" n 0.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::edit::quadrilateral \- Editing a quadrilateral on a canvas
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBcanvas::edit::points  ?0.1?\fR
.sp
package require \fBcanvas::edit::quadrilateral  ?0.1?\fR
.sp
\fB::canvas::edit\fR \fBquadrilateral\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR...
.sp
\fBobjectName\fR \fBdestroy\fR
.sp
\fBobjectName\fR \fBenable\fR
.sp
\fBobjectName\fR \fBdisable\fR
.sp
................................................................................
\fBhighlightCmd\fR \fBoff\fR \fIcanvas\fR \fIstate\fR
.sp
\fBdataCmd\fR \fIeditorObj\fR \fIcoordinates\fR
.sp
.BE
.SH DESCRIPTION
This package provides a class whose instances handle the editing of a
quadrilateral on a canvas. Instances can be configured with regard to
the visual appearance (regular, and highlighted) of vertex
markers. Note that instances do not store the edited quadrilateral
themselves, but delegate this to a configurable object.
.SH "CLASS API"
.TP
\fB::canvas::edit\fR \fBquadrilateral\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR...
This, the class command, creates and configures a new instance of a
quadrilateral editor, named \fIobjectName\fR. The instance will be
connected to the specified \fIcanvas\fR widget.
.sp
The result of the command is the fully qualified name of the
instance command.
.sp
The options accepted here, and their values, are explained in
the section \fBOptions\fR.
.PP
.SH "INSTANCE API"
Instances of the quadrilateral editors provide the following API:
.TP
\fBobjectName\fR \fBdestroy\fR
This method destroys the quadrilateral editor and releases all its
internal resources.
.sp
Note that this operation does not destroy the items the editor
managed on the attached canvas, nor the canvas itself.
.sp
The result of the method is an empty string.
.TP
\fBobjectName\fR \fBenable\fR
This method activates editing of the quadrilateral on the canvas. This
is the default after instance creation. A call is ignored if the
editor is already active.
.sp
The result of the method is an empty string.
.sp
The complementary method is \fBdisable\fR. The interogatory
method for the current state is \fBactive\fR.
.TP
\fBobjectName\fR \fBdisable\fR
This method disables editing of the quadrilateral on the canvas. A call
is ignored if the editor is already disabled.
.sp
The result of the method is an empty string.
.sp
The complementary method is \fBenable\fR. The interogatory
method for the current state is \fBactive\fR.
.TP
\fBobjectName\fR \fBactive\fR
This method queries the editor state.
.sp
The result of the method is a boolean value, \fBtrue\fR if
the editor is active, and \fBfalse\fR otherwise, i.e. disabled.
.sp
The methods to change the state are \fBenable\fR and
\fBdisable\fR.
.TP
\fBobjectName\fR \fBadd\fR \fIx\fR \fIy\fR
This method programmatically adds a vertex at the specified location
to the quadrilateral.
.sp
The result of the method is an empty string.
.sp
Note that this method goes through the whole set of callbacks
invoked when the user interactively creates a vertex, i.e.
\fB-create-cmd\fR, and, more importantly, \fB-data-cmd\fR.
.sp
This is the method through which to load the vertices of a
pre-existing quadrilateral into an editor instance.
.sp
Note that at most 4 vertices can be specified, and at least 4
must be specified for the quadrilateral to be complete.
.TP
\fBobjectName\fR \fBclear\fR
This method programmatically unset the quadrilateral in the editor.
.sp
The result of the method is an empty string.
.sp
Note that this method goes through the same callback invoked
when the user interactively removes a vertex, i.e. \fB-data-cmd\fR.
.PP
.SH OPTIONS
The class command accepts the following options
.TP
\fB-convex\fR \fIboolean\fR
The value of this option is a boolean flag. When the flag is set the
editor will accept only convex quadrilaterals and reject all
operations which would result in a violation of convexity.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to \fBfalse\fR, i.e. acceptance
of any quadrilateral.
.TP
\fB-tag\fR \fIstring\fR
The value of this option is the name of the canvas tag with which to
identify all items of all quadrilateral managed by the editor.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to \fBQUADRILATERAL\fR
.TP
\fB-create-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to create a new vertex.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to a command which will create a
black-bordered blue circle of radius 3 centered on the location of the
new point.
.sp
The signature of this command prefix is
.RS
.TP
\fBcreateCmd\fR \fIcanvas\fR \fIx\fR \fIy\fR
The result of the command prefix \fImust\fR be a list of the canvas
items it created to represent the marker. Note here that the visual
representation of a "vertex" may consist of multiple canvas items in an
arbitrary shape.
.RE
.TP
\fB-highlight-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to (un)highlight a vertex.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to a command which will re-color
the item to highlight in red (and restores the color for
unhighlighting).
.sp
The two signatures of this command prefix are
.RS
.TP
\fBhighlightCmd\fR \fBon\fR \fIcanvas\fR \fIitem\fR
.sp
This method of the command prefix has to perform whatever is
needed to highlight the vertex the \fIitem\fR is a part of (remember
the note above about quadrilateral allowed to be constructed from multiple
canvas items).
.sp
The result of the command can be anything and will be passed as
is as argument \fIstate\fR to the \fBoff\fR method.
.TP
\fBhighlightCmd\fR \fBoff\fR \fIcanvas\fR \fIstate\fR
.sp
This method is invoked to unhighlight a vertex described by the
\fIstate\fR, which is the unchanged result of the \fBon\fR method
of the command prefix. The result of this method is ignored.
.sp
Note any interaction between dragging and highlighting of
quadrilateral is handled within the editor, and that the callback bears no
responsibility for doing such.
.RE
.TP
\fB-data-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when the quadrilateral was edited in some way. This is how the editor
delegates the actual storage of quadrilateral information to an
outside object.
.sp
This option can only be set at construction time.
.sp
If not specified it defaults to an empty string and is ignored
by the editor, i.e. not invoked.
.sp
The signatures of this command prefix are
.RS
.TP
\fBdataCmd\fR \fIeditorObj\fR \fIcoordinates\fR
This callback is invoked when the quarilateral was changed either
interactively, or programmatically.
See instance method \fBadd\fR for the latter.
.sp
The \fIeditorObj\fR identifies the instance invoking the
callback, whereas \fIcoordinates\fR is a list of vertex locations,
with each location a pair of x- and y-coordinates.
.sp
The result of this method is ignored.
.RE
.PP
.SH KEYWORDS
canvas, concave, convex, editing, non-convex, quadrilateral

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_equad\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::edit::quadrilateral" n 0\&.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::edit::quadrilateral \- Editing a quadrilateral on a canvas
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBcanvas::edit::points  ?0\&.1?\fR
.sp
package require \fBcanvas::edit::quadrilateral  ?0\&.1?\fR
.sp
\fB::canvas::edit\fR \fBquadrilateral\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR\&.\&.\&.
.sp
\fBobjectName\fR \fBdestroy\fR
.sp
\fBobjectName\fR \fBenable\fR
.sp
\fBobjectName\fR \fBdisable\fR
.sp
................................................................................
\fBhighlightCmd\fR \fBoff\fR \fIcanvas\fR \fIstate\fR
.sp
\fBdataCmd\fR \fIeditorObj\fR \fIcoordinates\fR
.sp
.BE
.SH DESCRIPTION
This package provides a class whose instances handle the editing of a
quadrilateral on a canvas\&. Instances can be configured with regard to
the visual appearance (regular, and highlighted) of vertex
markers\&. Note that instances do not store the edited quadrilateral
themselves, but delegate this to a configurable object\&.
.SH "CLASS API"
.TP
\fB::canvas::edit\fR \fBquadrilateral\fR \fIobjectName\fR \fIcanvas\fR \fIoptions\fR\&.\&.\&.
This, the class command, creates and configures a new instance of a
quadrilateral editor, named \fIobjectName\fR\&. The instance will be
connected to the specified \fIcanvas\fR widget\&.
.sp
The result of the command is the fully qualified name of the
instance command\&.
.sp
The options accepted here, and their values, are explained in
the section \fBOptions\fR\&.
.PP
.SH "INSTANCE API"
Instances of the quadrilateral editors provide the following API:
.TP
\fBobjectName\fR \fBdestroy\fR
This method destroys the quadrilateral editor and releases all its
internal resources\&.
.sp
Note that this operation does not destroy the items the editor
managed on the attached canvas, nor the canvas itself\&.
.sp
The result of the method is an empty string\&.
.TP
\fBobjectName\fR \fBenable\fR
This method activates editing of the quadrilateral on the canvas\&. This
is the default after instance creation\&. A call is ignored if the
editor is already active\&.
.sp
The result of the method is an empty string\&.
.sp
The complementary method is \fBdisable\fR\&. The interogatory
method for the current state is \fBactive\fR\&.
.TP
\fBobjectName\fR \fBdisable\fR
This method disables editing of the quadrilateral on the canvas\&. A call
is ignored if the editor is already disabled\&.
.sp
The result of the method is an empty string\&.
.sp
The complementary method is \fBenable\fR\&. The interogatory
method for the current state is \fBactive\fR\&.
.TP
\fBobjectName\fR \fBactive\fR
This method queries the editor state\&.
.sp
The result of the method is a boolean value, \fBtrue\fR if
the editor is active, and \fBfalse\fR otherwise, i\&.e\&. disabled\&.
.sp
The methods to change the state are \fBenable\fR and
\fBdisable\fR\&.
.TP
\fBobjectName\fR \fBadd\fR \fIx\fR \fIy\fR
This method programmatically adds a vertex at the specified location
to the quadrilateral\&.
.sp
The result of the method is an empty string\&.
.sp
Note that this method goes through the whole set of callbacks
invoked when the user interactively creates a vertex, i\&.e\&.
\fB-create-cmd\fR, and, more importantly, \fB-data-cmd\fR\&.
.sp
This is the method through which to load the vertices of a
pre-existing quadrilateral into an editor instance\&.
.sp
Note that at most 4 vertices can be specified, and at least 4
must be specified for the quadrilateral to be complete\&.
.TP
\fBobjectName\fR \fBclear\fR
This method programmatically unset the quadrilateral in the editor\&.
.sp
The result of the method is an empty string\&.
.sp
Note that this method goes through the same callback invoked
when the user interactively removes a vertex, i\&.e\&. \fB-data-cmd\fR\&.
.PP
.SH OPTIONS
The class command accepts the following options
.TP
\fB-convex\fR \fIboolean\fR
The value of this option is a boolean flag\&. When the flag is set the
editor will accept only convex quadrilaterals and reject all
operations which would result in a violation of convexity\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to \fBfalse\fR, i\&.e\&. acceptance
of any quadrilateral\&.
.TP
\fB-tag\fR \fIstring\fR
The value of this option is the name of the canvas tag with which to
identify all items of all quadrilateral managed by the editor\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to \fBQUADRILATERAL\fR
.TP
\fB-create-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to create a new vertex\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to a command which will create a
black-bordered blue circle of radius 3 centered on the location of the
new point\&.
.sp
The signature of this command prefix is
.RS
.TP
\fBcreateCmd\fR \fIcanvas\fR \fIx\fR \fIy\fR
The result of the command prefix \fImust\fR be a list of the canvas
items it created to represent the marker\&. Note here that the visual
representation of a "vertex" may consist of multiple canvas items in an
arbitrary shape\&.
.RE
.TP
\fB-highlight-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when it has to (un)highlight a vertex\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to a command which will re-color
the item to highlight in red (and restores the color for
unhighlighting)\&.
.sp
The two signatures of this command prefix are
.RS
.TP
\fBhighlightCmd\fR \fBon\fR \fIcanvas\fR \fIitem\fR
.sp
This method of the command prefix has to perform whatever is
needed to highlight the vertex the \fIitem\fR is a part of (remember
the note above about quadrilateral allowed to be constructed from multiple
canvas items)\&.
.sp
The result of the command can be anything and will be passed as
is as argument \fIstate\fR to the \fBoff\fR method\&.
.TP
\fBhighlightCmd\fR \fBoff\fR \fIcanvas\fR \fIstate\fR
.sp
This method is invoked to unhighlight a vertex described by the
\fIstate\fR, which is the unchanged result of the \fBon\fR method
of the command prefix\&. The result of this method is ignored\&.
.sp
Note any interaction between dragging and highlighting of
quadrilateral is handled within the editor, and that the callback bears no
responsibility for doing such\&.
.RE
.TP
\fB-data-cmd\fR \fIcommand-prefix\fR
The value of this option is a command prefix the editor will invoke
when the quadrilateral was edited in some way\&. This is how the editor
delegates the actual storage of quadrilateral information to an
outside object\&.
.sp
This option can only be set at construction time\&.
.sp
If not specified it defaults to an empty string and is ignored
by the editor, i\&.e\&. not invoked\&.
.sp
The signatures of this command prefix are
.RS
.TP
\fBdataCmd\fR \fIeditorObj\fR \fIcoordinates\fR
This callback is invoked when the quarilateral was changed either
interactively, or programmatically\&.
See instance method \fBadd\fR for the latter\&.
.sp
The \fIeditorObj\fR identifies the instance invoking the
callback, whereas \fIcoordinates\fR is a list of vertex locations,
with each location a pair of x- and y-coordinates\&.
.sp
The result of this method is ignored\&.
.RE
.PP
.SH KEYWORDS
canvas, concave, convex, editing, non-convex, quadrilateral

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_highlight.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::highlight" n 0.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::highlight \- Manage the highlighting of canvas items or item groups
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBcanvas::highlight  ?0.1?\fR
.sp
\fB::canvas::highlight\fR \fBon\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR
.sp
\fB::canvas::highlight\fR \fBoff\fR \fIcanvas\fR \fItagOrId\fR
.sp
\fB{*}cmd\fR \fBon\fR \fIcanvas\fR \fIitem\fR
.sp
\fB{*}cmd\fR \fBoff\fR \fIcanvas\fR \fIclientdata\fR
.sp
.BE
.SH DESCRIPTION
This package provides utility commands for setting up and tearing down
of highlights for canvas items or item groups, the latter identified
by a tag.
.SH API
.TP
\fB::canvas::highlight\fR \fBon\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR
This command sets up a general highlight, with the items of canvas
\fIcanvas\fR to highlight in this manner identified by \fItagOrId\fR
and the \fIcmd\fR prefix providing the implementation, i.e. the how to
perform the highlight.
.sp
The signature of the command prefix is described later, in
section \fBHighlight callback\fR.
.sp
The result of the command is the empty string.
.sp
Limitations:
.RS
.IP [1]
When a highlight is active no other highlight can be activated.
This means that nested highlights are not possible.
.IP [2]
The system may break if a highlight is removed from within its
highlight callback.
.RE
.TP
\fB::canvas::highlight\fR \fBoff\fR \fIcanvas\fR \fItagOrId\fR
This command removes any highlight set on the items of canvas
\fIcanvas\fR identified by \fItagOrId\fR.
.sp
The result of the command is the empty string.
.PP
.SS "HIGHLIGHT CALLBACK"
The highlight callback is a command prefix invoked in the following
two ways:
.TP
\fB{*}cmd\fR \fBon\fR \fIcanvas\fR \fIitem\fR
This form is invoked when the mouse has entered (one of) the item(s)
the highlight was set up for. The callback now has to perform any
reconfiguration necessary to highlight the item (group).
.sp
The result of the command can be anything. It is stored by the
system as client information and passed unchanged to the un-highlight
callback for its use. In this manner the highlight callback is able to
maintain custom state from highlighting to un-highlighting.
.sp
Note that the callback does not have to maintain state, nor
does it have to actually reconfigure the item (group). In the latter
case the callback simply serves as easy enter/leave notification.
.TP
\fB{*}cmd\fR \fBoff\fR \fIcanvas\fR \fIclientdata\fR
This form is invoked when the mouse has left (one of) the item(s) of
the currently active the highlight. The callback now has to perform
any reconfiguration necessary to un-highlight the item (group).
.sp
The result of the command must be a boolean value with the
usual value to be \fBtrue\fR. By returning \fBfalse\fR instead the
callback can veto the removal of the highlight.
.PP
.SH KEYWORDS
canvas, enter callback, highlighting, leave callback

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_highlight\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::highlight" n 0\&.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::highlight \- Manage the highlighting of canvas items or item groups
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBcanvas::highlight  ?0\&.1?\fR
.sp
\fB::canvas::highlight\fR \fBon\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR
.sp
\fB::canvas::highlight\fR \fBoff\fR \fIcanvas\fR \fItagOrId\fR
.sp
\fB{*}cmd\fR \fBon\fR \fIcanvas\fR \fIitem\fR
.sp
\fB{*}cmd\fR \fBoff\fR \fIcanvas\fR \fIclientdata\fR
.sp
.BE
.SH DESCRIPTION
This package provides utility commands for setting up and tearing down
of highlights for canvas items or item groups, the latter identified
by a tag\&.
.SH API
.TP
\fB::canvas::highlight\fR \fBon\fR \fIcanvas\fR \fItagOrId\fR \fIcmd\fR
This command sets up a general highlight, with the items of canvas
\fIcanvas\fR to highlight in this manner identified by \fItagOrId\fR
and the \fIcmd\fR prefix providing the implementation, i\&.e\&. the how to
perform the highlight\&.
.sp
The signature of the command prefix is described later, in
section \fBHighlight callback\fR\&.
.sp
The result of the command is the empty string\&.
.sp
Limitations:
.RS
.IP [1]
When a highlight is active no other highlight can be activated\&.
This means that nested highlights are not possible\&.
.IP [2]
The system may break if a highlight is removed from within its
highlight callback\&.
.RE
.TP
\fB::canvas::highlight\fR \fBoff\fR \fIcanvas\fR \fItagOrId\fR
This command removes any highlight set on the items of canvas
\fIcanvas\fR identified by \fItagOrId\fR\&.
.sp
The result of the command is the empty string\&.
.PP
.SS "HIGHLIGHT CALLBACK"
The highlight callback is a command prefix invoked in the following
two ways:
.TP
\fB{*}cmd\fR \fBon\fR \fIcanvas\fR \fIitem\fR
This form is invoked when the mouse has entered (one of) the item(s)
the highlight was set up for\&. The callback now has to perform any
reconfiguration necessary to highlight the item (group)\&.
.sp
The result of the command can be anything\&. It is stored by the
system as client information and passed unchanged to the un-highlight
callback for its use\&. In this manner the highlight callback is able to
maintain custom state from highlighting to un-highlighting\&.
.sp
Note that the callback does not have to maintain state, nor
does it have to actually reconfigure the item (group)\&. In the latter
case the callback simply serves as easy enter/leave notification\&.
.TP
\fB{*}cmd\fR \fBoff\fR \fIcanvas\fR \fIclientdata\fR
This form is invoked when the mouse has left (one of) the item(s) of
the currently active the highlight\&. The callback now has to perform
any reconfiguration necessary to un-highlight the item (group)\&.
.sp
The result of the command must be a boolean value with the
usual value to be \fBtrue\fR\&. By returning \fBfalse\fR instead the
callback can veto the removal of the highlight\&.
.PP
.SH KEYWORDS
canvas, enter callback, highlighting, leave callback

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_mvg.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2010 Wolf-Dieter Busch (http://wiki.tcl.tk/15505)
'\" Copyright (c) 2010 Documentation, Andreas Kupries
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::mvg" n 1.0.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::mvg \- Canvas to ImageMagick MVG vector format
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBcanvas::mvg  ?1?\fR
.sp
\fB::canvas::mvg\fR \fIpathName\fR
.sp
.BE
.SH DESCRIPTION
This package provides a command to convert a canvas' contents to
ImageMagick's MVG vector format.
.SH API
.TP
\fB::canvas::mvg\fR \fIpathName\fR
Dump the contents of the canvas \fIpathName\fR. The result is a string
in ImageMagick's MVG vector format.
.PP
.SH KEYWORDS
canvas, graphics, imagemagick, magick vector graphics, mvg, print screen, serialization, vector graphics
.SH COPYRIGHT
.nf
Copyright (c) 2010 Wolf-Dieter Busch (http://wiki.tcl.tk/15505)
Copyright (c) 2010 Documentation, Andreas Kupries

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_mvg\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2010 Wolf-Dieter Busch (http://wiki\&.tcl\&.tk/15505)
'\" Copyright (c) 2010 Documentation, Andreas Kupries
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::mvg" n 1\&.0\&.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::mvg \- Canvas to ImageMagick MVG vector format
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBcanvas::mvg  ?1?\fR
.sp
\fB::canvas::mvg\fR \fIpathName\fR
.sp
.BE
.SH DESCRIPTION
This package provides a command to convert a canvas' contents to
ImageMagick's MVG vector format\&.
.SH API
.TP
\fB::canvas::mvg\fR \fIpathName\fR
Dump the contents of the canvas \fIpathName\fR\&. The result is a string
in ImageMagick's MVG vector format\&.
.PP
.SH KEYWORDS
canvas, graphics, imagemagick, magick vector graphics, mvg, print screen, serialization, vector graphics
.SH COPYRIGHT
.nf
Copyright (c) 2010 Wolf-Dieter Busch (http://wiki\&.tcl\&.tk/15505)
Copyright (c) 2010 Documentation, Andreas Kupries

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_snap.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2004 George Petasis (http://wiki.tcl.tk/1404)
'\" Copyright (c) 2010 Documentation, Andreas Kupries
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::snap" n 1.0.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::snap \- Canvas snapshot to Tk photo image
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBcanvas::snap  ?1.0.1?\fR
.sp
package require \fBimg::window \fR
.sp
\fB::canvas::snap\fR \fIpathName\fR
.sp
.BE
.SH DESCRIPTION
This package provides a command to take snapshots of arbitrary
canvases.
.SH API
.TP
\fB::canvas::snap\fR \fIpathName\fR
Takes a snapshot of the canvas \fIpathName\fR. The result is the name
of a new Tk photo image containing the snapshot.
.sp
\fINote\fR that this command has a side-effect. To avoid having white
rectangles where other windows may overlap the canvas this command
forces the toplevel window the canvas is in to the top of the stacking
order.
.PP
.SH KEYWORDS
canvas, image, photo, print screen, snapshot
.SH COPYRIGHT
.nf
Copyright (c) 2004 George Petasis (http://wiki.tcl.tk/1404)
Copyright (c) 2010 Documentation, Andreas Kupries

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_snap\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2004 George Petasis (http://wiki\&.tcl\&.tk/1404)
'\" Copyright (c) 2010 Documentation, Andreas Kupries
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::snap" n 1\&.0\&.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::snap \- Canvas snapshot to Tk photo image
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBcanvas::snap  ?1\&.0\&.1?\fR
.sp
package require \fBimg::window \fR
.sp
\fB::canvas::snap\fR \fIpathName\fR
.sp
.BE
.SH DESCRIPTION
This package provides a command to take snapshots of arbitrary
canvases\&.
.SH API
.TP
\fB::canvas::snap\fR \fIpathName\fR
Takes a snapshot of the canvas \fIpathName\fR\&. The result is the name
of a new Tk photo image containing the snapshot\&.
.sp
\fINote\fR that this command has a side-effect\&. To avoid having white
rectangles where other windows may overlap the canvas this command
forces the toplevel window the canvas is in to the top of the stacking
order\&.
.PP
.SH KEYWORDS
canvas, image, photo, print screen, snapshot
.SH COPYRIGHT
.nf
Copyright (c) 2004 George Petasis (http://wiki\&.tcl\&.tk/1404)
Copyright (c) 2010 Documentation, Andreas Kupries

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_sqmap.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::sqmap" n 0.3.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::sqmap \- Canvas with map background based on square tiles
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBTk  8.4\fR
.sp
package require \fBsnit \fR
.sp
package require \fBuevent::onidle \fR
.sp
package require \fBcache::async \fR
.sp
package require \fBcanvas::sqmap  ?0.3.1?\fR
.sp
\fB::canvas::sqmap\fR \fIpathName\fR ?options?
.sp
\fIcanvasName\fR \fBimage set\fR \fIcell\fR \fIimage\fR
.sp
\fIcanvasName\fR \fBimage unset\fR \fIcell\fR
.sp
\fIcanvasName\fR \fBflush\fR
.sp
.BE
.SH DESCRIPTION
This package provides an extended canvas widget for the display of
maps based on a set of square image tiles. The tiles are the
background of the canvas, with all other canvas items added always
shown in front of them. The number of tiles shown, tile size, and
where to get the images to show are all configurable.
.SH API
.TP
\fB::canvas::sqmap\fR \fIpathName\fR ?options?
Creates the canvas \fIpathName\fR and configures it. The new widget
supports all of the options and methods of a regular canvas, plus the
options and methods described below.
.sp
The result of the command is \fIpathName\fR.
.PP
.SS OPTIONS
.TP
\fB-grid-cell-width\fR
The value for this option is a non-negative integer. It specifies the
width of the cells the background is made up of.
.TP
\fB-grid-cell-height\fR
The value for this option is a non-negative integer. It specifies the
height of the cells the background is made up of.
.TP
\fB-grid-cell-command\fR
The value for this option is a command prefix. It is invoked whenever
the canvas needs the image for a specific cell of the background, with
two additional arguments, the id of the cell, and a command prefix to
invoke when the image is ready, or known to not exist.
.sp
The id of the cell is a 2-element list containing the row and column
number of the cell, in this order. The result command prefix (named
"$result" in the example below) has to be invoked with either two or
three arguments, i.e.
.CS


    $result set   $cellid $image ; # image is known and ready
    $result unset $cellid        ; # image does not exist

.CE
.IP
This option may be left undefined, i.e. the canvas can operate without
it. In that case the only images shown in grid cells are those
explicitly set with the method \fBimage set\fR, see the next
section. All other grid cells will simply be empty.
.TP
\fB-viewport-command\fR
This option specifies a command prefix to invoke when the viewport of
the canvas is changed, to allow users keep track of where in the
scroll-region we are at all times. This can be used, for example, to
drive derivate displays, or to keep items in view by moving them as
the viewport moves.
.TP
\fB-image-on-load\fR
The value for this option is an image. If specified the image is shown
in a cell while the actual image for that cell is getting loaded
through the callback specified by the \fB-grid-cell-command\fR.
.TP
\fB-image-on-unset\fR
The value for this option is an image. If specified the image is shown
in a cell for which the callback specified by the \fB-grid-cell-command\fR
reported that there is no actual image to be shown.
.PP
.SS METHODS
.TP
\fIcanvasName\fR \fBimage set\fR \fIcell\fR \fIimage\fR
Invoking this method places the \fIimage\fR into the specified
\fIcell\fR of the background. The cell is given as a 2-element list
containing row and column number, in this order.
.sp
Note that an image is allowed to be associated with and displayed in
multiple cells of the canvas.
.TP
\fIcanvasName\fR \fBimage unset\fR \fIcell\fR
Invoking this method declares the specified \fIcell\fR of the
background as empty, an existing image shown by this cell will be
forgotten.  The cell is given as a 2-element list containing row and
column number, in this order.
.TP
\fIcanvasName\fR \fBflush\fR
Invoking this method forces the canvas to completely reload the images
for all cells. Do not use this method if the canvas is operated
without a \fB-grid-cell-command\fR, as in that case the canvas will
simply forget all images without being able to reload them.
.PP
.SH "IMAGE OWNERSHIP"
Note that the canvas \fIdoes not\fR take ownership of the images it
shows in the background. In other words, when we say that the canvas
forgets an image this means only that the association between a grid
cell and shown image is broken. The image is \fInot\fR
deleted. Managing the lifecycle of the images shown by the canvas is
responsibility of the user of the canvas.
.SH KEYWORDS
canvas, cell, grid, image, map, square map, tile

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_sqmap\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::sqmap" n 0\&.3\&.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::sqmap \- Canvas with map background based on square tiles
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBTk  8\&.4\fR
.sp
package require \fBsnit \fR
.sp
package require \fBuevent::onidle \fR
.sp
package require \fBcache::async \fR
.sp
package require \fBcanvas::sqmap  ?0\&.3\&.1?\fR
.sp
\fB::canvas::sqmap\fR \fIpathName\fR ?options?
.sp
\fIcanvasName\fR \fBimage set\fR \fIcell\fR \fIimage\fR
.sp
\fIcanvasName\fR \fBimage unset\fR \fIcell\fR
.sp
\fIcanvasName\fR \fBflush\fR
.sp
.BE
.SH DESCRIPTION
This package provides an extended canvas widget for the display of
maps based on a set of square image tiles\&. The tiles are the
background of the canvas, with all other canvas items added always
shown in front of them\&. The number of tiles shown, tile size, and
where to get the images to show are all configurable\&.
.SH API
.TP
\fB::canvas::sqmap\fR \fIpathName\fR ?options?
Creates the canvas \fIpathName\fR and configures it\&. The new widget
supports all of the options and methods of a regular canvas, plus the
options and methods described below\&.
.sp
The result of the command is \fIpathName\fR\&.
.PP
.SS OPTIONS
.TP
\fB-grid-cell-width\fR
The value for this option is a non-negative integer\&. It specifies the
width of the cells the background is made up of\&.
.TP
\fB-grid-cell-height\fR
The value for this option is a non-negative integer\&. It specifies the
height of the cells the background is made up of\&.
.TP
\fB-grid-cell-command\fR
The value for this option is a command prefix\&. It is invoked whenever
the canvas needs the image for a specific cell of the background, with
two additional arguments, the id of the cell, and a command prefix to
invoke when the image is ready, or known to not exist\&.
.sp
The id of the cell is a 2-element list containing the row and column
number of the cell, in this order\&. The result command prefix (named
"$result" in the example below) has to be invoked with either two or
three arguments, i\&.e\&.
.CS


    $result set   $cellid $image ; # image is known and ready
    $result unset $cellid        ; # image does not exist

.CE
.IP
This option may be left undefined, i\&.e\&. the canvas can operate without
it\&. In that case the only images shown in grid cells are those
explicitly set with the method \fBimage set\fR, see the next
section\&. All other grid cells will simply be empty\&.
.TP
\fB-viewport-command\fR
This option specifies a command prefix to invoke when the viewport of
the canvas is changed, to allow users keep track of where in the
scroll-region we are at all times\&. This can be used, for example, to
drive derivate displays, or to keep items in view by moving them as
the viewport moves\&.
.TP
\fB-image-on-load\fR
The value for this option is an image\&. If specified the image is shown
in a cell while the actual image for that cell is getting loaded
through the callback specified by the \fB-grid-cell-command\fR\&.
.TP
\fB-image-on-unset\fR
The value for this option is an image\&. If specified the image is shown
in a cell for which the callback specified by the \fB-grid-cell-command\fR
reported that there is no actual image to be shown\&.
.PP
.SS METHODS
.TP
\fIcanvasName\fR \fBimage set\fR \fIcell\fR \fIimage\fR
Invoking this method places the \fIimage\fR into the specified
\fIcell\fR of the background\&. The cell is given as a 2-element list
containing row and column number, in this order\&.
.sp
Note that an image is allowed to be associated with and displayed in
multiple cells of the canvas\&.
.TP
\fIcanvasName\fR \fBimage unset\fR \fIcell\fR
Invoking this method declares the specified \fIcell\fR of the
background as empty, an existing image shown by this cell will be
forgotten\&.  The cell is given as a 2-element list containing row and
column number, in this order\&.
.TP
\fIcanvasName\fR \fBflush\fR
Invoking this method forces the canvas to completely reload the images
for all cells\&. Do not use this method if the canvas is operated
without a \fB-grid-cell-command\fR, as in that case the canvas will
simply forget all images without being able to reload them\&.
.PP
.SH "IMAGE OWNERSHIP"
Note that the canvas \fIdoes not\fR take ownership of the images it
shows in the background\&. In other words, when we say that the canvas
forgets an image this means only that the association between a grid
cell and shown image is broken\&. The image is \fInot\fR
deleted\&. Managing the lifecycle of the images shown by the canvas is
responsibility of the user of the canvas\&.
.SH KEYWORDS
canvas, cell, grid, image, map, square map, tile

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_tags.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::tag" n 0.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::tag \- Easier management of the tags on canvas items or item groups
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBcanvas::tag  ?0.1?\fR
.sp
\fB::canvas::tag\fR \fBappend\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR...
.sp
\fB::canvas::tag\fR \fBprepend\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR...
.sp
\fB::canvas::tag\fR \fBappend\fR \fIcanvas\fR \fItagOrId\fR \fIindex\fR \fItag\fR...
.sp
\fB::canvas::tag\fR \fBremove\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR...
.sp
\fB::canvas::tag\fR \fBmatch\fR \fIcanvas\fR \fItagOrId\fR \fIpattern\fR
.sp
.BE
.SH DESCRIPTION
This package provides utility commands for easier management of the
tag lists associated with canvas items or item groups.
.PP
The problem with the existing canvas API is that a tag list can
only be set as a whole, making adding and removing of tags from such
lists relatively complex operations reading the current tag list,
modifying it, and then writing the changed list back.
.PP
The commands provided by this package hide all this complexity
from the user.
.SH API
.TP
\fB::canvas::tag\fR \fBappend\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR...
This command adds the tags \fItag\fR... to the tag list for the items
identified by the \fItagOrId\fR in the \fIcanvas\fR widget. The new
tags are added at the end of the list.
.sp
The result of the command is the empty string.
.TP
\fB::canvas::tag\fR \fBprepend\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR...
This command adds the tags \fItag\fR... to the tag list for the items
identified by the \fItagOrId\fR in the \fIcanvas\fR widget. The new
tags are added at the beginning of the list.
.sp
The result of the command is the empty string.
.TP
\fB::canvas::tag\fR \fBappend\fR \fIcanvas\fR \fItagOrId\fR \fIindex\fR \fItag\fR...
This command adds the tags \fItag\fR... to the tag list for the items
identified by the \fItagOrId\fR in the \fIcanvas\fR widget. The new
tags are inserted before the element at \fIindex\fR.
.sp
\fIindex\fR \fB0\fR refers to the beginning of the list.
.sp
\fIindex\fR \fBend\fR refers to after the end of the list.
.sp
The result of the command is the empty string.
.TP
\fB::canvas::tag\fR \fBremove\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR...
This command removes the named tags \fItag\fR... from the tag list for the items
identified by the \fItagOrId\fR in the \fIcanvas\fR widget.
.sp
The result of the command is the empty string.
.TP
\fB::canvas::tag\fR \fBmatch\fR \fIcanvas\fR \fItagOrId\fR \fIpattern\fR
This command finds all tags for the items identified by the
\fItagOrId\fR in the \fIcanvas\fR widget which match the glob
\fIpattern\fR.
.sp
The result of the command is a list of the matching tags. Which
may be empty.
.PP
.SH KEYWORDS
append tag, canvas, insert tag, remove tag, tags

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_tags\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::tag" n 0\&.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::tag \- Easier management of the tags on canvas items or item groups
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBcanvas::tag  ?0\&.1?\fR
.sp
\fB::canvas::tag\fR \fBappend\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR\&.\&.\&.
.sp
\fB::canvas::tag\fR \fBprepend\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR\&.\&.\&.
.sp
\fB::canvas::tag\fR \fBappend\fR \fIcanvas\fR \fItagOrId\fR \fIindex\fR \fItag\fR\&.\&.\&.
.sp
\fB::canvas::tag\fR \fBremove\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR\&.\&.\&.
.sp
\fB::canvas::tag\fR \fBmatch\fR \fIcanvas\fR \fItagOrId\fR \fIpattern\fR
.sp
.BE
.SH DESCRIPTION
This package provides utility commands for easier management of the
tag lists associated with canvas items or item groups\&.
.PP
The problem with the existing canvas API is that a tag list can
only be set as a whole, making adding and removing of tags from such
lists relatively complex operations reading the current tag list,
modifying it, and then writing the changed list back\&.
.PP
The commands provided by this package hide all this complexity
from the user\&.
.SH API
.TP
\fB::canvas::tag\fR \fBappend\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR\&.\&.\&.
This command adds the tags \fItag\fR\&.\&.\&. to the tag list for the items
identified by the \fItagOrId\fR in the \fIcanvas\fR widget\&. The new
tags are added at the end of the list\&.
.sp
The result of the command is the empty string\&.
.TP
\fB::canvas::tag\fR \fBprepend\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR\&.\&.\&.
This command adds the tags \fItag\fR\&.\&.\&. to the tag list for the items
identified by the \fItagOrId\fR in the \fIcanvas\fR widget\&. The new
tags are added at the beginning of the list\&.
.sp
The result of the command is the empty string\&.
.TP
\fB::canvas::tag\fR \fBappend\fR \fIcanvas\fR \fItagOrId\fR \fIindex\fR \fItag\fR\&.\&.\&.
This command adds the tags \fItag\fR\&.\&.\&. to the tag list for the items
identified by the \fItagOrId\fR in the \fIcanvas\fR widget\&. The new
tags are inserted before the element at \fIindex\fR\&.
.sp
\fIindex\fR \fB0\fR refers to the beginning of the list\&.
.sp
\fIindex\fR \fBend\fR refers to after the end of the list\&.
.sp
The result of the command is the empty string\&.
.TP
\fB::canvas::tag\fR \fBremove\fR \fIcanvas\fR \fItagOrId\fR \fItag\fR\&.\&.\&.
This command removes the named tags \fItag\fR\&.\&.\&. from the tag list for the items
identified by the \fItagOrId\fR in the \fIcanvas\fR widget\&.
.sp
The result of the command is the empty string\&.
.TP
\fB::canvas::tag\fR \fBmatch\fR \fIcanvas\fR \fItagOrId\fR \fIpattern\fR
This command finds all tags for the items identified by the
\fItagOrId\fR in the \fIcanvas\fR widget which match the glob
\fIpattern\fR\&.
.sp
The result of the command is a list of the matching tags\&. Which
may be empty\&.
.PP
.SH KEYWORDS
append tag, canvas, insert tag, remove tag, tags

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_trlines.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::track::lines" n 0.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::track::lines \- Manage a group of rubber band lines
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBcanvas::tag  ?0.1?\fR
.sp
\fB::canvas::track\fR \fBlines\fR \fIobjectName\fR \fIcanvas\fR
.sp
\fBobjectName\fR \fBdestroy\fR
.sp
\fBobjectName\fR \fBstart\fR \fIcurrent\fR \fIp\fR...
.sp
\fBobjectName\fR \fBmove\fR \fIcurrent\fR
.sp
\fBobjectName\fR \fBdone\fR
.sp
.BE
.SH DESCRIPTION
This package provides a utility class managing the drawing of set of semi-crosshair (rubberband) lines.
.SH "CLASS API"
.TP
\fB::canvas::track\fR \fBlines\fR \fIobjectName\fR \fIcanvas\fR
This, the class command, creates and configures a new instance of the
tracker, named \fIobjectName\fR. The instance will be
connected to the specified \fIcanvas\fR widget.
.sp
The result of the command is the fully qualified name of the
instance command.
.PP
.SH "INSTANCE API"
Instances of this class provide the following API:
.TP
\fBobjectName\fR \fBdestroy\fR
This method destroys the instance and releases all its
internal resources.
.sp
This operation does destroy the items representing the
tracked lines. It does not destroy the attached canvas.
.sp
The result of the method is an empty string.
.TP
\fBobjectName\fR \fBstart\fR \fIcurrent\fR \fIp\fR...
This method starts the tracking of a set of lines, one line per
point \fIp\fR, which specifies the destination end-point of each
line. All lines will have \fIcurrent\fR as a common end-point.
.sp
Note that a previously tracked set of lines is removed.
.sp
The result of the method is an empty string.
.sp
Each point is specified through a 2-element list containing its
x- and y-coordinates, in this order.
.TP
\fBobjectName\fR \fBmove\fR \fIcurrent\fR
This method updates the shared end-point of all rubberbands and redraws
them.
.sp
The result of the method is an empty string.
.sp
The point is specified through a 2-element list containing its
x- and y-coordinates, in this order.
.TP
\fBobjectName\fR \fBdone\fR
This method ends the tracking of the current set of lines and removes
them from the canvas.
.PP
.SH KEYWORDS
canvas, crosshair, rubberband, tracking

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_trlines\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::track::lines" n 0\&.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::track::lines \- Manage a group of rubber band lines
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBcanvas::tag  ?0\&.1?\fR
.sp
\fB::canvas::track\fR \fBlines\fR \fIobjectName\fR \fIcanvas\fR
.sp
\fBobjectName\fR \fBdestroy\fR
.sp
\fBobjectName\fR \fBstart\fR \fIcurrent\fR \fIp\fR\&.\&.\&.
.sp
\fBobjectName\fR \fBmove\fR \fIcurrent\fR
.sp
\fBobjectName\fR \fBdone\fR
.sp
.BE
.SH DESCRIPTION
This package provides a utility class managing the drawing of set of semi-crosshair (rubberband) lines\&.
.SH "CLASS API"
.TP
\fB::canvas::track\fR \fBlines\fR \fIobjectName\fR \fIcanvas\fR
This, the class command, creates and configures a new instance of the
tracker, named \fIobjectName\fR\&. The instance will be
connected to the specified \fIcanvas\fR widget\&.
.sp
The result of the command is the fully qualified name of the
instance command\&.
.PP
.SH "INSTANCE API"
Instances of this class provide the following API:
.TP
\fBobjectName\fR \fBdestroy\fR
This method destroys the instance and releases all its
internal resources\&.
.sp
This operation does destroy the items representing the
tracked lines\&. It does not destroy the attached canvas\&.
.sp
The result of the method is an empty string\&.
.TP
\fBobjectName\fR \fBstart\fR \fIcurrent\fR \fIp\fR\&.\&.\&.
This method starts the tracking of a set of lines, one line per
point \fIp\fR, which specifies the destination end-point of each
line\&. All lines will have \fIcurrent\fR as a common end-point\&.
.sp
Note that a previously tracked set of lines is removed\&.
.sp
The result of the method is an empty string\&.
.sp
Each point is specified through a 2-element list containing its
x- and y-coordinates, in this order\&.
.TP
\fBobjectName\fR \fBmove\fR \fIcurrent\fR
This method updates the shared end-point of all rubberbands and redraws
them\&.
.sp
The result of the method is an empty string\&.
.sp
The point is specified through a 2-element list containing its
x- and y-coordinates, in this order\&.
.TP
\fBobjectName\fR \fBdone\fR
This method ends the tracking of the current set of lines and removes
them from the canvas\&.
.PP
.SH KEYWORDS
canvas, crosshair, rubberband, tracking

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_zoom.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::zoom" n 0.2.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::zoom \- Zoom control for canvas::sqmap
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBTk  8.4\fR
.sp
package require \fBsnit \fR
.sp
package require \fBuevent::onidle \fR
.sp
package require \fBcanvas::zoom  ?0.2.1?\fR
.sp
\fB::canvas::zoom\fR \fIpathName\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides a widget to enable the user of a map display to
control the zoom level.
.SH API
.TP
\fB::canvas::zoom\fR \fIpathName\fR ?options?
Creates the zoom control widget \fIpathName\fR and configures it. The
methods and options supported by the new widget are described in the
following sections.
.sp
The result of the command is \fIpathName\fR.
.PP
.SS OPTIONS
.TP
\fB-orient\fR
The value for this option is either \fBvertical\fR, or
\fBhorizontal\fR, specifying the orientation of the major axis of
the widget. The default is \fBvertical\fR.
.TP
\fB-levels\fR
The value for this option is a non-negative integer. It specifies the
number of zoom levels to support.
.TP
\fB-variable\fR
The value for this option is the name of a global or namespaced
variable which is connected with the widget. changes to the zoom level
made the widget are propagated to this variable, and in turn changes
to the variable are imported into the widget.
.TP
\fB-command\fR
This option specifies a command prefix. This callback will be invoked
whenever the zoom level is changed. It is called with two additional
arguments, the zoom control widget, and the new zoom level, in this
order.
.PP
.SS METHODS
The widget supports no methods beyond the standard (\fBconfigure\fR,
\fBcget\fR, etc.).
.SH KEYWORDS
zoom

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/canvas/canvas_zoom\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvas::zoom" n 0\&.2\&.1 tklib "Variations on a canvas"
.BS
.SH NAME
canvas::zoom \- Zoom control for canvas::sqmap
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBTk  8\&.4\fR
.sp
package require \fBsnit \fR
.sp
package require \fBuevent::onidle \fR
.sp
package require \fBcanvas::zoom  ?0\&.2\&.1?\fR
.sp
\fB::canvas::zoom\fR \fIpathName\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides a widget to enable the user of a map display to
control the zoom level\&.
.SH API
.TP
\fB::canvas::zoom\fR \fIpathName\fR ?options?
Creates the zoom control widget \fIpathName\fR and configures it\&. The
methods and options supported by the new widget are described in the
following sections\&.
.sp
The result of the command is \fIpathName\fR\&.
.PP
.SS OPTIONS
.TP
\fB-orient\fR
The value for this option is either \fBvertical\fR, or
\fBhorizontal\fR, specifying the orientation of the major axis of
the widget\&. The default is \fBvertical\fR\&.
.TP
\fB-levels\fR
The value for this option is a non-negative integer\&. It specifies the
number of zoom levels to support\&.
.TP
\fB-variable\fR
The value for this option is the name of a global or namespaced
variable which is connected with the widget\&. changes to the zoom level
made the widget are propagated to this variable, and in turn changes
to the variable are imported into the widget\&.
.TP
\fB-command\fR
This option specifies a command prefix\&. This callback will be invoked
whenever the zoom level is changed\&. It is called with two additional
arguments, the zoom control widget, and the new zoom level, in this
order\&.
.PP
.SS METHODS
The widget supports no methods beyond the standard (\fBconfigure\fR,
\fBcget\fR, etc\&.)\&.
.SH KEYWORDS
zoom

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/chatwidget/chatwidget.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "chatwidget" n 1.0.0 tklib "Composite widget for chat applications"
.BS
.SH NAME
chatwidget \- Provides a multi-paned view suitable for display of chat room or irc channel information
.SH SYNOPSIS
package require \fBTk  8.5\fR
.sp
package require \fBchatwidget  ?1.0.0?\fR
.sp
\fB::chatwidget::chatwidget\fR \fIpath\fR ?\fIoptions\fR?
.sp
\fB$widget\fR topic \fIcommand\fR \fIargs\fR
.sp
\fB$widget\fR name \fInick\fR \fIargs\fR
.sp
................................................................................
\fB$widget\fR entry \fIargs\fR
.sp
\fB$widget\fR chat \fIargs\fR
.sp
.BE
.SH DESCRIPTION
This is a composite widget designed to simplify the construction of
chat applications. The widget contains display areas for chat
messages, user names and topic and an entry area. It automatically
handles colourization of messages per nick and manages nick
completion. A system of hooks permit the application author to adjust
display features. The main chat display area may be split for use
displaying history or for searching.
.PP
The widget is made up of a number of text widget and panedwindow
widgets so that the size of each part of the display may be adjusted
by the user. All the text widgets may be accessed via widget
passthrough commands if fine adjustment is required. The topic and
names sections can also be hidden if desired.
.SH COMMANDS
.TP
\fB::chatwidget::chatwidget\fR \fIpath\fR ?\fIoptions\fR?
Create a new chatwidget using the Tk window id \fIpath\fR. Any options
provided are currently passed directly to the main chat text widget.
.PP
.SH "WIDGET COMMANDS"
.TP
\fB$widget\fR topic \fIcommand\fR \fIargs\fR
The chat widget can display a topic string, for instance the topic or
name given to a multi-user chatroom or irc channel.
.RS
.TP
\fBshow\fR
Enable display of the topic.
.TP
\fBhide\fR
Disable display of the topic
.TP
\fBset \fItopic\fR\fR
Set the topic text to \fItopic\fR.
.RE
.TP
\fB$widget\fR name \fInick\fR \fIargs\fR
Control the names and tags associated with names.
.RS
.TP
\fBlist ?\fI-full\fR?\fR
Returns a list of all the user names from the names view. If ?-full? is given then the list returned is a list of lists where each
sublist is made up of the nick followed by any options that have been
set on this nick entry. This may be used to examine any application
specific options that may be applied to a nick when using the
\fBadd\fR command.
.TP
\fBadd \fInick\fR ?\fIoptions\fR?\fR
.TP
\fBdelete \fInick\fR\fR
.RE
.TP
\fB$widget\fR message \fItext\fR \fIargs\fR
Add messages to the display. options are -nick, -time, -type, -mark
-tags
.TP
\fB$widget\fR hook \fIcommand\fR \fIargs\fR
Manage hooks. add (message, post names_group, names_nick, chatstate), remove, run
.TP
\fB$widget\fR names \fIargs\fR
Passthrough to the name display text widget. See the \fBtext\fR widget manual
for all available commands. The chatwidget provides two additional
commands \fBshow\fR and \fBhide\fR which are used to control the
display of this element in the widget.
.TP
\fB$widget\fR entry \fIargs\fR
Passthrough to the entry text widget. See the \fBtext\fR widget manual
for all available commands.
.TP
\fB$widget\fR chat \fIargs\fR
Passthrough to the chat text widget. See the \fBtext\fR widget manual for
all available commands.
.PP
.SH EXAMPLE
.CS


chatwidget::chatwidget .chat
proc speak {w msg} {$w message $msg -nick user}
.chat hook add post [list speak .chat]
pack .chat -side top -fill both -expand 1
.chat topic show
.chat topic set "Chat widget demo"
.chat name add "admin" -group admin
.chat name add "user" -group users -color tomato
.chat message "Chatwidget ready" -type system
.chat message "Hello, user" -nick admin
.chat message "Hello, admin" -nick user

.CE
.PP
A more extensive example is available by examining the code for the picoirc
program in the tclapps repository which ties the tcllib \fBpicoirc\fR package to this
\fBchatwidget\fR package to create a simple irc client.
.SH "SEE ALSO"
text(n)
.SH KEYWORDS
chat, chatwidget, composite widget, irc, mega-widget, widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/chatwidget/chatwidget\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "chatwidget" n 1\&.0\&.0 tklib "Composite widget for chat applications"
.BS
.SH NAME
chatwidget \- Provides a multi-paned view suitable for display of chat room or irc channel information
.SH SYNOPSIS
package require \fBTk  8\&.5\fR
.sp
package require \fBchatwidget  ?1\&.0\&.0?\fR
.sp
\fB::chatwidget::chatwidget\fR \fIpath\fR ?\fIoptions\fR?
.sp
\fB$widget\fR topic \fIcommand\fR \fIargs\fR
.sp
\fB$widget\fR name \fInick\fR \fIargs\fR
.sp
................................................................................
\fB$widget\fR entry \fIargs\fR
.sp
\fB$widget\fR chat \fIargs\fR
.sp
.BE
.SH DESCRIPTION
This is a composite widget designed to simplify the construction of
chat applications\&. The widget contains display areas for chat
messages, user names and topic and an entry area\&. It automatically
handles colourization of messages per nick and manages nick
completion\&. A system of hooks permit the application author to adjust
display features\&. The main chat display area may be split for use
displaying history or for searching\&.
.PP
The widget is made up of a number of text widget and panedwindow
widgets so that the size of each part of the display may be adjusted
by the user\&. All the text widgets may be accessed via widget
passthrough commands if fine adjustment is required\&. The topic and
names sections can also be hidden if desired\&.
.SH COMMANDS
.TP
\fB::chatwidget::chatwidget\fR \fIpath\fR ?\fIoptions\fR?
Create a new chatwidget using the Tk window id \fIpath\fR\&. Any options
provided are currently passed directly to the main chat text widget\&.
.PP
.SH "WIDGET COMMANDS"
.TP
\fB$widget\fR topic \fIcommand\fR \fIargs\fR
The chat widget can display a topic string, for instance the topic or
name given to a multi-user chatroom or irc channel\&.
.RS
.TP
\fBshow\fR
Enable display of the topic\&.
.TP
\fBhide\fR
Disable display of the topic
.TP
\fBset \fItopic\fR\fR
Set the topic text to \fItopic\fR\&.
.RE
.TP
\fB$widget\fR name \fInick\fR \fIargs\fR
Control the names and tags associated with names\&.
.RS
.TP
\fBlist ?\fI-full\fR?\fR
Returns a list of all the user names from the names view\&. If ?-full? is given then the list returned is a list of lists where each
sublist is made up of the nick followed by any options that have been
set on this nick entry\&. This may be used to examine any application
specific options that may be applied to a nick when using the
\fBadd\fR command\&.
.TP
\fBadd \fInick\fR ?\fIoptions\fR?\fR
.TP
\fBdelete \fInick\fR\fR
.RE
.TP
\fB$widget\fR message \fItext\fR \fIargs\fR
Add messages to the display\&. options are -nick, -time, -type, -mark
-tags
.TP
\fB$widget\fR hook \fIcommand\fR \fIargs\fR
Manage hooks\&. add (message, post names_group, names_nick, chatstate), remove, run
.TP
\fB$widget\fR names \fIargs\fR
Passthrough to the name display text widget\&. See the \fBtext\fR widget manual
for all available commands\&. The chatwidget provides two additional
commands \fBshow\fR and \fBhide\fR which are used to control the
display of this element in the widget\&.
.TP
\fB$widget\fR entry \fIargs\fR
Passthrough to the entry text widget\&. See the \fBtext\fR widget manual
for all available commands\&.
.TP
\fB$widget\fR chat \fIargs\fR
Passthrough to the chat text widget\&. See the \fBtext\fR widget manual for
all available commands\&.
.PP
.SH EXAMPLE
.CS


chatwidget::chatwidget \&.chat
proc speak {w msg} {$w message $msg -nick user}
\&.chat hook add post [list speak \&.chat]
pack \&.chat -side top -fill both -expand 1
\&.chat topic show
\&.chat topic set "Chat widget demo"
\&.chat name add "admin" -group admin
\&.chat name add "user" -group users -color tomato
\&.chat message "Chatwidget ready" -type system
\&.chat message "Hello, user" -nick admin
\&.chat message "Hello, admin" -nick user

.CE
.PP
A more extensive example is available by examining the code for the picoirc
program in the tclapps repository which ties the tcllib \fBpicoirc\fR package to this
\fBchatwidget\fR package to create a simple irc client\&.
.SH "SEE ALSO"
text(n)
.SH KEYWORDS
chat, chatwidget, composite widget, irc, mega-widget, widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/controlwidget/controlwidget.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2010 Ron Fox <rfox@...>
'\" Copyright (c) 2010 Gerhard Reithofer <...@...>
'\" Copyright (c) 2010 Marco Maggi <...@...>
'\" Copyright (c) 2010 Arjen Markus <arjenmarkus@users.sourceforge.net>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "controlwidget" n 0.1 tklib "controlwidget"
.BS
.SH NAME
controlwidget \- Collection of widgets for displaying and controlling numerical values
.SH SYNOPSIS
package require \fBTcl  ?8.5?\fR
.sp
package require \fBTk  ?8.5?\fR
.sp
package require \fBsnit  ?2.0?\fR
.sp
package require \fBcontrolwidget  ?0.1?\fR
.sp
\fB::controlwidget::meter\fR \fIw\fR \fIargs\fR
.sp
\fB::controlwidget::slider\fR \fIw\fR \fIargs\fR
.sp
\fB::controlwidget::equalizerBar\fR \fIw\fR \fIargs\fR
.sp
................................................................................
\fB$matrix\fR get
.sp
\fB$matrix\fR set \fIindex\fR
.sp
.BE
.SH DESCRIPTION
.PP
The controlwidget package focuses on the display and interactive control of numerical values.
It mimicks several of the meters and controls found in laboratory settings but also
daily life: volt meters, equalizers and tachometers to name a few. They can be seen as alternatives
for the \fIscale widget\fR.
.PP
\fINote:\fR The package has not sofar been tested extensively, and that may result in
an unexpected appearance if you use sizes that are different than the defaults. Also
not all options for the coloring of the various parts and fonts and so on have been tested, so that
may be another source of bugs.
.PP
A last note: some parts have not been included in any option, most notably the colors of
parts that require lighter and darker shades to cooperate.
.SH "TYPES OF WIDGETS"
The package distinguishes several typed of widgets:
.IP \(bu
Vertical meters: the value of the variable is translated into a vertical position, like with
the coloured bars you find on your stereo installation.
.IP \(bu
Angle displays: the value of the variable is related to the angle of a needle, like with tachometers.
.IP \(bu
Interactive widgets: most widgets allow you to change the value of the variable by pressing the mouse button
on the needle and shifting it up and down or left and right.
.IP \(bu
Non-interactive widgets: some widgets, like the thermometer widget, do not allow such interaction.
.IP \(bu
Logical or choice widgets: some widgets display the values as either on/off (or true/false) or as
one of a set of discrete choices.
.PP
All widgets have in common, however, that you can connect them to a variable and that changing the variable
changes the display. Forthermore, all widgets have the set and get methods to interact with the value that
the widget displays (whether that is stored in a global variable or not).
.PP
They also have in common that their appearance and behaviour is determined by one or more options that
you can set at creation time and often later on as well. The widgets are all based on the \fIsnit\fR
package, so that the methods \fBconfigure\fR and \fBcget\fR are available to set and get these options.
.SH COMMANDS
Currently the package contains these widgets of the \fIvertical meter\fR type:
.TP
\fB::controlwidget::meter\fR \fIw\fR \fIargs\fR
Create a vertical meter consisting of an axis and a moveable arrow.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the meter
................................................................................
.TP
\fBreadonly\fR boolean
Whether the arrow can be moved interactively or not
.RE
.RE
.TP
\fB::controlwidget::slider\fR \fIw\fR \fIargs\fR
Create a widget containing one or more vertical sliders and an axis. You can shift the slider handles
interactively via the mouse.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the (list) variable to be associated with the widget
................................................................................
.TP
\fBtroughwidth\fR color
Width of the troughs holding the sliders
.RE
.RE
.TP
\fB::controlwidget::equalizerBar\fR \fIw\fR \fIargs\fR
Create a widget containing one or more vertical bars resembling those found on hifi graphical equalizers.
Note that it is a read-only widget.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the (list) variable to be associated with the widget
................................................................................
.RE
.TP
\fB::controlwidget::thermometer\fR \fIw\fR \fIargs\fR
Create a thermometer widget (read-only)
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the (list) variable to be associated with the widget
................................................................................
.TP
\fBlog\fR boolean
Use a logarithmic axis (true) or a linear axis (false)
.PP
The package contains the following widget based on angle displays:
.TP
\fB::controlwidget::voltmeter\fR \fIw\fR \fIargs\fR
Create a voltmeter-like widget.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the meter
................................................................................
\fBmin\fR value
The minimum value for data in the display
.TP
\fBmax\fR value
The maximum value for data in the display
.TP
\fBlabels\fR list
The labels to be shown along the scale. (These are simply considered texts, so no
relation with the minimum and maximum perse)
.TP
\fBtitle\fR string
String to be shown below the dial
.TP
\fBwidth\fR pixels
The width of the widget
................................................................................
.TP
\fBtitlecolor\fR color
Color of the title below the dial
.RE
.RE
.TP
\fB::controlwidget::tachometer\fR \fIw\fR \fIargs\fR
Create a tachometer-like widget.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget. In addition
to the ones given for the voltmeter widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the meter
.TP
\fBvalue\fR value
................................................................................
.TP
\fBpincolor\fR color
Color for the needle and the pin
.RE
.RE
.TP
\fB::controlwidget::rdial\fR \fIw\fR \fIargs\fR
Create a rotating dial. You can drag the dial to change the value. With the shift button
depressed the value changes slowly, with the control button depressed it changes fast.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the dial
................................................................................
.PP
All these widgets have the following methods:
.TP
\fB$widget\fR get
Return the current value or values shown in the widget
.TP
\fB$widget\fR set \fIvalue\fR
Reset the value or values shown in the widget. If the widget is associated with
a variable, that variable is set as well.
.RS
.TP
value \fIdouble/list\fR
New value or values for the widget
.RE
.PP
Two further widgets are available, meant to display logical values:
.TP
\fB::controlwidget::led\fR \fIw\fR \fIargs\fR
Create a LED-like widget.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget. In addition
to the ones given for the voltmeter widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the LED
.TP
\fBsize\fR pixels
................................................................................
.TP
\fBoff\fR color
Color to use for the "off" state
.RE
.RE
.TP
\fB::controlwidget::radioMatrix\fR \fIw\fR \fIargs\fR
Create a matrix of radio buttons that behaves as a single widget.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget. In addition
to the ones given for the voltmeter widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the matrix
.TP
\fBorient\fR string
................................................................................
\fBrows\fR integer
Number of rows in the matrix
.TP
\fBcolumns\fR integer
Number of columns in the matrix
.TP
\fBcommand\fR list
Command associated with the radio buttons. Invoked when the active radio button changes.
.RE
.RE
.PP
The LED widget has the following public methods:
.TP
\fB$led\fR on
Set the state to "on"
................................................................................
.RS
.TP
index \fIinteger\fR
Index of the radio button to be set
.RE
.PP
.SH ACKNOWLEDGMENTS
The code for most of these widgets first appeared on the Wiki. In many cases, Arjen Markus merely
refactored the code a bit and "snitified" some of them. The original code was developed by the following people:
.IP \(bu
Vertical meter, LED display, radio matrix: Ron Fox
.IP \(bu
Rotating dials: Gerhard Reithofer
.IP \(bu
Voltmeter and tachometer: Marco Maggi
.IP \(bu
Code for moving the needle: ?
.PP
.SH KEYWORDS
controlling, displaying, numerical values, scale widget
.SH COPYRIGHT
.nf
Copyright (c) 2010 Ron Fox <rfox@...>
Copyright (c) 2010 Gerhard Reithofer <...@...>
Copyright (c) 2010 Marco Maggi <...@...>
Copyright (c) 2010 Arjen Markus <arjenmarkus@users.sourceforge.net>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/controlwidget/controlwidget\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2010 Ron Fox <rfox@\&.\&.\&.>
'\" Copyright (c) 2010 Gerhard Reithofer <\&.\&.\&.@\&.\&.\&.>
'\" Copyright (c) 2010 Marco Maggi <\&.\&.\&.@\&.\&.\&.>
'\" Copyright (c) 2010 Arjen Markus <arjenmarkus@users\&.sourceforge\&.net>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "controlwidget" n 0\&.1 tklib "controlwidget"
.BS
.SH NAME
controlwidget \- Collection of widgets for displaying and controlling numerical values
.SH SYNOPSIS
package require \fBTcl  ?8\&.5?\fR
.sp
package require \fBTk  ?8\&.5?\fR
.sp
package require \fBsnit  ?2\&.0?\fR
.sp
package require \fBcontrolwidget  ?0\&.1?\fR
.sp
\fB::controlwidget::meter\fR \fIw\fR \fIargs\fR
.sp
\fB::controlwidget::slider\fR \fIw\fR \fIargs\fR
.sp
\fB::controlwidget::equalizerBar\fR \fIw\fR \fIargs\fR
.sp
................................................................................
\fB$matrix\fR get
.sp
\fB$matrix\fR set \fIindex\fR
.sp
.BE
.SH DESCRIPTION
.PP
The controlwidget package focuses on the display and interactive control of numerical values\&.
It mimicks several of the meters and controls found in laboratory settings but also
daily life: volt meters, equalizers and tachometers to name a few\&. They can be seen as alternatives
for the \fIscale widget\fR\&.
.PP
\fINote:\fR The package has not sofar been tested extensively, and that may result in
an unexpected appearance if you use sizes that are different than the defaults\&. Also
not all options for the coloring of the various parts and fonts and so on have been tested, so that
may be another source of bugs\&.
.PP
A last note: some parts have not been included in any option, most notably the colors of
parts that require lighter and darker shades to cooperate\&.
.SH "TYPES OF WIDGETS"
The package distinguishes several typed of widgets:
.IP \(bu
Vertical meters: the value of the variable is translated into a vertical position, like with
the coloured bars you find on your stereo installation\&.
.IP \(bu
Angle displays: the value of the variable is related to the angle of a needle, like with tachometers\&.
.IP \(bu
Interactive widgets: most widgets allow you to change the value of the variable by pressing the mouse button
on the needle and shifting it up and down or left and right\&.
.IP \(bu
Non-interactive widgets: some widgets, like the thermometer widget, do not allow such interaction\&.
.IP \(bu
Logical or choice widgets: some widgets display the values as either on/off (or true/false) or as
one of a set of discrete choices\&.
.PP
All widgets have in common, however, that you can connect them to a variable and that changing the variable
changes the display\&. Forthermore, all widgets have the set and get methods to interact with the value that
the widget displays (whether that is stored in a global variable or not)\&.
.PP
They also have in common that their appearance and behaviour is determined by one or more options that
you can set at creation time and often later on as well\&. The widgets are all based on the \fIsnit\fR
package, so that the methods \fBconfigure\fR and \fBcget\fR are available to set and get these options\&.
.SH COMMANDS
Currently the package contains these widgets of the \fIvertical meter\fR type:
.TP
\fB::controlwidget::meter\fR \fIw\fR \fIargs\fR
Create a vertical meter consisting of an axis and a moveable arrow\&.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created\&.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the meter
................................................................................
.TP
\fBreadonly\fR boolean
Whether the arrow can be moved interactively or not
.RE
.RE
.TP
\fB::controlwidget::slider\fR \fIw\fR \fIargs\fR
Create a widget containing one or more vertical sliders and an axis\&. You can shift the slider handles
interactively via the mouse\&.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created\&.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the (list) variable to be associated with the widget
................................................................................
.TP
\fBtroughwidth\fR color
Width of the troughs holding the sliders
.RE
.RE
.TP
\fB::controlwidget::equalizerBar\fR \fIw\fR \fIargs\fR
Create a widget containing one or more vertical bars resembling those found on hifi graphical equalizers\&.
Note that it is a read-only widget\&.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created\&.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the (list) variable to be associated with the widget
................................................................................
.RE
.TP
\fB::controlwidget::thermometer\fR \fIw\fR \fIargs\fR
Create a thermometer widget (read-only)
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created\&.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the (list) variable to be associated with the widget
................................................................................
.TP
\fBlog\fR boolean
Use a logarithmic axis (true) or a linear axis (false)
.PP
The package contains the following widget based on angle displays:
.TP
\fB::controlwidget::voltmeter\fR \fIw\fR \fIargs\fR
Create a voltmeter-like widget\&.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created\&.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the meter
................................................................................
\fBmin\fR value
The minimum value for data in the display
.TP
\fBmax\fR value
The maximum value for data in the display
.TP
\fBlabels\fR list
The labels to be shown along the scale\&. (These are simply considered texts, so no
relation with the minimum and maximum perse)
.TP
\fBtitle\fR string
String to be shown below the dial
.TP
\fBwidth\fR pixels
The width of the widget
................................................................................
.TP
\fBtitlecolor\fR color
Color of the title below the dial
.RE
.RE
.TP
\fB::controlwidget::tachometer\fR \fIw\fR \fIargs\fR
Create a tachometer-like widget\&.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created\&.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget\&. In addition
to the ones given for the voltmeter widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the meter
.TP
\fBvalue\fR value
................................................................................
.TP
\fBpincolor\fR color
Color for the needle and the pin
.RE
.RE
.TP
\fB::controlwidget::rdial\fR \fIw\fR \fIargs\fR
Create a rotating dial\&. You can drag the dial to change the value\&. With the shift button
depressed the value changes slowly, with the control button depressed it changes fast\&.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created\&.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the dial
................................................................................
.PP
All these widgets have the following methods:
.TP
\fB$widget\fR get
Return the current value or values shown in the widget
.TP
\fB$widget\fR set \fIvalue\fR
Reset the value or values shown in the widget\&. If the widget is associated with
a variable, that variable is set as well\&.
.RS
.TP
value \fIdouble/list\fR
New value or values for the widget
.RE
.PP
Two further widgets are available, meant to display logical values:
.TP
\fB::controlwidget::led\fR \fIw\fR \fIargs\fR
Create a LED-like widget\&.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created\&.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget\&. In addition
to the ones given for the voltmeter widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the LED
.TP
\fBsize\fR pixels
................................................................................
.TP
\fBoff\fR color
Color to use for the "off" state
.RE
.RE
.TP
\fB::controlwidget::radioMatrix\fR \fIw\fR \fIargs\fR
Create a matrix of radio buttons that behaves as a single widget\&.
.RS
.TP
widget \fIw\fR (in)
Name of the widget to be created\&.
.TP
arguments \fIargs\fR (in)
List of key-value pairs, controlling the appearance and behaviour of the widget\&. In addition
to the ones given for the voltmeter widget:
.RS
.TP
\fBvariable\fR name
Name of the variable to be associated with the matrix
.TP
\fBorient\fR string
................................................................................
\fBrows\fR integer
Number of rows in the matrix
.TP
\fBcolumns\fR integer
Number of columns in the matrix
.TP
\fBcommand\fR list
Command associated with the radio buttons\&. Invoked when the active radio button changes\&.
.RE
.RE
.PP
The LED widget has the following public methods:
.TP
\fB$led\fR on
Set the state to "on"
................................................................................
.RS
.TP
index \fIinteger\fR
Index of the radio button to be set
.RE
.PP
.SH ACKNOWLEDGMENTS
The code for most of these widgets first appeared on the Wiki\&. In many cases, Arjen Markus merely
refactored the code a bit and "snitified" some of them\&. The original code was developed by the following people:
.IP \(bu
Vertical meter, LED display, radio matrix: Ron Fox
.IP \(bu
Rotating dials: Gerhard Reithofer
.IP \(bu
Voltmeter and tachometer: Marco Maggi
.IP \(bu
Code for moving the needle: ?
.PP
.SH KEYWORDS
controlling, displaying, numerical values, scale widget
.SH COPYRIGHT
.nf
Copyright (c) 2010 Ron Fox <rfox@\&.\&.\&.>
Copyright (c) 2010 Gerhard Reithofer <\&.\&.\&.@\&.\&.\&.>
Copyright (c) 2010 Marco Maggi <\&.\&.\&.@\&.\&.\&.>
Copyright (c) 2010 Arjen Markus <arjenmarkus@users\&.sourceforge\&.net>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/crosshair/crosshair.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2003 Kevin Kenny
'\" Copyright (c) 2008 (docs) Andreas Kupries <andreas_kupries@users.sourceforge.net>
'\" Copyright (c) 2013 Frank Gover, Andreas Kupries
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "crosshair" n 1.1 tklib "Crosshairs"
.BS
.SH NAME
crosshair \- Crosshairs for Tk canvas
.SH SYNOPSIS
package require \fBTcl  ?8.4?\fR
.sp
package require \fBTk  ?8.4?\fR
.sp
package require \fBcrosshair  ?1.1?\fR
.sp
\fBcrosshair::crosshair\fR \fIw\fR ?\fIarg\fR...?
.sp
\fBcrosshair::off\fR \fIw\fR
.sp
\fBcrosshair::configure\fR \fIw\fR ?\fIarg\fR...?
.sp
\fBcrosshair::track\fR \fBon\fR \fIw\fR \fIcmdprefix\fR
.sp
\fBcrosshair::track\fR \fBoff\fR \fIw\fR
.sp
\fBcrosshair::bbox_add\fR \fIw\fR \fIbbox\fR
.sp
\fBcrosshair::bbox_remove\fR \fItoken\fR
.sp
.BE
.SH DESCRIPTION
The \fBcrosshair\fR package provides commands to (de)activate and
track crosshairs on canvas widgets.
.SH API
The following commands are exported to the public:
.TP
\fBcrosshair::crosshair\fR \fIw\fR ?\fIarg\fR...?
This command activates the display of a pair of cross-hairs for the
canvas widget \fIw\fR. The cross-hairs track the pointing device. The
result of the command is the empty string.
.sp
All arguments after the widget \fIw\fR are treated as options as for a
canvas line item in \fIw\fR. Of particular interest are \fB-fill\fR
and \fB-dash\fR.
.TP
\fBcrosshair::off\fR \fIw\fR
This command removes the cross-hairs from the canvas widget \fIw\fR.
Nothing is done if the widget had no cross-hairs. The result of the
command is the empty string.
.TP
\fBcrosshair::configure\fR \fIw\fR ?\fIarg\fR...?
This command changes the appearance of the cross-hairs in the canvas
widget \fIw\fR. It is an error to call it for a canvas which has no
cross-hairs.
.sp
All arguments after the widget \fIw\fR are treated as options as for a
canvas line item in \fIw\fR. Of particular interest are \fB-fill\fR
and \fB-dash\fR.
.sp
The result of the command are the current configuration settings.
.TP
\fBcrosshair::track\fR \fBon\fR \fIw\fR \fIcmdprefix\fR
This command activates reporting of the location of the cross-hairs in
the canvas widget \fIw\fR. It is an error to use this command for a
canvas which has no cross-hairs. The result of the command is the
empty string.
.sp
After the invokation of this command the specified command prefix
\fIcmdprefix\fR will be called whenever the mouse moves within the
canvas, with 7 arguments. These are, in order:
.RS
.IP [1]
The widget \fIw\fR
.IP [2]
The x-location of the cross-hairs, in pixels.
.IP [3]
The y-location of the cross-hairs, in pixels.
.IP [4]
The x-location of the top-left corner of the viewport, in pixels.
.IP [5]
The y-location of the top-left corner of the viewport, in pixels.
.IP [6]
The x-location of the bottom-right corner of the viewport, in pixels.
.IP [7]
The y-location of the bottom-right corner of the viewport, in pixels.
.RE
.IP
A previously existing callback for \fIw\fR will be disabled. I.e. per
canvas widget with cross-hairs only one callback reporting their
location is possible.
.TP
\fBcrosshair::track\fR \fBoff\fR \fIw\fR
This command disables the reporting of the location of the cross-hairs
in the canvas widget \fIw\fR. It is an error to use this command for a
canvas which has no cross-hairs. The result of the command is the
empty string.
.TP
\fBcrosshair::bbox_add\fR \fIw\fR \fIbbox\fR
This command adds a bounding box to the crosshairs for canvas \fIw\fR.
The crosshairs will only be active within that area.
.sp
The result of the command is a token with which the bounding
box can be removed again, see \fBcrosshair::bbox_remove\fR below.
.sp
The bounding box \fIbbox\fR is specified thorugh a list of 4
values, the lower left and upper right corners of the box. The order
of values in the list is:
.CS

llx lly urx ury
.CE
.sp
Note that this command can be used multiple times, each call
adding one more bounding box. In such a case the visible area is the
\fIunion\fR of all the specified bounding boxes.
.TP
\fBcrosshair::bbox_remove\fR \fItoken\fR
This command removes the bounding box specified by the \fItoken\fR (a
result of \fBcrosshair::bbox_add\fR) from the crosshairs for its
canvas widget.
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category \fItklib :: crosshair\fR of the
\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
.SH KEYWORDS
canvas, cross-hairs, location, tracking, viewport
.SH COPYRIGHT
.nf
Copyright (c) 2003 Kevin Kenny
Copyright (c) 2008 (docs) Andreas Kupries <andreas_kupries@users.sourceforge.net>
Copyright (c) 2013 Frank Gover, Andreas Kupries

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/crosshair/crosshair\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2003 Kevin Kenny
'\" Copyright (c) 2008 (docs) Andreas Kupries <andreas_kupries@users\&.sourceforge\&.net>
'\" Copyright (c) 2013 Frank Gover, Andreas Kupries
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "crosshair" n 1\&.1 tklib "Crosshairs"
.BS
.SH NAME
crosshair \- Crosshairs for Tk canvas
.SH SYNOPSIS
package require \fBTcl  ?8\&.4?\fR
.sp
package require \fBTk  ?8\&.4?\fR
.sp
package require \fBcrosshair  ?1\&.1?\fR
.sp
\fBcrosshair::crosshair\fR \fIw\fR ?\fIarg\fR\&.\&.\&.?
.sp
\fBcrosshair::off\fR \fIw\fR
.sp
\fBcrosshair::configure\fR \fIw\fR ?\fIarg\fR\&.\&.\&.?
.sp
\fBcrosshair::track\fR \fBon\fR \fIw\fR \fIcmdprefix\fR
.sp
\fBcrosshair::track\fR \fBoff\fR \fIw\fR
.sp
\fBcrosshair::bbox_add\fR \fIw\fR \fIbbox\fR
.sp
\fBcrosshair::bbox_remove\fR \fItoken\fR
.sp
.BE
.SH DESCRIPTION
The \fBcrosshair\fR package provides commands to (de)activate and
track crosshairs on canvas widgets\&.
.SH API
The following commands are exported to the public:
.TP
\fBcrosshair::crosshair\fR \fIw\fR ?\fIarg\fR\&.\&.\&.?
This command activates the display of a pair of cross-hairs for the
canvas widget \fIw\fR\&. The cross-hairs track the pointing device\&. The
result of the command is the empty string\&.
.sp
All arguments after the widget \fIw\fR are treated as options as for a
canvas line item in \fIw\fR\&. Of particular interest are \fB-fill\fR
and \fB-dash\fR\&.
.TP
\fBcrosshair::off\fR \fIw\fR
This command removes the cross-hairs from the canvas widget \fIw\fR\&.
Nothing is done if the widget had no cross-hairs\&. The result of the
command is the empty string\&.
.TP
\fBcrosshair::configure\fR \fIw\fR ?\fIarg\fR\&.\&.\&.?
This command changes the appearance of the cross-hairs in the canvas
widget \fIw\fR\&. It is an error to call it for a canvas which has no
cross-hairs\&.
.sp
All arguments after the widget \fIw\fR are treated as options as for a
canvas line item in \fIw\fR\&. Of particular interest are \fB-fill\fR
and \fB-dash\fR\&.
.sp
The result of the command are the current configuration settings\&.
.TP
\fBcrosshair::track\fR \fBon\fR \fIw\fR \fIcmdprefix\fR
This command activates reporting of the location of the cross-hairs in
the canvas widget \fIw\fR\&. It is an error to use this command for a
canvas which has no cross-hairs\&. The result of the command is the
empty string\&.
.sp
After the invokation of this command the specified command prefix
\fIcmdprefix\fR will be called whenever the mouse moves within the
canvas, with 7 arguments\&. These are, in order:
.RS
.IP [1]
The widget \fIw\fR
.IP [2]
The x-location of the cross-hairs, in pixels\&.
.IP [3]
The y-location of the cross-hairs, in pixels\&.
.IP [4]
The x-location of the top-left corner of the viewport, in pixels\&.
.IP [5]
The y-location of the top-left corner of the viewport, in pixels\&.
.IP [6]
The x-location of the bottom-right corner of the viewport, in pixels\&.
.IP [7]
The y-location of the bottom-right corner of the viewport, in pixels\&.
.RE
.IP
A previously existing callback for \fIw\fR will be disabled\&. I\&.e\&. per
canvas widget with cross-hairs only one callback reporting their
location is possible\&.
.TP
\fBcrosshair::track\fR \fBoff\fR \fIw\fR
This command disables the reporting of the location of the cross-hairs
in the canvas widget \fIw\fR\&. It is an error to use this command for a
canvas which has no cross-hairs\&. The result of the command is the
empty string\&.
.TP
\fBcrosshair::bbox_add\fR \fIw\fR \fIbbox\fR
This command adds a bounding box to the crosshairs for canvas \fIw\fR\&.
The crosshairs will only be active within that area\&.
.sp
The result of the command is a token with which the bounding
box can be removed again, see \fBcrosshair::bbox_remove\fR below\&.
.sp
The bounding box \fIbbox\fR is specified thorugh a list of 4
values, the lower left and upper right corners of the box\&. The order
of values in the list is:
.CS

llx lly urx ury
.CE
.sp
Note that this command can be used multiple times, each call
adding one more bounding box\&. In such a case the visible area is the
\fIunion\fR of all the specified bounding boxes\&.
.TP
\fBcrosshair::bbox_remove\fR \fItoken\fR
This command removes the bounding box specified by the \fItoken\fR (a
result of \fBcrosshair::bbox_add\fR) from the crosshairs for its
canvas widget\&.
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such in the category \fItklib :: crosshair\fR of the
\fITcllib SF Trackers\fR [http://sourceforge\&.net/tracker/?group_id=12883]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH KEYWORDS
canvas, cross-hairs, location, tracking, viewport
.SH COPYRIGHT
.nf
Copyright (c) 2003 Kevin Kenny
Copyright (c) 2008 (docs) Andreas Kupries <andreas_kupries@users\&.sourceforge\&.net>
Copyright (c) 2013 Frank Gover, Andreas Kupries

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ctext/ctext.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) George Peter Staplin <GeorgePS@XMission.com>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ctext" n 3.3 tklib "Ctext a text widget with highlighting support"
.BS
.SH NAME
ctext \- Ctext a text widget with highlighting support
.SH SYNOPSIS
package require \fBTk \fR
.sp
package require \fBctext  ?3.3?\fR
.sp
\fBctext\fR \fIpathName\fR ?\fIoptions\fR?
.sp
\fB::ctext::addHighlightClass\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIkeywordlist\fR
.sp
\fB::ctext::addHighlightClassWithOnlyCharStart\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIchar\fR
.sp
................................................................................
.sp
\fIpathName\fR \fBcut\fR
.sp
\fIpathName\fR \fBpaste\fR
.sp
\fIpathName\fR \fBappend\fR
.sp
\fIpathName\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR ?...?
.sp
.BE
.SH DESCRIPTION
The \fBctext\fR package provides the ctext widget which
is an enhanced text widget with support for configurable syntax
highlighting and some extra commands.
.PP
Ctext overloads the text widget and provides
new commands, named \fBhighlight\fR, \fBcopy\fR, \fBpaste\fR,\fBcut\fR,
\fBappend\fR, and \fBedit\fR.  It also provides several
commands that allow you to define classes.
Each class corresponds to a tag in the widget.
.SH COMMANDS
.TP
\fBctext\fR \fIpathName\fR ?\fIoptions\fR?
Creates and configures a ctext widget.
.PP
.SH HIGHLIGHTING
Highlighting is controlled with text widget tags, that are called highlight classes.
The \fIclass\fR is a tag name and can be configured like any text widget tag.
Four types of highlight classes are supported. All highlight classes are automatically used
by the \fBhighlight\fR method of the widget.
.TP
\fB::ctext::addHighlightClass\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIkeywordlist\fR
Add a highlighting class \fIclass\fR to the ctext widget \fIpathName\fR.
The highligthing will be done with the color \fIcolor\fR. All words in the \fIkeywordlist\fR will be
highlighted.
.CS


	# highlight some tcl keywords
	::ctext::addHighlightClass .t tclkeywords red [list set info interp uplevel upvar]]

.CE
.TP
\fB::ctext::addHighlightClassWithOnlyCharStart\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIchar\fR
Add a highlighting class \fIclass\fR to the ctext widget \fIpathName\fR.
The highligthing will be done with the color \fIcolor\fR. All words starting with \fIchar\fR will be
highlighted.
.CS


	::ctext::addHighlightClassWithOnlyCharStart .t vars blue \\$

.CE
.TP
\fB::ctext::addHighlightClassForSpecialChars\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIcharstring\fR
Add a highlighting class \fIclass\fR to the ctext widget \fIpathName\fR.
The highligthing will be done with the color \fIcolor\fR. All chars in \fIcharstring\fR will be
highlighted.
.TP
\fB::ctext::addHighlightClassForRegexp\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIpattern\fR
Add a highlighting class \fIclass\fR to the ctext widget \fIpathName\fR.
The highligthing will be done with the color \fIcolor\fR. All text parts matching the regexp \fIpattern\fR
will be highligthed.
.TP
\fB::ctext::clearHighlightClasses\fR \fIpathName\fR
Remove all highlight classes from the widget \fIpathName\fR.
.TP
\fB::ctext::getHighlightClasses\fR \fIpathName\fR
List all highlight classes for the widget \fIpathName\fR.
.TP
\fB::ctext::deleteHighlightClass\fR \fIpathName\fR \fIclass\fR
Delete the highlight class \fIclass\fR from the widget \fIpathName\fR
.TP
\fB::ctext::enableComments\fR \fIenable\fR
Enable C comment highlighting. The \fIclass\fR for c-style comments is \fB_cComment\fR.
The C comment highlighting is disabled by default.
.TP
\fB::ctext::disableComments\fR \fIenable\fR
Disable C comment highlighting.
.PP
.SH "WIDGET COMMANDS"
Each ctext widget created with the above command supports the following
commands and options in addition to the standard text widget commands and
options.
.TP
\fIpathName\fR \fBhighlight\fR \fIstartIndex\fR \fIendIndex\fR
Highlight the text between \fIstartIndex\fR and \fIendIndex\fR.
.TP
\fIpathName\fR \fBfastdelete\fR \fIindex1\fR ?\fIindex2\fR?
Delete text range without updating the highlighting. Arguments
are identical to the \fIpathName\fR \fBdelete\fR command inherited from
the standard text widget.
.TP
\fIpathName\fR \fBfastinsert\fR
Insert text without updating the highlighting. Arguments
are identical to the \fIpathName\fR \fBinsert\fR command inherited from
the standard text widget.
.TP
\fIpathName\fR \fBcopy\fR
Call \fBtk_textCopy\fR for the ctext instance.
.TP
\fIpathName\fR \fBcut\fR
Call \fBtk_textCut\fR for the ctext instance.
.TP
\fIpathName\fR \fBpaste\fR
Call \fBtk_textPaste\fR for the ctext instance.
.TP
\fIpathName\fR \fBappend\fR
Append the current selection to the clipboard.
.TP
\fIpathName\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR ?...?
Set the options for the ctext widget. Each option name must be followed
the new value.
.PP
.SH "WIDGET OPTIONS"
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemap\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Creates (-linemap 1) or deletes (-linemap 0) a line number list on the
left of the widget. The default is to have a linemap displayed.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemapfg\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Changes the foreground of the linemap.
The default is the same color as the main text
widget.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemapbg\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Changes the background of the linemap.
The default is the same color as the main text
widget.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemap_select_fg\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Changes the selected
line foreground.  The default is black.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemap_select_bg\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Changes the selected line
background.  The default is yellow.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemap_mark_command\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Calls a procedure or command
with the \fIpathName\fR of the ctext window, the \fItype\fR which is
either \fBmarked\fR or \fBunmarked\fR, and finally the line
number selected.
The proc prototype is:
.CS


proc linemark_cmd {win type line}.

.CE
.IP
See also
ctext_test_interactive.tcl
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-highlight\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Takes a boolean value which defines
whether or not to highlight text which is inserted
or deleted.  The default is 1.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemap_markable\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Takes a boolean value which
specifies whether or not lines in the linemap
are markable with the mouse.  The default is 1.
.PP
.SH EXAMPLE
.CS


	package require Tk
	package require ctext

	proc main {} {
	pack [frame .f] -fill both -expand 1
	pack [scrollbar .f.s -command {.f.t yview}] -side right -fill y

	pack [ctext .f.t -bg black -fg white -insertbackground yellow  -yscrollcommand {.f.s set}] -fill both -expand 1

	ctext::addHighlightClass .f.t widgets purple  [list ctext button label text frame toplevel  scrollbar checkbutton canvas listbox menu menubar menubutton  radiobutton scale entry message tk_chooseDir tk_getSaveFile  tk_getOpenFile tk_chooseColor tk_optionMenu]

	ctext::addHighlightClass .f.t flags orange  [list -text -command -yscrollcommand  -xscrollcommand -background -foreground -fg -bg  -highlightbackground -y -x -highlightcolor -relief -width  -height -wrap -font -fill -side -outline -style -insertwidth  -textvariable -activebackground -activeforeground -insertbackground  -anchor -orient -troughcolor -nonewline -expand -type -message  -title -offset -in -after -yscroll -xscroll -forward -regexp -count  -exact -padx -ipadx -filetypes -all -from -to -label -value -variable  -regexp -backwards -forwards -bd -pady -ipady -state -row -column  -cursor -highlightcolors -linemap -menu -tearoff -displayof -cursor  -underline -tags -tag]

	ctext::addHighlightClass .f.t stackControl red  {proc uplevel namespace while for foreach if else}
	ctext::addHighlightClassWithOnlyCharStart .f.t vars mediumspringgreen "\\$"
	ctext::addHighlightClass .f.t variable_funcs gold {set global variable unset}
	ctext::addHighlightClassForSpecialChars .f.t brackets green {[]{}}
	ctext::addHighlightClassForRegexp .f.t paths lightblue {\\.[a-zA-Z0-9\\_\\-]+}
	ctext::addHighlightClassForRegexp .f.t comments khaki {#[^\\n\\r]*}
	.f.t fastinsert end [info body main]

	pack [frame .f1] -fill x

	.f.t highlight 1.0 end

	pack [button .f1.exit -text Exit -command exit] -side left

	pack [entry .e] -side bottom -fill x
	.e insert end "ctext::deleteHighlightClass .f.t "
	bind .e <Return> {eval [.e get]}
	}
	main


.CE
Further examples are in the source package for ctext.
.SH THANKS
Kevin Kenny, Neil Madden, Jeffrey Hobbs, Richard Suchenwirth,
Johan Bengtsson, Mac Cody, Günther, Andreas Sievers, and Michael Schlenker.
.SH "SEE ALSO"
re_syntax, text
.SH KEYWORDS
syntax highlighting, text, widget
.SH COPYRIGHT
.nf
Copyright (c) George Peter Staplin <GeorgePS@XMission.com>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ctext/ctext\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) George Peter Staplin <GeorgePS@XMission\&.com>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ctext" n 3\&.3 tklib "Ctext a text widget with highlighting support"
.BS
.SH NAME
ctext \- Ctext a text widget with highlighting support
.SH SYNOPSIS
package require \fBTk \fR
.sp
package require \fBctext  ?3\&.3?\fR
.sp
\fBctext\fR \fIpathName\fR ?\fIoptions\fR?
.sp
\fB::ctext::addHighlightClass\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIkeywordlist\fR
.sp
\fB::ctext::addHighlightClassWithOnlyCharStart\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIchar\fR
.sp
................................................................................
.sp
\fIpathName\fR \fBcut\fR
.sp
\fIpathName\fR \fBpaste\fR
.sp
\fIpathName\fR \fBappend\fR
.sp
\fIpathName\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR ?\&.\&.\&.?
.sp
.BE
.SH DESCRIPTION
The \fBctext\fR package provides the ctext widget which
is an enhanced text widget with support for configurable syntax
highlighting and some extra commands\&.
.PP
Ctext overloads the text widget and provides
new commands, named \fBhighlight\fR, \fBcopy\fR, \fBpaste\fR,\fBcut\fR,
\fBappend\fR, and \fBedit\fR\&.  It also provides several
commands that allow you to define classes\&.
Each class corresponds to a tag in the widget\&.
.SH COMMANDS
.TP
\fBctext\fR \fIpathName\fR ?\fIoptions\fR?
Creates and configures a ctext widget\&.
.PP
.SH HIGHLIGHTING
Highlighting is controlled with text widget tags, that are called highlight classes\&.
The \fIclass\fR is a tag name and can be configured like any text widget tag\&.
Four types of highlight classes are supported\&. All highlight classes are automatically used
by the \fBhighlight\fR method of the widget\&.
.TP
\fB::ctext::addHighlightClass\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIkeywordlist\fR
Add a highlighting class \fIclass\fR to the ctext widget \fIpathName\fR\&.
The highligthing will be done with the color \fIcolor\fR\&. All words in the \fIkeywordlist\fR will be
highlighted\&.
.CS


	# highlight some tcl keywords
	::ctext::addHighlightClass \&.t tclkeywords red [list set info interp uplevel upvar]]

.CE
.TP
\fB::ctext::addHighlightClassWithOnlyCharStart\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIchar\fR
Add a highlighting class \fIclass\fR to the ctext widget \fIpathName\fR\&.
The highligthing will be done with the color \fIcolor\fR\&. All words starting with \fIchar\fR will be
highlighted\&.
.CS


	::ctext::addHighlightClassWithOnlyCharStart \&.t vars blue \\$

.CE
.TP
\fB::ctext::addHighlightClassForSpecialChars\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIcharstring\fR
Add a highlighting class \fIclass\fR to the ctext widget \fIpathName\fR\&.
The highligthing will be done with the color \fIcolor\fR\&. All chars in \fIcharstring\fR will be
highlighted\&.
.TP
\fB::ctext::addHighlightClassForRegexp\fR \fIpathName\fR \fIclass\fR \fIcolor\fR \fIpattern\fR
Add a highlighting class \fIclass\fR to the ctext widget \fIpathName\fR\&.
The highligthing will be done with the color \fIcolor\fR\&. All text parts matching the regexp \fIpattern\fR
will be highligthed\&.
.TP
\fB::ctext::clearHighlightClasses\fR \fIpathName\fR
Remove all highlight classes from the widget \fIpathName\fR\&.
.TP
\fB::ctext::getHighlightClasses\fR \fIpathName\fR
List all highlight classes for the widget \fIpathName\fR\&.
.TP
\fB::ctext::deleteHighlightClass\fR \fIpathName\fR \fIclass\fR
Delete the highlight class \fIclass\fR from the widget \fIpathName\fR
.TP
\fB::ctext::enableComments\fR \fIenable\fR
Enable C comment highlighting\&. The \fIclass\fR for c-style comments is \fB_cComment\fR\&.
The C comment highlighting is disabled by default\&.
.TP
\fB::ctext::disableComments\fR \fIenable\fR
Disable C comment highlighting\&.
.PP
.SH "WIDGET COMMANDS"
Each ctext widget created with the above command supports the following
commands and options in addition to the standard text widget commands and
options\&.
.TP
\fIpathName\fR \fBhighlight\fR \fIstartIndex\fR \fIendIndex\fR
Highlight the text between \fIstartIndex\fR and \fIendIndex\fR\&.
.TP
\fIpathName\fR \fBfastdelete\fR \fIindex1\fR ?\fIindex2\fR?
Delete text range without updating the highlighting\&. Arguments
are identical to the \fIpathName\fR \fBdelete\fR command inherited from
the standard text widget\&.
.TP
\fIpathName\fR \fBfastinsert\fR
Insert text without updating the highlighting\&. Arguments
are identical to the \fIpathName\fR \fBinsert\fR command inherited from
the standard text widget\&.
.TP
\fIpathName\fR \fBcopy\fR
Call \fBtk_textCopy\fR for the ctext instance\&.
.TP
\fIpathName\fR \fBcut\fR
Call \fBtk_textCut\fR for the ctext instance\&.
.TP
\fIpathName\fR \fBpaste\fR
Call \fBtk_textPaste\fR for the ctext instance\&.
.TP
\fIpathName\fR \fBappend\fR
Append the current selection to the clipboard\&.
.TP
\fIpathName\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR ?\&.\&.\&.?
Set the options for the ctext widget\&. Each option name must be followed
the new value\&.
.PP
.SH "WIDGET OPTIONS"
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemap\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Creates (-linemap 1) or deletes (-linemap 0) a line number list on the
left of the widget\&. The default is to have a linemap displayed\&.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemapfg\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Changes the foreground of the linemap\&.
The default is the same color as the main text
widget\&.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemapbg\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Changes the background of the linemap\&.
The default is the same color as the main text
widget\&.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemap_select_fg\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Changes the selected
line foreground\&.  The default is black\&.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemap_select_bg\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Changes the selected line
background\&.  The default is yellow\&.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemap_mark_command\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Calls a procedure or command
with the \fIpathName\fR of the ctext window, the \fItype\fR which is
either \fBmarked\fR or \fBunmarked\fR, and finally the line
number selected\&.
The proc prototype is:
.CS


proc linemark_cmd {win type line}\&.

.CE
.IP
See also
ctext_test_interactive\&.tcl
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-highlight\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Takes a boolean value which defines
whether or not to highlight text which is inserted
or deleted\&.  The default is 1\&.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-linemap_markable\fR
Database Name:	\fB\fR
Database Class:	\fB\fR

.fi
.IP
Takes a boolean value which
specifies whether or not lines in the linemap
are markable with the mouse\&.  The default is 1\&.
.PP
.SH EXAMPLE
.CS


	package require Tk
	package require ctext

	proc main {} {
	pack [frame \&.f] -fill both -expand 1
	pack [scrollbar \&.f\&.s -command {\&.f\&.t yview}] -side right -fill y

	pack [ctext \&.f\&.t -bg black -fg white -insertbackground yellow  -yscrollcommand {\&.f\&.s set}] -fill both -expand 1

	ctext::addHighlightClass \&.f\&.t widgets purple  [list ctext button label text frame toplevel  scrollbar checkbutton canvas listbox menu menubar menubutton  radiobutton scale entry message tk_chooseDir tk_getSaveFile  tk_getOpenFile tk_chooseColor tk_optionMenu]

	ctext::addHighlightClass \&.f\&.t flags orange  [list -text -command -yscrollcommand  -xscrollcommand -background -foreground -fg -bg  -highlightbackground -y -x -highlightcolor -relief -width  -height -wrap -font -fill -side -outline -style -insertwidth  -textvariable -activebackground -activeforeground -insertbackground  -anchor -orient -troughcolor -nonewline -expand -type -message  -title -offset -in -after -yscroll -xscroll -forward -regexp -count  -exact -padx -ipadx -filetypes -all -from -to -label -value -variable  -regexp -backwards -forwards -bd -pady -ipady -state -row -column  -cursor -highlightcolors -linemap -menu -tearoff -displayof -cursor  -underline -tags -tag]

	ctext::addHighlightClass \&.f\&.t stackControl red  {proc uplevel namespace while for foreach if else}
	ctext::addHighlightClassWithOnlyCharStart \&.f\&.t vars mediumspringgreen "\\$"
	ctext::addHighlightClass \&.f\&.t variable_funcs gold {set global variable unset}
	ctext::addHighlightClassForSpecialChars \&.f\&.t brackets green {[]{}}
	ctext::addHighlightClassForRegexp \&.f\&.t paths lightblue {\\\&.[a-zA-Z0-9\\_\\-]+}
	ctext::addHighlightClassForRegexp \&.f\&.t comments khaki {#[^\\n\\r]*}
	\&.f\&.t fastinsert end [info body main]

	pack [frame \&.f1] -fill x

	\&.f\&.t highlight 1\&.0 end

	pack [button \&.f1\&.exit -text Exit -command exit] -side left

	pack [entry \&.e] -side bottom -fill x
	\&.e insert end "ctext::deleteHighlightClass \&.f\&.t "
	bind \&.e <Return> {eval [\&.e get]}
	}
	main


.CE
Further examples are in the source package for ctext\&.
.SH THANKS
Kevin Kenny, Neil Madden, Jeffrey Hobbs, Richard Suchenwirth,
Johan Bengtsson, Mac Cody, Günther, Andreas Sievers, and Michael Schlenker\&.
.SH "SEE ALSO"
re_syntax, text
.SH KEYWORDS
syntax highlighting, text, widget
.SH COPYRIGHT
.nf
Copyright (c) George Peter Staplin <GeorgePS@XMission\&.com>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/cursor/cursor.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) Jeffrey Hobbs <jeff@hobbs.org>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "cursor" n 0.3.1 tklib "Tk cursor routines"
.BS
.SH NAME
cursor \- Procedures to handle CURSOR data
.SH SYNOPSIS
package require \fBTk \fR
.sp
package require \fBcursor  ?0.3.1?\fR
.sp
\fB::cursor::propagate\fR \fIwidget\fR \fIcursor\fR
.sp
\fB::cursor::restore\fR \fIwidget\fR ?\fIcursor\fR?
.sp
\fB::cursor::display\fR ?\fIparent\fR?
.sp
.BE
.SH DESCRIPTION
The \fBcursor\fR package provides commands to handle Tk cursors.
.SH COMMANDS
The following commands are available:
.TP
\fB::cursor::propagate\fR \fIwidget\fR \fIcursor\fR
Sets the cursor for the specified \fIwidget\fR and all its descendants
to \fIcursor\fR.
.TP
\fB::cursor::restore\fR \fIwidget\fR ?\fIcursor\fR?
Restore the original or previously set cursor for the specified
\fIwidget\fR and all its descendants.  If \fIcursor\fR is specified,
that will be used if on any widget that did not have a preset cursor
(set by a previous call to \fB::cursor::propagate\fR).
.TP
\fB::cursor::display\fR ?\fIparent\fR?
Pops up a dialog with a listbox containing all the cursor names.
Selecting a cursor name will display it in that dialog.  This is
simply for viewing any available cursors on the platform.
.PP
.SH "SEE ALSO"
Tk_GetCursor(3), cursors(n), options(n)
.SH KEYWORDS
cursor
.SH COPYRIGHT
.nf
Copyright (c) Jeffrey Hobbs <jeff@hobbs.org>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/cursor/cursor\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) Jeffrey Hobbs <jeff@hobbs\&.org>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "cursor" n 0\&.3\&.1 tklib "Tk cursor routines"
.BS
.SH NAME
cursor \- Procedures to handle CURSOR data
.SH SYNOPSIS
package require \fBTk \fR
.sp
package require \fBcursor  ?0\&.3\&.1?\fR
.sp
\fB::cursor::propagate\fR \fIwidget\fR \fIcursor\fR
.sp
\fB::cursor::restore\fR \fIwidget\fR ?\fIcursor\fR?
.sp
\fB::cursor::display\fR ?\fIparent\fR?
.sp
.BE
.SH DESCRIPTION
The \fBcursor\fR package provides commands to handle Tk cursors\&.
.SH COMMANDS
The following commands are available:
.TP
\fB::cursor::propagate\fR \fIwidget\fR \fIcursor\fR
Sets the cursor for the specified \fIwidget\fR and all its descendants
to \fIcursor\fR\&.
.TP
\fB::cursor::restore\fR \fIwidget\fR ?\fIcursor\fR?
Restore the original or previously set cursor for the specified
\fIwidget\fR and all its descendants\&.  If \fIcursor\fR is specified,
that will be used if on any widget that did not have a preset cursor
(set by a previous call to \fB::cursor::propagate\fR)\&.
.TP
\fB::cursor::display\fR ?\fIparent\fR?
Pops up a dialog with a listbox containing all the cursor names\&.
Selecting a cursor name will display it in that dialog\&.  This is
simply for viewing any available cursors on the platform\&.
.PP
.SH "SEE ALSO"
Tk_GetCursor(3), cursors(n), options(n)
.SH KEYWORDS
cursor
.SH COPYRIGHT
.nf
Copyright (c) Jeffrey Hobbs <jeff@hobbs\&.org>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/datefield/datefield.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) Keith Vetter <keith@ebook.gemstar.com>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "datefield" n 0.2 tklib "Tk datefield widget"
.BS
.SH NAME
datefield \- Tk datefield widget
.SH SYNOPSIS
package require \fBTk \fR
.sp
package require \fBdatefield  ?0.2?\fR
.sp
\fB::datefield::datefield\fR \fIwidgetpath\fR ?\fIoptions\fR?
.sp
.BE
.SH DESCRIPTION
The \fBdatefield\fR package provides the datefield widget which
is an enhanced text entry widget for the purpose of date entry. Only
valid dates of the form MM/DD/YYYY can be entered.
.PP
The datefield widget is, in fact, just an entry widget with
specialized bindings. This means all the command and options for an
entry widget apply equally here.
.SH COMMANDS
.TP
\fB::datefield::datefield\fR \fIwidgetpath\fR ?\fIoptions\fR?
Creates and configures a date field widget.
.PP
.SH OPTIONS
See the \fBentry\fR manual entry for details on all available options.
.SH EXAMPLE
.CS


 package require datefield

 wm title . "Datefield example"
 proc DayOfWeek {args} {
     set now [clock scan $::myDate]
     set ::myDate2 [clock format $now -format %A]
 }
 trace variable myDate w DayOfWeek

 ::datefield::datefield .df -textvariable myDate
 label .l1 -text "Enter a date:"   -anchor e
 label .l2 -text "That date is a:" -anchor e
 label .l3 -textvariable myDate2 -relief sunken -width 12

 grid .l1 .df -sticky ew
 grid .l2 .l3 -sticky ew
 focus .df

.CE
.SH "SEE ALSO"
clock(n), entry(n)
.SH KEYWORDS
clock, date, dateentry, entry, widget
.SH CATEGORY
Widget
.SH COPYRIGHT
.nf
Copyright (c) Keith Vetter <keith@ebook.gemstar.com>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/datefield/datefield\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) Keith Vetter <keith@ebook\&.gemstar\&.com>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "datefield" n 0\&.2 tklib "Tk datefield widget"
.BS
.SH NAME
datefield \- Tk datefield widget
.SH SYNOPSIS
package require \fBTk \fR
.sp
package require \fBdatefield  ?0\&.2?\fR
.sp
\fB::datefield::datefield\fR \fIwidgetpath\fR ?\fIoptions\fR?
.sp
.BE
.SH DESCRIPTION
The \fBdatefield\fR package provides the datefield widget which
is an enhanced text entry widget for the purpose of date entry\&. Only
valid dates of the form MM/DD/YYYY can be entered\&.
.PP
The datefield widget is, in fact, just an entry widget with
specialized bindings\&. This means all the command and options for an
entry widget apply equally here\&.
.SH COMMANDS
.TP
\fB::datefield::datefield\fR \fIwidgetpath\fR ?\fIoptions\fR?
Creates and configures a date field widget\&.
.PP
.SH OPTIONS
See the \fBentry\fR manual entry for details on all available options\&.
.SH EXAMPLE
.CS


 package require datefield

 wm title \&. "Datefield example"
 proc DayOfWeek {args} {
     set now [clock scan $::myDate]
     set ::myDate2 [clock format $now -format %A]
 }
 trace variable myDate w DayOfWeek

 ::datefield::datefield \&.df -textvariable myDate
 label \&.l1 -text "Enter a date:"   -anchor e
 label \&.l2 -text "That date is a:" -anchor e
 label \&.l3 -textvariable myDate2 -relief sunken -width 12

 grid \&.l1 \&.df -sticky ew
 grid \&.l2 \&.l3 -sticky ew
 focus \&.df

.CE
.SH "SEE ALSO"
clock(n), entry(n)
.SH KEYWORDS
clock, date, dateentry, entry, widget
.SH CATEGORY
Widget
.SH COPYRIGHT
.nf
Copyright (c) Keith Vetter <keith@ebook\&.gemstar\&.com>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/diagrams/diagram.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "diagram" n 0.3 tklib "Documentation toolbox"
.BS
.SH NAME
diagram \- Diagram drawing
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBdiagram  1\fR
.sp
\fB::diagram\fR \fIobjectName\fR \fIcanvas\fR ?\fIscript\fR?
.sp
\fIdiagramObject\fR \fBnew direction\fR \fIname\fR ?\fIkey\fR \fIvalue\fR...?
.sp
\fIdiagramObject\fR \fBnew element\fR \fIname\fR \fIattributes\fR \fIcmdprefix\fR
.sp
\fIdiagramObject\fR \fBnew alias\fR \fIname\fR \fIcmdprefix\fR
.sp
\fIdiagramObject\fR \fBnew command\fR \fIname\fR \fIarguments\fR \fIbody\fR
.sp
\fIdiagramObject\fR \fBnew attribute\fR \fIname\fR ?\fIkey\fR \fIvalue\fR...?
.sp
\fIdiagramObject\fR \fBunknown attribute\fR \fIcmdprefix\fR
.sp
\fIdiagramObject\fR \fBdraw\fR \fIscript\fR
.sp
\fBarc\fR \fIattr\fR...
.sp
\fBarrow\fR \fIattr\fR...
.sp
\fB-->\fR \fIattr\fR...
.sp
\fB<-->\fR \fIattr\fR...
.sp
\fB<-->\fR \fIattr\fR...
.sp
\fBblock\fR \fIscript\fR \fIattr\fR...
.sp
\fBbox\fR \fIattr\fR...
.sp
\fBcircle\fR \fIattr\fR...
.sp
\fBO\fR \fIattr\fR...
.sp
\fBdiamond\fR \fIattr\fR...
.sp
\fB<>\fR \fIattr\fR...
.sp
\fBdrum\fR \fIattr\fR...
.sp
\fBellipse\fR \fIattr\fR...
.sp
\fBline\fR \fIattr\fR...
.sp
\fB--\fR \fIattr\fR...
.sp
\fBmove\fR \fIattr\fR
.sp
\fBspline\fR \fIattr\fR...
.sp
\fBtext\fR \fIattr\fR...
.sp
\fBwest\fR
.sp
\fBw\fR
.sp
\fBleft\fR
.sp
................................................................................
.sp
\fBintersect\fR \fIelem1\fR \fIelem2\fR
.sp
\fIelement\fR \fBnames\fR ?\fIpattern\fR?
.sp
\fIelement\fR \fIcorner\fR
.sp
\fIelement\fR \fIcorner1\fR \fIcorner2\fR...
.sp
\fIelement\fR ?\fIcorner1\fR... ?\fBnames\fR ?\fIpattern\fR??]?
.sp
\fB\fBn\fRth\fR ?\fIcorner\fR?
.sp
\fB\fBn\fRth\fR \fBlast\fR ?\fIcorner\fR?
.sp
\fB\fBn\fRth\fR \fIshape\fR ?\fIcorner\fR?
.sp
................................................................................
\fB2nd\fR
.sp
\fB3rd\fR
.sp
.BE
.SH DESCRIPTION
Welcome to \fBdiagram\fR, a package for the easy construction of
diagrams (sic), i.e. 2D vector graphics, sometimes also called \fIpictures\fR.
Note that this package is not a replacement for \fBTk\fR's canvas,
but rather a layer sitting on top of it, to make it easier to use.
In other words, using the canvas as the core graphics engine \fBdiagram\fR abstracts away from the minutiae of handling coordinates to
position and size the drawn elements, allowing the user to concentrate
on the content of the diagram instead.
.PP
This is similar to Brian Kernighan's PIC language for troff, which is
the spiritual ancestor of this package.
.PP
This document contains the reference to the API and drawing (language)
commands. Its intended audience are users of the package wishing to
refresh their memory.
Newcomers should read the \fIDiagram Language Tutorial\fR first.
Developers wishing to work on the internals of the package and its
supporting packages should look at section
\fBDiagram Classes\fR
first, and then the comments in the sources of the packages itself.
.PP
In the remainder of the document we first describe the APIs of the
diagram class and its instances, followed by the language reference
for the drawing language itself.
.SH API
.SS "CLASS API"
The package exports the API described here.
.TP
\fB::diagram\fR \fIobjectName\fR \fIcanvas\fR ?\fIscript\fR?
The command creates a new instance of a diagram
controller and returns the fully qualified name of the
object command as its result.
The new instance is connected to the specified
\fIcanvas\fR object, which is used as the diagrams
graphics engine. This is usually an instance of Tk's
canvas, however any object which is API compatible to
Tk's canvas can be used here.
.sp
The API of this object command is described in the
following section, \fBObject API\fR. It may be
used to invoke various operations on the object.
.sp
If the \fIscript\fR argument is specified then method
\fBdraw\fR will be invoked on it.
.PP
.SS "OBJECT API"
Instances of the diagram class support the following
methods:
.TP
\fIdiagramObject\fR \fBnew direction\fR \fIname\fR ?\fIkey\fR \fIvalue\fR...?
This method defines a new named direction and its
attributes. The latter is given through the
\fIkey\fR/\fIvalue\fR pairs coming after the \fIname\fR.
.sp
Users are mostly free to specify arbitrary attributes
with whatever meaning they desire. The exception are
the names \fIangle\fR and \fIopposite\fR. They are
special to the diagram package and have a fixed meaning.
.RS
.TP
angle
This attribute specifies the angle of the direction in
degrees, where 0 points east (to the right) and 90 points
north (up).
.TP
opposite
This attribute specifies the name of the direction
which should be considered as complementary to the
named one.
.RE
.TP
\fIdiagramObject\fR \fBnew element\fR \fIname\fR \fIattributes\fR \fIcmdprefix\fR
This method defines a new graphics element for the
drawing language. I.e. \fIname\fR will become a new
command in the language, and the specified command
prefix (\fIcmdprefix\fR) will be called to perform
the actual drawing.
.sp
\fIattributes\fR specifies the set of attributes for which
data has to be available. I.e. the system will run the
...-callbacks for these attributes.
See the method \fBnew attribute\fR for more information
on attribute definitions.
.sp
The command prefix is expected to conform to the
following signature:
.RS
.TP
\fBcmdprefix\fR \fIcanvas\fR \fIattributes\fR
Where \fIcanvas\fR is the handle of the canvas widget
to draw to, and \fIattributes\fR is a dictionary
holding the attributes for the element, be they
user-specified, or defaults.
.sp
The results of the command has to be a list containing
at least two and at most four items. These are, in order:
.RS
.IP [1]
The list of canvas items the drawn element consists of.
.IP [2]
The dictionary of named locations in the element, its
\fIcorners\fR.
.IP [3]
An optional mode, either "relative" or "absolute".
When not returned "relative" is assumed. In the
case of a relative element position the attributes
"with" and "at" are used to determine the final
position of the new element.
.IP [4]
An optional name of a direction. If not the
empty string this is handed to the automatic
layouter as the new direction to follow.
.RE
.RE
.TP
\fIdiagramObject\fR \fBnew alias\fR \fIname\fR \fIcmdprefix\fR
This method defines a new command for the drawing
language. I.e. \fIname\fR will become a new command in
the language, and the specified command prefix
(\fIcmdprefix\fR) will be called on use of this new
command. Any arguments given to the command are
simply passed to the prefix. There is no fixed siganture.
.sp
Note that the prefix is run in the context of the
drawing language, allowing the direct use of any
existing commands.
.TP
\fIdiagramObject\fR \fBnew command\fR \fIname\fR \fIarguments\fR \fIbody\fR
This is like \fBnew alias\fR except that the new
command is defined as a procedure in the language's
context, with regular argument list and body.
.TP
\fIdiagramObject\fR \fBnew attribute\fR \fIname\fR ?\fIkey\fR \fIvalue\fR...?
This method defines a new named attribute which can be
used by graphical elements. The handling of the
attribute by the processor is declared through the
\fIkey\fR/\fIvalue\fR pairs coming after the \fIname\fR.
.sp
The accepted keys and their meanings are:
.RS
.TP
\fBkey\fR
The value of this key is the name of the key
under which the attribute's value shall be
stored in the attribute dictionary given to
the drawing command after attribute processing
is complete.
.sp
This key is optional. If it is not specified it
defaults to the name of the attribute.
.TP
\fBget\fR
The value of this key is a command prefix
which will be invoked to retrieve the
attribute's argument(s) from the command
line.
.sp
This key is optional. If it is not specified a
default is used which takes the single word
after the attribute name as the attribute's
value.
.sp
The signature of the command prefix is
.RS
.TP
\fBcmdprefix\fR \fIwordqueue\fR
Where \fIwordqueue\fR is the handle of
a queue object conforming to the API
of the queues provided by package
\fBstruct::queue\fR. This queue
contains the not-yet-processed part of
the attribute definitions, with one
entry per word, with the first entry
the word \fIafter\fR name of the
attribute. In other words, the
attribute's name has already been
removed from the queue.
.sp
The result of the command is the value
of the attribute, which may have been
taken from the queue, or not.
.RE
.TP
\fBtransform\fR
The value of this key is a command prefix
which will be invoked to transform the
retrieved value (See \fBget\fR) into their
final form.
.sp
This key is optional. If it is not specified
no transformation is done.
The signature of the command prefix is
.RS
.TP
\fBcmdprefix\fR \fIvalue\fR
Where \fIvalue\fR is the value to transform.
.sp
The result of the command is the final
value of the attribute.
.RE
.TP
\fBtype\fR
The value of this key is a command prefix
which will be invoked to validate the
attribute's argument(s).
.sp
This key is optional. If it is not specified
no validation is done.
.sp
The signature of the command prefix is that of
snit validation types. See the documentation
of the \fBsnit\fR package.
.TP
\fBmerge\fR
The value of this key is a command prefix
which will be invoked to insert the
transformed and validated attribute value into
the dictionary of collected attributes.
.sp
This key is optional. If it is not specified
a default merge is chosen, based on the data
for key \fBaggregate\fR, see below.
The signature of the command prefix is
.RS
.TP
\fBcmdprefix\fR \fIvalue\fR \fIdict\fR
Where \fIvalue\fR is the value to
insert, and \fIdict\fR the dictionary
of attributes and values collected so
far.
.sp
The result of the command is the new
dictionary of attributes.
.RE
.TP
\fBaggregate\fR
The value of this key is a boolean flag. It
has an effect if and only if the key \fBmerge\fR was not specified. This key is
optional. If it is not specified it defaults
to \fBFalse\fR.
.sp
If the key is effective, the value of \fBFalse\fR means that the attribute's value is
\fIset\fR into the dictionary using the value
of key \fIkey\fR (see above) as index,
\fIoverwriting\fR any previously specified value.
.sp
If the key is effective, the value of \fBTrue\fR means that the attribute's value is
\fIadded\fR to the dictionary using the value
of key \fIkey\fR (see above) as index,
\fIextending\fR any previously specified value.
This means that the final value of the
attribute as seen after processing will be a
list of the collected values.
.TP
\fBdefault\fR
The value of this key is a command prefix
which will be invoked after collection of
attributes has been completed and this
attribute is in the list of required
attributes for the drawing element (See
argument \fIattributes\fR of method
\fBnew element\fR).
.sp
Note that the connection is made through the
value of key \fIkey\fR, not through the
attribute name per se.
.sp
Further note that this command prefix is
invoked even if a user specified attribute
value is present. This allows the command
to go beyond simply setting defaults, it
can calculate and store derived values as
well.
.sp
This key is optional. If an element requires
this attribute, but \fIdefault\fR is not
specified then nothing will be done.
.sp
The signature of the command prefix is
.RS
.TP
\fBcmdprefix\fR \fBinit\fR
This method is run when the attribute
is defined, its responsibility is to
initialize anything in the language
namespace for the attribute and
default processing.
.sp
The result of this method is ignored.
.TP
\fBcmdprefix\fR \fBfill\fR \fIvarname\fR
This method is run to put defaults, or
derived values into the attribute dictionary
named by \fIvarname\fR. This variable will
be found in the calling context.
.sp
The result of this method is ignored.
.TP
\fBcmdprefix\fR \fBset\fR \fIname\fR \fIvalue\fR
This method is run to push current a
attribute value into the language
namespace, to make it the new default.
.sp
The result of this method is ignored.
.RE
.TP
\fBlinked\fR
This key is effective if and only if key
\fBdefault\fR is not specified. In that
case is supplies a default handling for
\fBdefault\fR, linking the attribute to a
variable in the language context.
.sp
The value for this key is a 2-element list
containing the name of the variable to link
to, and its initial value, in this order.
.RE
.TP
\fIdiagramObject\fR \fBunknown attribute\fR \fIcmdprefix\fR
This method registers the command prefix with the
subsystem processing the attributes for element
commands, telling it to call it when it encounters an
attribute it is unable to handle on its on.
.sp
It is allowed to register more than callback, these
will be called in order of registration (i.e. first to
last), until one of the callbacks accepts the current
input.
The command prefix is expected to conform to the
following signature:
.RS
.TP
\fBcmdprefix\fR \fIwordqueue\fR
Where \fIwordqueue\fR is the handle of a queue
object conforming to the API of the queues
provided by package \fBstruct::queue\fR.
This queue contains the not-yet-processed part
of the attribute definitions, with one entry
per word, with the first entry the name of the
attribute which could not be processed.
.sp
The results of the command has to be a boolean
value where \fBTrue\fR signals that this
callback has accepted the attribute, processed
it, and the new state of the \fIwordqueue\fR
is where the general processing shall continue.
.sp
Given the signature the command has basically
two ways of handling (rewriting) the attributes
it recognizes:
.RS
.IP [1]
Replace the attribute (and arguments)
with a different attribute and arguments.
.IP [2]
Push additional words in front to get
the general processing unstuck.
.RE
.RE
.TP
\fIdiagramObject\fR \fBdraw\fR \fIscript\fR
This method runs the given \fIscript\fR in the
context of the drawing language definitions.
See section \fBLanguage Reference\fR for
details on the available commands.
.sp
\fINote\fR that \fIscript\fR is \fItrusted\fR.
It is executed in the current interpreter with
access to its full abilities.
For the execution of untrusted diagram scripts this
interpreter should be a safe one.
.PP
.SH "LANGUAGE REFERENCE"
.SS ELEMENTS
This section lists the commands for the predefined drawing elements,
aka shapes. These commands are all defined in the language's context.
All commands of this section return the handle of the newly created
element as their result. This handle also exists as a command which
can be used to query the element for its corners (names, values).
See section \fBMiscellaneous Commands\fR.
IMAGE: figure-02-basic-shapes
.TP
\fBarc\fR \fIattr\fR...
IMAGE: figure-02-arc
An open element with the corresponding corners, i.e. "start", "end",
and "center".
Note however that it also has the compass rose of closed elements as
its corners, with the center of the arc's circle as the center of the
compass and the other points on the circle the arc is part of.
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
................................................................................
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name. I.e. this attribute defines the text's
position relative to the element's center.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
The commands without arguments are all shorthands with the anchor
implied. Note that they do not combine, only the last is used. For
comined directions the main attribute command, \fBanchor\fR has to be
used.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
"anchor north"
.RE
.TP
\fBclockwise\fR
.TP
\fBcw\fR
Specifies the direction of the \fBarc\fR element, here going
clockwise.
The complementary attribute is \fBcounterclockwise\fR.
If not specified the system falls back to the value taken from the
language variable \fBclockwise\fR, which itself defaults to
\fBfalse\fR, for counter-clockwise direction.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR.
.TP
\fBcounterclockwise\fR
.TP
\fBccw\fR
Specifies the direction of the \fBarc\fR element, here
counter-clockwise.
The complementary attribute is \fBclockwise\fR.
If not specified the system falls back to the value taken from the
language variable \fBclockwise\fR, which itself defaults to
\fBfalse\fR, for counter-clockwise direction.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling".
.TP
\fBfrom\fR \fIlocation\fR
Specifies the location where the \fBarc\fR element begins.
Defaults to the current location as maintained by the layouting
system.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR.
.TP
\fBradius\fR \fIlength\fR
Specifies the radius of the \fBarc\fR element, or rather, the radius
of the circle the shown arc is a part of.
If not specified the system falls back to the value taken from the
language variable \fBarcradius\fR, which itself defaults to the pixel
equivalent of \fB1 cm\fR.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR.















































































































































































































































































































































































































































































































































































.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line.
.TP
\fBdot\fR, \fBdotted\fR, \fB.\fR
Draw a dotted line.
.TP
\fBdash-dot\fR, \fB-.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-..\fR
Draw a dash-dot-dotted line.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element.
Defaults to nothing.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR.
.TP
\fBto\fR \fIlocation\fR
Specifies the location where the \fBarc\fR element ends.
Defaults to a location such that a 90-degree arc is drawn in the
chosen direction, starting at \fBfrom\fR.
.RE
.TP
\fBarrow\fR \fIattr\fR...
.TP

\fB-->\fR \fIattr\fR...
.TP
\fB<-->\fR \fIattr\fR...
.TP
\fB<-->\fR \fIattr\fR...
IMAGE: figure-02-arrow
An alias for the \fBline\fR element (see below), with the attribute
\fBarrowhead\fR preset to \fB->\fR, \fB<->\fR, or \fB<-\fR.  The
\fBarrow\fR is equivalent to \fB-->\fR.
.TP
\fBblock\fR \fIscript\fR \fIattr\fR...
A closed element with the corresponding corners, i.e. the eight
directions of the compass rose, and "center".
The main effect is the aggregration of all elements created by the
\fIscript\fR into one element.
This also means that while the elements created by the script are
visible in the element history while the script is executing,
afterward the history contains only the block itself, and not the
elements it is composed of.
.sp
The script has access to the current state of all variables in the
language context.
Any changes to the variables will be reverted after execution of the
block.
However, also, any variables set in the script will be exported as
corners of the element, allowing users to define their own named
locations in the block.




.sp
Regarding the layout mechanism any changes made by the script are
reverted after the element is done.
In other words, a block is an implicit \fBgroup\fR.




.sp
Blocks handle all attributes, propgating their settings into the
script as the default values active during script execution.






.TP








\fBbox\fR \fIattr\fR...
IMAGE: figure-02-box
A closed element with the corresponding corners, i.e. the eight
directions of the compass rose, and "center".
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
................................................................................
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name. I.e. this attribute defines the text's
position relative to the element's center.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
The commands without arguments are all shorthands with the anchor
implied. Note that they do not combine, only the last is used. For
comined directions the main attribute command, \fBanchor\fR has to be
used.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
.TP
\fBabove\fR
"anchor south"
.TP
\fBbelow\fR
"anchor north"
.RE








.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR.
Defaults to the current location as maintained by the layouting
system.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling".
.TP
\fBheight\fR \fIlength\fR
.TP
\fBht\fR \fIlength\fR
Specifies the height of the element.
If not specified the system falls back to the value taken from the
language variable \fBboxheight\fR, which itself defaults to the
pixel equivalent of \fB2 cm\fR.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR.
.TP
\fBslant\fR \fIangle\fR
Specifies the angle by which the \fBbox\fR element is slanted, in
degrees.
If not specified the system falls back to the value taken from the
language variable \fBslant\fR, which itself defaults to \fB90\fR,
i.e. vertical, no slant.
0 degrees is slanting straight east, pointing to the right.
90 degrees is slanting to the north, pointing straight up.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line.
.TP
\fBdot\fR, \fBdotted\fR, \fB.\fR
Draw a dotted line.
.TP
\fBdash-dot\fR, \fB-.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-..\fR
Draw a dash-dot-dotted line.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element.
Defaults to nothing.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR.
.TP
\fBwidth\fR \fIlength\fR
.TP
\fBwid\fR \fIlength\fR
Specifies the width of the element.
If not specified the system falls back to the value taken from the
language variable \fBboxwidth\fR, which itself defaults to the pixel
equivalent of \fB2 cm\fR.
.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user. In that
case it defaults to \fBcenter\fR.
.RE
.TP
\fBcircle\fR \fIattr\fR...
.TP
\fBO\fR \fIattr\fR...
IMAGE: figure-02-circle
A closed element with the corresponding corners, i.e. the eight
directions of the compass rose, and "center".
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
................................................................................
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name. I.e. this attribute defines the text's
position relative to the element's center.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
The commands without arguments are all shorthands with the anchor
implied. Note that they do not combine, only the last is used. For
comined directions the main attribute command, \fBanchor\fR has to be
used.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR.
Defaults to the current location as maintained by the layouting
system.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR.
.TP
\fBdiameter\fR \fIlength\fR
.TP
\fBdiam\fR \fIlength\fR
Specifies the diameter of the \fBcircle\fR element, as an alternative
way to specify its \fBradius\fR.
Effective if and only if the radius was not specified. I.e. if both
diameter and radius are specified then the radius infomration has
precendence.
This attribute has no default, because the defaults are taken from the
radius.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling".








.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR.
.TP
\fBradius\fR \fIlength\fR
.TP
\fBrad\fR \fIlength\fR
Specifies the radius of the \fBcircle\fR element.
If not specified the system falls back to the value taken from the
language variable \fBcircleradius\fR, which itself defaults to the
pixel equivalent of \fB1 cm\fR.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line.
.TP
\fBdot\fR, \fBdotted\fR, \fB.\fR
Draw a dotted line.
.TP
\fBdash-dot\fR, \fB-.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-..\fR
Draw a dash-dot-dotted line.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element.
Defaults to nothing.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR.








.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user. In that
case it defaults to \fBcenter\fR.
.RE
.TP
\fBdiamond\fR \fIattr\fR...
.TP
\fB<>\fR \fIattr\fR...
IMAGE: figure-02-diamond
A closed element with the corresponding corners, i.e. the eight
directions of the compass rose, and "center".
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
................................................................................
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name. I.e. this attribute defines the text's
position relative to the element's center.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
The commands without arguments are all shorthands with the anchor
implied. Note that they do not combine, only the last is used. For
comined directions the main attribute command, \fBanchor\fR has to be
used.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
\fBabove\fR
"anchor south"
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBaspect\fR \fInumber\fR
Specifies the aspect ratio, i.e ratio of width to height, of the
\fBdiamond\fR element.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBwidth\fR and
\fBheight\fR, if any.
.sp

If both \fBwidth\fR, and \fBheight\fR are specified then any
specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence. A missing
specification is ignored in that case well, i.e. no defaults are
required.
.sp
If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified. No defaults are required for these
cases either.
.sp
If only one of the attributes \fBwidth\fR or \fBheight\fR is specified

then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR.
.sp
If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph.
.TP
\fBat\fR \fIlocation\fR




Specifies the location of the element's corner named by the attribute
\fBwith\fR.
Defaults to the current location as maintained by the layouting
system.












.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling".
.TP
\fBheight\fR \fIlength\fR
Specifies the height of the \fBdiamond\fR element.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBaspect\fR and
\fBwidth\fR, if any.
.sp
If both \fBwidth\fR, and \fBheight\fR are specified then any
specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence. A missing
specification is ignored in that case well, i.e. no defaults are
required.
.sp
If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified. No defaults are required for these
cases either.
.sp
If only one of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR.
.sp
If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR.











.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line.
.TP
\fBdot\fR, \fBdotted\fR, \fB.\fR
Draw a dotted line.
.TP
\fBdash-dot\fR, \fB-.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-..\fR
Draw a dash-dot-dotted line.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element.
Defaults to nothing.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR.
.TP
\fBwidth\fR \fIlength\fR
Specifies the width of the \fBdiamond\fR element.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBaspect\fR and

\fBheight\fR, if any.
.sp
If both \fBwidth\fR, and \fBheight\fR are specified then any
specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence. A missing
specification is ignored in that case well, i.e. no defaults are
required.
.sp
If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified. No defaults are required for these
cases either.





.sp
If only one of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR.



.sp
If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph.






.TP






\fBwith\fR \fIcorner\fR





Specifies the corner of the element to place at the location given by
the attribute \fBat\fR.
Defaults to the current corner as maintained by the layouting system,

except if the value for \fBat\fR was specified by the user. In that
case it defaults to \fBcenter\fR.
.RE
.TP
\fBdrum\fR \fIattr\fR...















IMAGE: figure-02-drum
A closed element with the corresponding corners, i.e. the eight
directions of the compass rose, and "center".
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
................................................................................
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name. I.e. this attribute defines the text's
position relative to the element's center.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
The commands without arguments are all shorthands with the anchor
implied. Note that they do not combine, only the last is used. For
comined directions the main attribute command, \fBanchor\fR has to be
used.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
.TP
\fBabove\fR
"anchor south"
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBaspect\fR \fInumber\fR
Specifies the aspect ratio, i.e ratio of width to height, of the
ellipses which are used to draw the top and bottom of the \fBdrum\fR
element.
If not specified the system falls back to the value taken from the
language variable \fBdrumaspect\fR, which itself defaults to
\fB0.35\fR.
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR.
Defaults to the current location as maintained by the layouting
system.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling".
.TP
\fBheight\fR \fIlength\fR
.TP
\fBht\fR \fIlength\fR
Specifies the height of the element.
If not specified the system falls back to the value taken from the
language variable \fBboxheight\fR, which itself defaults to the
pixel equivalent of \fB2 cm\fR.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line.
.TP
\fBdot\fR, \fBdotted\fR, \fB.\fR
Draw a dotted line.
.TP
\fBdash-dot\fR, \fB-.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-..\fR
Draw a dash-dot-dotted line.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element.
Defaults to nothing.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR.
.TP
\fBwidth\fR \fIlength\fR
.TP
\fBwid\fR \fIlength\fR
Specifies the width of the element.
If not specified the system falls back to the value taken from the
language variable \fBboxwidth\fR, which itself defaults to the pixel
equivalent of \fB2 cm\fR.
.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user. In that
case it defaults to \fBcenter\fR.
.RE
.TP
\fBellipse\fR \fIattr\fR...
IMAGE: figure-02-ellipse
A closed element with the corresponding corners, i.e. the eight
directions of the compass rose, and "center".
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name. I.e. this attribute defines the text's
position relative to the element's center.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
The commands without arguments are all shorthands with the anchor
implied. Note that they do not combine, only the last is used. For
comined directions the main attribute command, \fBanchor\fR has to be
used.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR.
Defaults to the current location as maintained by the layouting
system.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling".
.TP
\fBheight\fR \fIlength\fR
.TP
\fBht\fR \fIlength\fR
Specifies the height of the element.
If not specified the system falls back to the value taken from the
language variable \fBboxheight\fR, which itself defaults to the
pixel equivalent of \fB2 cm\fR.

.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line.
.TP
\fBdot\fR, \fBdotted\fR, \fB.\fR
Draw a dotted line.
.TP
\fBdash-dot\fR, \fB-.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-..\fR
Draw a dash-dot-dotted line.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element.
Defaults to nothing.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR.
.TP
\fBwidth\fR \fIlength\fR
.TP
\fBwid\fR \fIlength\fR
Specifies the width of the element.
If not specified the system falls back to the value taken from the
language variable \fBboxwidth\fR, which itself defaults to the pixel
equivalent of \fB2 cm\fR.

.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user. In that
case it defaults to \fBcenter\fR.
.RE
.TP
\fBline\fR \fIattr\fR...
.TP
\fB--\fR \fIattr\fR...
IMAGE: figure-02-line
An open element with the corresponding corners, i.e. "start", "end",
and "center".
It handles the attributes

.RS







.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name. I.e. this attribute defines the text's
position relative to the element's center.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
The commands without arguments are all shorthands with the anchor
implied. Note that they do not combine, only the last is used. For
comined directions the main attribute command, \fBanchor\fR has to be
used.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
\fBbelow\fR
"anchor north"
.RE
.TP
\fBarrowhead\fR \fIspec\fR
IMAGE: figure-19-style-arrowheads
Specifies where to draw arrowheads on the \fBline\fR element, at the
beginning or end, at both ends, or none.
If not specified the system falls back to the value taken from the
language variable \fBarrowhead\fR, which itself defaults to
\fBnone\fR.
The legal values are
.RS
.TP
\fBnone\fR, \fB-\fR
Draw no arrowheads, at neither end of the line.
.TP
\fBstart\fR, \fBfirst\fR, \fB<-\fR
Draw an arrowhead at the beginning of the line, but not at its end.
.TP
\fBend\fR, \fBlast\fR, \fB->\fR
Draw an arrowhead at the end of the line, but not at its beginning.
.TP
\fBboth\fR, \fB<->\fR
Draw arrowheads at both ends of the line.
.RE
.IP
Note that the values "start", "end", "-", "->", "<-", and "<->" are
all accepted as shorthands for the \fBarrowhead\fR command using them
as argument.
.TP






































\fBat\fR \fIlocation\fR






\fBLine\fR elements are normally positioned absolutely, using the
locations specified through the attributes \fBfrom\fR, \fBthen\fR, and
\fBto\fR.
If \fBat\fR is specified however then these positions are translated a
last time, moving the line's corner named by the attribute \fBwith\fR
to the location given by this attribute.
.TP
\fBchop\fR ?\fIlength\fR?
Specifies the length of the \fBline\fR element to remove from the
beginning and/or end.
Defaults to nothing.
If specified once the chopping applies to both beginning and end of
the line.
If specified twice or more the last two specifications are used, and
applied to beginning and end of the line, in this order.
Whenever the attribute is specified without an explicit length, the
system falls back to the value taken from the language variable
\fBcircleradius\fR, which itself defaults to the pixel equivalent of
\fB1 cm\fR
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling".
.TP
\fBfrom\fR \fIlocation\fR
Specifies the location where the \fBline\fR element begins.
Defaults to the current location as maintained by the layouting
system.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR.
.TP
\fBnoturn\fR
Specifies that the direction of \fBline\fR element at its end is not
propagated to the layout management.
If not specified the direction of the line becomes the new direction
the layout.
.TP
\fBsmooth\fR
Specifies the use of bezier splines for the \fBline\fR element.
If not specified lines are drawn exactly through the specified
waypoints, without any smooth curves.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line.
.TP
\fBdot\fR, \fBdotted\fR, \fB.\fR
Draw a dotted line.
.TP
\fBdash-dot\fR, \fB-.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-..\fR
Draw a dash-dot-dotted line.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element.
Defaults to nothing.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR.
.TP
\fBthen\fR \fIlocation\fR
.TP
\fBthen\fR (<direction> ?\fIlength\fR?)...
.TP
(<direction> ?\fIlength\fR?)...
This attribute specifies an intermediate location the \fBline\fR
element has to go through.
It can be specified multiple times, with each use adding one
additional location to the series which the line will go
through. These location will be traversed in the order they were
specified.
.sp
The location can be given explicitly, or as a series of directions
with distances. In the latter case the names of all known directions
are accepted for the direction part.
If no distance is specified for a direction the system falls back to
the value taken from the language variable \fBmovelength\fR, which
itself defaults to the pixel equivalent of \fB2 cm\fR.
The whole set of direction,distance pairs is treated as a series of
translations which are added up to provide the final translation
specifying the intermediate point (relative to the preceding point).
.sp
The last named direction is propagated to the layout system as the
direction to follow. The use of \fBnoturn\fR is not able to overide
this behaviour.
.sp
At last, the names of the registered directions also serve as
attribute commands, with an implicit attribute \fBthen\fR in front of
them.
.sp
If no intermediate or last location is specified for the line the
system falls back to a point \fBmovelength\fR pixels away from the
starting location, in the current direction as maintained by the
layouting system
.TP
\fBto\fR \fIlocation\fR
Specifies the location where the \fBline\fR element ends.
This attribute has no default. The default is handled by the attribute
\fBthen\fR, which makes it appear as if \fBto\fR has a default when
not specified.
.TP
\fBwith\fR \fIcorner\fR
\fBLine\fR elements are normally positioned absolutely, using the
locations specified through the attributes \fBfrom\fR, \fBthen\fR, and
\fBto\fR.
If \fBat\fR is specified however then these positions are translated a
last time, moving the line's corner named by the attribute \fBwith\fR
to the location given by this attribute.
This means that \fIwith\fR is effective if and only if the attribute
\fBat\fR was specified as well for the line.
.RE
.TP
\fBmove\fR \fIattr\fR
An open element with the corresponding corners, i.e. "start", "end",
and "center".
A \fBmove\fR element is in essence an invisible \fBline\fR.
While the main effect we are interested in is the change it makes to
the layout system, it is an actual element, i.e. it has the same
corners as an ordinary line, and shows up in the history as well,
allowing future references to all the places it touched.
It handles the same attibutes as \fBline\fR elements.
.TP
\fBspline\fR \fIattr\fR...
IMAGE: figure-02-spline
An alias for the \fBline\fR element (see above), with the attribute
\fBsmooth\fR preset.
.TP
\fBtext\fR \fIattr\fR...
IMAGE: figure-02-text
A closed element with the corresponding corners, i.e. the eight
directions of the compass rose, and "center".
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name. I.e. this attribute defines the text's
position relative to the element's center.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
The commands without arguments are all shorthands with the anchor
implied. Note that they do not combine, only the last is used. For
comined directions the main attribute command, \fBanchor\fR has to be
used.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
.TP
\fBabove\fR
"anchor south"
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR.
Defaults to the current location as maintained by the layouting
system.
.TP
\fBheight\fR \fIlength\fR
Specifies the height of the \fBtext\fR element.
Defaults to the natural height of its text.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element.
Defaults to nothing.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR.
.TP
\fBwidth\fR \fIlength\fR
Specifies the width of the \fBtext\fR element.
Defaults to the natural width of its text.
.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user. In that
case it defaults to \fBcenter\fR.
.RE
.PP
.SS ATTRIBUTES
The set of all attributes supported by all the element commands is
shown below.
While we speak of them as commands, and provide a syntax, they are not
truly available as actual commands, but only as part of the arguments
for an element command.
.PP
Note that some of the attribute names are overloaded, i.e. have
multiple, different, definitions. During processing of attributes for
an element the actual definition used is chosen based on the type of
the element the processing is for.
.PP
Further, as a catch-all clause, any attribute which could not be
processed according to the definitions below will be treated as the
argument of an implicit \fBtext\fR attribute.
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name. I.e. this attribute defines the text's
position relative to the element's center.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
The commands without arguments are all shorthands with the anchor
implied. Note that they do not combine, only the last is used. For
comined directions the main attribute command, \fBanchor\fR has to be
used.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
.TP
\fBabove\fR
"anchor south"
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBarrowhead\fR \fIspec\fR
IMAGE: figure-19-style-arrowheads
Specifies where to draw arrowheads on the \fBline\fR element, at the
beginning or end, at both ends, or none.
If not specified the system falls back to the value taken from the
language variable \fBarrowhead\fR, which itself defaults to
\fBnone\fR.
The legal values are
.RS
.TP
\fBnone\fR, \fB-\fR
Draw no arrowheads, at neither end of the line.
.TP
\fBstart\fR, \fBfirst\fR, \fB<-\fR
Draw an arrowhead at the beginning of the line, but not at its end.
.TP
\fBend\fR, \fBlast\fR, \fB->\fR
Draw an arrowhead at the end of the line, but not at its beginning.
.TP
\fBboth\fR, \fB<->\fR
Draw arrowheads at both ends of the line.
.RE
.IP
Note that the values "start", "end", "-", "->", "<-", and "<->" are
all accepted as shorthands for the \fBarrowhead\fR command using them
as argument.
.TP
\fBaspect\fR \fInumber\fR
Specifies the aspect ratio, i.e ratio of width to height, of the
\fBdiamond\fR element.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBwidth\fR and
\fBheight\fR, if any.
.sp
If both \fBwidth\fR, and \fBheight\fR are specified then any
specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence. A missing
specification is ignored in that case well, i.e. no defaults are
required.
.sp
If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified. No defaults are required for these
cases either.
.sp
If only one of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR.
.sp
If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph.
.TP
\fBaspect\fR \fInumber\fR
Specifies the aspect ratio, i.e ratio of width to height, of the
ellipses which are used to draw the top and bottom of the \fBdrum\fR
element.
If not specified the system falls back to the value taken from the
language variable \fBdrumaspect\fR, which itself defaults to
\fB0.35\fR.
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR.
Defaults to the current location as maintained by the layouting
system.
.TP
\fBat\fR \fIlocation\fR
\fBLine\fR elements are normally positioned absolutely, using the
locations specified through the attributes \fBfrom\fR, \fBthen\fR, and
\fBto\fR.
If \fBat\fR is specified however then these positions are translated a
last time, moving the line's corner named by the attribute \fBwith\fR
to the location given by this attribute.
.TP
\fBchop\fR ?\fIlength\fR?
Specifies the length of the \fBline\fR element to remove from the
beginning and/or end.
Defaults to nothing.
If specified once the chopping applies to both beginning and end of
the line.
If specified twice or more the last two specifications are used, and
applied to beginning and end of the line, in this order.
Whenever the attribute is specified without an explicit length, the
system falls back to the value taken from the language variable
\fBcircleradius\fR, which itself defaults to the pixel equivalent of
\fB1 cm\fR
.TP
\fBclockwise\fR
.TP
\fBcw\fR
Specifies the direction of the \fBarc\fR element, here going
clockwise.
The complementary attribute is \fBcounterclockwise\fR.
If not specified the system falls back to the value taken from the
language variable \fBclockwise\fR, which itself defaults to
\fBfalse\fR, for counter-clockwise direction.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR.
.TP
\fBcounterclockwise\fR
.TP
\fBccw\fR
Specifies the direction of the \fBarc\fR element, here
counter-clockwise.
The complementary attribute is \fBclockwise\fR.
If not specified the system falls back to the value taken from the
language variable \fBclockwise\fR, which itself defaults to
\fBfalse\fR, for counter-clockwise direction.
.TP
\fBdiameter\fR \fIlength\fR
.TP
\fBdiam\fR \fIlength\fR
Specifies the diameter of the \fBcircle\fR element, as an alternative
way to specify its \fBradius\fR.
Effective if and only if the radius was not specified. I.e. if both
diameter and radius are specified then the radius infomration has
precendence.
This attribute has no default, because the defaults are taken from the
radius.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling".
.TP
\fBfrom\fR \fIlocation\fR
Specifies the location where the \fBline\fR element begins.
Defaults to the current location as maintained by the layouting
system.
.TP
\fBfrom\fR \fIlocation\fR
Specifies the location where the \fBarc\fR element begins.
Defaults to the current location as maintained by the layouting
system.
.TP
\fBheight\fR \fIlength\fR
.TP
\fBht\fR \fIlength\fR
Specifies the height of the element.
If not specified the system falls back to the value taken from the
language variable \fBboxheight\fR, which itself defaults to the
pixel equivalent of \fB2 cm\fR.
.TP
\fBheight\fR \fIlength\fR
Specifies the height of the \fBdiamond\fR element.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBaspect\fR and
\fBwidth\fR, if any.
.sp
If both \fBwidth\fR, and \fBheight\fR are specified then any
specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence. A missing
specification is ignored in that case well, i.e. no defaults are
required.
.sp
If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified. No defaults are required for these
cases either.
.sp
If only one of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR.
.sp
If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph.
.TP
\fBheight\fR \fIlength\fR
Specifies the height of the \fBtext\fR element.
Defaults to the natural height of its text.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box.
The value is ignored if no text was specified for the element.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR.
.TP
\fBnoturn\fR
Specifies that the direction of \fBline\fR element at its end is not
propagated to the layout management.
If not specified the direction of the line becomes the new direction
the layout.
.TP
\fBradius\fR \fIlength\fR
.TP
\fBrad\fR \fIlength\fR
Specifies the radius of the \fBcircle\fR element.
If not specified the system falls back to the value taken from the
language variable \fBcircleradius\fR, which itself defaults to the
pixel equivalent of \fB1 cm\fR.
.TP
\fBradius\fR \fIlength\fR
Specifies the radius of the \fBarc\fR element, or rather, the radius
of the circle the shown arc is a part of.
If not specified the system falls back to the value taken from the
language variable \fBarcradius\fR, which itself defaults to the pixel
equivalent of \fB1 cm\fR.
.TP
\fBslant\fR \fIangle\fR
Specifies the angle by which the \fBbox\fR element is slanted, in
degrees.
If not specified the system falls back to the value taken from the
language variable \fBslant\fR, which itself defaults to \fB90\fR,
i.e. vertical, no slant.
0 degrees is slanting straight east, pointing to the right.
90 degrees is slanting to the north, pointing straight up.
.TP
\fBsmooth\fR
Specifies the use of bezier splines for the \fBline\fR element.
If not specified lines are drawn exactly through the specified
waypoints, without any smooth curves.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line.
.TP
\fBdot\fR, \fBdotted\fR, \fB.\fR
Draw a dotted line.
.TP
\fBdash-dot\fR, \fB-.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-..\fR
Draw a dash-dot-dotted line.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element.
Defaults to nothing.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with.
Ignored if there is no text.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR.
.TP
\fBthen\fR \fIlocation\fR
.TP
\fBthen\fR (<direction> ?\fIlength\fR?)...
.TP
(<direction> ?\fIlength\fR?)...
This attribute specifies an intermediate location the \fBline\fR
element has to go through.
It can be specified multiple times, with each use adding one
additional location to the series which the line will go
through. These location will be traversed in the order they were
specified.
.sp
The location can be given explicitly, or as a series of directions
with distances. In the latter case the names of all known directions
are accepted for the direction part.
If no distance is specified for a direction the system falls back to
the value taken from the language variable \fBmovelength\fR, which
itself defaults to the pixel equivalent of \fB2 cm\fR.
The whole set of direction,distance pairs is treated as a series of
translations which are added up to provide the final translation
specifying the intermediate point (relative to the preceding point).
.sp
The last named direction is propagated to the layout system as the
direction to follow. The use of \fBnoturn\fR is not able to overide
this behaviour.
.sp
At last, the names of the registered directions also serve as
attribute commands, with an implicit attribute \fBthen\fR in front of
them.
.sp
If no intermediate or last location is specified for the line the
system falls back to a point \fBmovelength\fR pixels away from the
starting location, in the current direction as maintained by the
layouting system
.TP
\fBto\fR \fIlocation\fR
Specifies the location where the \fBline\fR element ends.
This attribute has no default. The default is handled by the attribute
\fBthen\fR, which makes it appear as if \fBto\fR has a default when
not specified.
.TP
\fBto\fR \fIlocation\fR
Specifies the location where the \fBarc\fR element ends.
Defaults to a location such that a 90-degree arc is drawn in the
chosen direction, starting at \fBfrom\fR.
.TP
\fBwidth\fR \fIlength\fR
.TP
\fBwid\fR \fIlength\fR
Specifies the width of the element.
If not specified the system falls back to the value taken from the
language variable \fBboxwidth\fR, which itself defaults to the pixel
equivalent of \fB2 cm\fR.
.TP
\fBwidth\fR \fIlength\fR
Specifies the width of the \fBdiamond\fR element.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBaspect\fR and
\fBheight\fR, if any.
.sp
If both \fBwidth\fR, and \fBheight\fR are specified then any
specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence. A missing
specification is ignored in that case well, i.e. no defaults are
required.
.sp
If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified. No defaults are required for these
cases either.
.sp
If only one of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR.
.sp
If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph.
.TP
\fBwidth\fR \fIlength\fR
Specifies the width of the \fBtext\fR element.
Defaults to the natural width of its text.
.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user. In that
case it defaults to \fBcenter\fR.
.TP
\fBwith\fR \fIcorner\fR
\fBLine\fR elements are normally positioned absolutely, using the
locations specified through the attributes \fBfrom\fR, \fBthen\fR, and
\fBto\fR.
If \fBat\fR is specified however then these positions are translated a
last time, moving the line's corner named by the attribute \fBwith\fR
to the location given by this attribute.
This means that \fIwith\fR is effective if and only if the attribute
\fBat\fR was specified as well for the line.
.PP
.SS CORNERS
Corners are named values for in elements, usually locations.
.IP \(bu
The \fIclosed\fR elements define corners for the compass rose,
including the "center", and their "width" and "height".
.sp
IMAGE: figure-27-corners-closed
.sp
.IP \(bu
\fBblock\fR elements additionally export all variables which were set
during their definition as corners.
.IP \(bu
The \fIopen\fR elements on the other hand define "start", "end", and
"center". The first two map to the locations originally provided
through the attributes \fBfrom\fR and \fBto\fR of the element.
.sp
IMAGE: figure-28-corners-open
.sp
.IP \(bu
The center of \fBline\fR and \fBmove\fR elements is the location
halfway between "start" and "end" corners, this is regardless of any
intermediate locations the element may have.
.IP \(bu
The \fBline\fR and \fBmove\fR elements additionally name all their
locations as corners using numbers as names, starting from \fB1\fR
(equivalent to "start"), in order of traversal.
.sp
IMAGE: figure-15-spline-1
.sp
.IP \(bu
The center of \fBarc\fR elements is the center of the circle the arc
is part off.
.IP \(bu
The \fBarc\fR elements additionally define the compass rose of
closed elements as well.
.PP
.SS "NAMED DIRECTIONS"
The named directions are commands which tell the layout system in
which direction to go when placing the next element without an
explicit position specification.
They can also be used as arguments to the attribute \fBthen\fR, and
the command \fBby\fR for relative points, see there for the relevant
syntax.
.PP
The diagram core defines the directions of the compass rose, plus a
number of aliases. See below for the full list.
.PP
IMAGE: figure-27-corners-closed
.PP
This overlaps with the pre-defined corners for closed elements. This
is used by the layout system, when are going in direction X the name
of the opposite direction is the name of the corner at which the new
element will be attached to the current position, and if this corner
does not exist the nearest actual corner by angle is used.
.PP
.TP
\fBwest\fR
.TP
\fBw\fR
.TP
\fBleft\fR
................................................................................
.TP
\fInumber\fR \fBinch\fR
.TP
\fInumber\fR \fBpt\fR
These commands allow the specification of distances and coordinates in
metric and imperial units, returning the equivalent distance or
coordinate in pixels, which is the unit used internally for all
calculations.
.sp
The conversion factors are based on the result of \fBtk scaling\fR
and are computed once, at the time the package is sourced, future
changes of the \fBtk scaling\fR factor have no effect.
.TP
\fInumber\fR \fInumber\fR
.sp
IMAGE: figure-50-point-cons-absolute
.sp
This command takes the x and y coordinates of a location and returns
the \fIabsolute\fR point for it.
.TP
\fBby\fR \fIdistance\fR \fIdirection\fR
.sp
IMAGE: figure-51-point-cons-relative
.sp
This command takes a \fIdistance\fR and \fIdirection\fR (angle in
degress, or registered direction name) and returns the \fIrelative\fR
point for it, i.e. the \fIdelta\fR or \fItranslation\fR it
represents.
.sp
Note also the (dis)similarities to the directional specifications for
the attribute \fBthen\fR of \fBline\fR and \fBmove\fR elements.
Where we say here
.CS

by 50 east
.CE
.IP
for the attribute we say
.CS

... then east 50 ...
.CE
.IP
or just
.CS

... then east ...
.CE
.TP
\fIpoint1\fR \fB+\fR \fIpoint2\fR
.sp
IMAGE: figure-48-point-vectoradd
.sp
This command interprets two points as vectors and adds them together.
If at least one of the points is \fIabsolute\fR the result is
absolute as well.
The result is a \fIrelative\fR point if and only if both points are
\fIrelative\fR.
.TP
\fIpoint1\fR \fB-\fR \fIpoint2\fR
.sp
IMAGE: figure-49-point-vectorsub
.sp
This command interprets two points as vectors and subtracts the second
from the first.
If at least one of the points is \fIabsolute\fR the result is
absolute as well.
The result is a \fIrelative\fR point if and only if both points are
\fIrelative\fR.
.TP
\fIpoint\fR \fBby\fR \fIdistance\fR \fIdirection\fR
This command is a more convenient, or at least shorter, form of
.CS


    [$point + [by $distance $direction]]
................................................................................

.CE
.TP
\fIpoint1\fR \fB|\fR \fIpoint2\fR
.sp
IMAGE: figure-31-point-projection
.sp
This command calculates the \fIprojection\fR of two points, i.e. the
result is the point having the x-coordinate of \fIpoint1\fR and the
y-coordinate of \fIpoint2\fR.
.TP
\fIn\fR \fBbetween\fR \fIpoin1\fR \fIpoint2\fR
.sp
IMAGE: figure-29-point-interpolation-1
.sp
This command computes the point which is \fIn\fR*100 percent of the
way between \fIpoint1\fR and \fIpoint2\fR, and returns it as its
result.
This means that for
.RS
.TP
\fIn\fR == 0
The result is \fIpoint1\fR.
.TP
\fIn\fR == 1
The result is \fIpoint2\fR.
.TP
\fIn\fR == 0.5
The result is half way between the two points.
.RE
.IP
etc.
\fINote\fR that it is allowed to use values < 0 and > 1 for \fIn\fR
.TP
\fBintersect\fR \fIelem1\fR \fIelem2\fR
.sp
IMAGE: figure-32-point-intersection
.sp
This command takes two \fIopen\fR elements, computes the lines going
through their "start"- and "end"-corners, and returns the point where
these two lines intersect.
The command throws an error if the lines do not intersect, or are
coincident.
.TP
\fIelement\fR \fBnames\fR ?\fIpattern\fR?
This command returns a list containing the names of all corners for
the \fIelement\fR. If a pattern is specified then only the names
matching it (via \fBstring match\fR are returned. Otherwise all
names are returned (equivalent to a default pattern of \fB*\fR).
.TP
\fIelement\fR \fIcorner\fR
This command returns the value for the \fIcorner\fR of the
\fIelement\fR.
This can be anything, including points and elements.
.TP
\fIelement\fR \fIcorner1\fR \fIcorner2\fR...
This is a convenience shorthand for
.CS


[[[$elem $corner1] $corner2] ...]

.CE
.IP
assuming that the value for
.CS

 [$elem $corner1]
.CE
.IP, etc. is
again an element.
.TP
\fIelement\fR ?\fIcorner1\fR... ?\fBnames\fR ?\fIpattern\fR??]?
This is a convenience shorthand for
.CS


[[[$elem $corner1] ...] names ?pattern?]

.CE
.IP
assuming that the value for
.CS

 [$elem $corner1]
.CE
.IP, etc. is
again an element.
.TP
\fB\fBn\fRth\fR ?\fIcorner\fR?
This command asks the diagram history for the \fBn\fRth element
created, searching from the beginning of the history (counting from 1)
and returns it as its result.
If the \fIcorner\fR is specified then the value for this corner is
returned instead.
.TP
\fB\fBn\fRth\fR \fBlast\fR ?\fIcorner\fR?
This command asks the diagram history for the \fBn\fRth element
created, searching from the end of the history and returns it as its
result.
If the \fIcorner\fR is specified then the value for this corner is
returned instead.
.TP
\fB\fBn\fRth\fR \fIshape\fR ?\fIcorner\fR?
This command asks the diagram history for the \fBn\fRth element
created, of the given \fIshape\fR, searching from the beginning of the
history (counting from 1) and returns it as its result.
If the \fIcorner\fR is specified then the value for this corner is
returned instead.
.TP
\fB\fBn\fRth\fR \fBlast\fR \fIshape\fR ?\fIcorner\fR?
This command asks the diagram history for the \fBn\fRth element
created, of the given \fIshape\fR, searching from the end of the
history and returns it as its result.
If the \fIcorner\fR is specified then the value for this corner is
returned instead.
.TP
\fBlast\fR ?\fIcorner\fR?
.TP
\fBlast\fR \fIshape\fR ?\fIcorner\fR?
Convenience commands mapping to "\fB1st last\fR"
and "\fB1st last\fR \fIshape\fR".
.TP
\fB1st\fR
.TP
\fB2nd\fR
.TP
\fB3rd\fR
Aliases for \fB1th\fR, \fB2th\fR, and \fB3th\fR, for readability,
usable whereever \fB\fBn\fRth\fR can ocur.
.PP
.SS VARIABLES
The language context contains a number of predefined variables which
hold the default values for various attributes. These variables, their
uses, and values are:
.TP
\fBanchor\fR
The default value for the attribute \fBanchor\fR.
Initialized to \fBcenter\fR.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
.TP
\fBarcradius\fR
The default value for the attribute \fBradius\fR of \fBarc\fR
elements.
Initialized to the pixel equivalent of \fB1 cm\fR.
.TP
\fBarrowhead\fR
The default value for the attribute \fBarrowhead\fR.
Initialized to \fBnone\fR.
The legal values are
.RS
.TP
\fBnone\fR, \fB-\fR
Draw no arrowheads, at neither end of the line.
.TP
\fBstart\fR, \fBfirst\fR, \fB<-\fR
Draw an arrowhead at the beginning of the line, but not at its end.
.TP
\fBend\fR, \fBlast\fR, \fB->\fR
Draw an arrowhead at the end of the line, but not at its beginning.
.TP
\fBboth\fR, \fB<->\fR
Draw arrowheads at both ends of the line.
.RE
.TP
\fBboxheight\fR
The default value for the attribute \fBheight\fR of \fBbox\fR,
\fBdiamond\fR and \fBellipse\fR elements.
Initialized to the pixel equivalent of \fB2 cm\fR.
.TP
\fBboxwidth\fR
The default value for the attribute \fBwidth\fR of \fBbox\fR,
\fBdiamond\fR and \fBellipse\fR elements.
Initialized to the pixel equivalent of \fB2 cm\fR.
.TP
\fBclockwise\fR
The default value for the attributes \fBclockwise\fR and
\fBcounterclockwise\fR of \fBarc\fR elements.
Initialized to \fBFalse\fR, for counter-clockwise direction.
.TP
\fBcircleradius\fR
The default value for the attribute \fBradius\fR of \fBcircle\fR
elements, and also the default for the attribute \fBchop\fR, when
specified without an explicit length.
Initialized to the pixel equivalent of \fB1 cm\fR.
.TP
\fBdrumaspect\fR
The default value for the attribute \fBaspect\fR of \fBdrum\fR
elements.
Initialized to \fB0.35\fR.
.TP
\fBfillcolor\fR
The default value for the attribute \fBfillcolor\fR of all elements
which can be filled.
Initialized to the empty string, signaling that the element is not
filled.
.TP
\fBjustify\fR
The default value for the attribute \fBjustify\fR.
Initialized to \fBleft\fR.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR.
.TP
\fBlinecolor\fR
The default value for the attribute \fBcolor\fR of all elements having
to draw lines (all but \fBtext\fR).
Initialized to \fBblack\fR.
.TP
\fBlinestyle\fR
The default value for the attribute \fBstyle\fR of all elements
having to draw some line.
Initialized to \fBsolid\fR.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line.
.TP
\fBdot\fR, \fBdotted\fR, \fB.\fR
Draw a dotted line.
.TP
\fBdash-dot\fR, \fB-.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-..\fR
Draw a dash-dot-dotted line.
.RE
.TP
\fBlinewidth\fR
The default value for the attribute \fBstroke\fR of all elements
having to draw some line.
Initialized to \fB1\fR (pixels).
.TP
\fBmovelength\fR
The default value for the directional specification of intermediate
locations by the attribute \fBthen\fR of \fBline\fR and \fBmove\fR
elements.
Initialized to the pixel equivalent of \fB2 cm\fR.
.TP
\fBslant\fR
The default value for the attribute \fBslant\fR of \fBbox\fR elements.
Initialized to 90 degrees, i.e. slant straight up.
.TP
\fBtextcolor\fR
The default value for the attribute \fBtextcolor\fR of all elements
having to draw some text.
Initialized to \fBblack\fR.
.TP
\fBtextfont\fR
The default value for the attribute \fBtextfont\fR of all elements
having to draw some text.
Initialized to \fBHelvetica 12pt\fR.
.PP
.SH "DIAGRAM CLASSES"     The intended audience of this section are developers wishing to work
on the internals of the diagram package.
Regular users of \fBdiagram\fR can skip this section without
missing anything.
.PP
The main information seen here is the figure below, showing the
hierarchy of the classes implementing diagram.
.PP
IMAGE: figure-00-dependencies
.PP
At the bottom, all at the same level are the supporting packages like
\fBsnit\fR, etc. These can all be found in Tcllib.
.PP
Above them is the set of diagram classes implementing the various
aspects of the system, i.e.:
.TP
\fBdiagram\fR
The main class, that which is seen by the user.
.TP
\fBdiagram::core\fR
The core engine, itself distributed over four helper classes.
.TP
\fBdiagram::basic\fR
The implementation of the standard shapes, like box, circle, etc.,
based on the extension features of the core.
.TP
\fBdiagram::element\fR
Core support class, the database of created elements. It also keeps
the history, i.e. the order in which elements were created.
.TP
\fBdiagram::attribute\fR
Core support class, the generic handling of definition and processing
of attributes.
.TP
\fBdiagram::direction\fR
Core support class, the database of named directions.
.TP
\fBdiagram::navigation\fR
Core support class, the state of layout engine, i.e. current position
and directin, and operations on it.
.TP
\fBdiagram::point\fR
General support class handling various vector operations.
.PP
.SH REFERENCES
.SH KEYWORDS
2D geometry, arc, arrow, box, canvas, circle, diagram, diamond, drawing, drum, ellipse, image, interpolation, intersection, line, move, picture, plane geometry, plotting, point, raster image, spline, text, vector
.SH CATEGORY
Documentation tools

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/diagrams/diagram\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "diagram" n 0\&.3 tklib "Documentation toolbox"
.BS
.SH NAME
diagram \- Diagram drawing
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBdiagram  1\fR
.sp
\fB::diagram\fR \fIobjectName\fR \fIcanvas\fR ?\fIscript\fR?
.sp
\fIdiagramObject\fR \fBnew direction\fR \fIname\fR ?\fIkey\fR \fIvalue\fR\&.\&.\&.?
.sp
\fIdiagramObject\fR \fBnew element\fR \fIname\fR \fIattributes\fR \fIcmdprefix\fR
.sp
\fIdiagramObject\fR \fBnew alias\fR \fIname\fR \fIcmdprefix\fR
.sp
\fIdiagramObject\fR \fBnew command\fR \fIname\fR \fIarguments\fR \fIbody\fR
.sp
\fIdiagramObject\fR \fBnew attribute\fR \fIname\fR ?\fIkey\fR \fIvalue\fR\&.\&.\&.?
.sp
\fIdiagramObject\fR \fBunknown attribute\fR \fIcmdprefix\fR
.sp
\fIdiagramObject\fR \fBdraw\fR \fIscript\fR
.sp
\fBarc\fR \fIattr\fR\&.\&.\&.
.sp
\fBarrow\fR \fIattr\fR\&.\&.\&.
.sp
\fB-->\fR \fIattr\fR\&.\&.\&.
.sp
\fB<-->\fR \fIattr\fR\&.\&.\&.
.sp
\fB<-->\fR \fIattr\fR\&.\&.\&.
.sp
\fBblock\fR \fIscript\fR \fIattr\fR\&.\&.\&.
.sp
\fBbox\fR \fIattr\fR\&.\&.\&.
.sp
\fBcircle\fR \fIattr\fR\&.\&.\&.
.sp
\fBO\fR \fIattr\fR\&.\&.\&.
.sp
\fBdiamond\fR \fIattr\fR\&.\&.\&.
.sp
\fB<>\fR \fIattr\fR\&.\&.\&.
.sp
\fBdrum\fR \fIattr\fR\&.\&.\&.
.sp
\fBellipse\fR \fIattr\fR\&.\&.\&.
.sp
\fBline\fR \fIattr\fR\&.\&.\&.
.sp
\fB--\fR \fIattr\fR\&.\&.\&.
.sp
\fBmove\fR \fIattr\fR
.sp
\fBspline\fR \fIattr\fR\&.\&.\&.
.sp
\fBtext\fR \fIattr\fR\&.\&.\&.
.sp
\fBwest\fR
.sp
\fBw\fR
.sp
\fBleft\fR
.sp
................................................................................
.sp
\fBintersect\fR \fIelem1\fR \fIelem2\fR
.sp
\fIelement\fR \fBnames\fR ?\fIpattern\fR?
.sp
\fIelement\fR \fIcorner\fR
.sp
\fIelement\fR \fIcorner1\fR \fIcorner2\fR\&.\&.\&.
.sp
\fIelement\fR ?\fIcorner1\fR\&.\&.\&. ?\fBnames\fR ?\fIpattern\fR??]?
.sp
\fB\fBn\fRth\fR ?\fIcorner\fR?
.sp
\fB\fBn\fRth\fR \fBlast\fR ?\fIcorner\fR?
.sp
\fB\fBn\fRth\fR \fIshape\fR ?\fIcorner\fR?
.sp
................................................................................
\fB2nd\fR
.sp
\fB3rd\fR
.sp
.BE
.SH DESCRIPTION
Welcome to \fBdiagram\fR, a package for the easy construction of
diagrams (sic), i\&.e\&. 2D vector graphics, sometimes also called \fIpictures\fR\&.
Note that this package is not a replacement for \fBTk\fR's canvas,
but rather a layer sitting on top of it, to make it easier to use\&.
In other words, using the canvas as the core graphics engine \fBdiagram\fR abstracts away from the minutiae of handling coordinates to
position and size the drawn elements, allowing the user to concentrate
on the content of the diagram instead\&.
.PP
This is similar to Brian Kernighan's PIC language for troff, which is
the spiritual ancestor of this package\&.
.PP
This document contains the reference to the API and drawing (language)
commands\&. Its intended audience are users of the package wishing to
refresh their memory\&.
Newcomers should read the \fIDiagram Language Tutorial\fR first\&.
Developers wishing to work on the internals of the package and its
supporting packages should look at section
\fBDiagram Classes\fR
first, and then the comments in the sources of the packages itself\&.
.PP
In the remainder of the document we first describe the APIs of the
diagram class and its instances, followed by the language reference
for the drawing language itself\&.
.SH API
.SS "CLASS API"
The package exports the API described here\&.
.TP
\fB::diagram\fR \fIobjectName\fR \fIcanvas\fR ?\fIscript\fR?
The command creates a new instance of a diagram
controller and returns the fully qualified name of the
object command as its result\&.
The new instance is connected to the specified
\fIcanvas\fR object, which is used as the diagrams
graphics engine\&. This is usually an instance of Tk's
canvas, however any object which is API compatible to
Tk's canvas can be used here\&.
.sp
The API of this object command is described in the
following section, \fBObject API\fR\&. It may be
used to invoke various operations on the object\&.
.sp
If the \fIscript\fR argument is specified then method
\fBdraw\fR will be invoked on it\&.
.PP
.SS "OBJECT API"
Instances of the diagram class support the following
methods:
.TP
\fIdiagramObject\fR \fBnew direction\fR \fIname\fR ?\fIkey\fR \fIvalue\fR\&.\&.\&.?
This method defines a new named direction and its
attributes\&. The latter is given through the
\fIkey\fR/\fIvalue\fR pairs coming after the \fIname\fR\&.
.sp
Users are mostly free to specify arbitrary attributes
with whatever meaning they desire\&. The exception are
the names \fIangle\fR and \fIopposite\fR\&. They are
special to the diagram package and have a fixed meaning\&.
.RS
.TP
angle
This attribute specifies the angle of the direction in
degrees, where 0 points east (to the right) and 90 points
north (up)\&.
.TP
opposite
This attribute specifies the name of the direction
which should be considered as complementary to the
named one\&.
.RE
.TP
\fIdiagramObject\fR \fBnew element\fR \fIname\fR \fIattributes\fR \fIcmdprefix\fR
This method defines a new graphics element for the
drawing language\&. I\&.e\&. \fIname\fR will become a new
command in the language, and the specified command
prefix (\fIcmdprefix\fR) will be called to perform
the actual drawing\&.
.sp
\fIattributes\fR specifies the set of attributes for which
data has to be available\&. I\&.e\&. the system will run the
\&.\&.\&.-callbacks for these attributes\&.
See the method \fBnew attribute\fR for more information
on attribute definitions\&.
.sp
The command prefix is expected to conform to the
following signature:
.RS
.TP
\fBcmdprefix\fR \fIcanvas\fR \fIattributes\fR
Where \fIcanvas\fR is the handle of the canvas widget
to draw to, and \fIattributes\fR is a dictionary
holding the attributes for the element, be they
user-specified, or defaults\&.
.sp
The results of the command has to be a list containing
at least two and at most four items\&. These are, in order:
.RS
.IP [1]
The list of canvas items the drawn element consists of\&.
.IP [2]
The dictionary of named locations in the element, its
\fIcorners\fR\&.
.IP [3]
An optional mode, either "relative" or "absolute"\&.
When not returned "relative" is assumed\&. In the
case of a relative element position the attributes
"with" and "at" are used to determine the final
position of the new element\&.
.IP [4]
An optional name of a direction\&. If not the
empty string this is handed to the automatic
layouter as the new direction to follow\&.
.RE
.RE
.TP
\fIdiagramObject\fR \fBnew alias\fR \fIname\fR \fIcmdprefix\fR
This method defines a new command for the drawing
language\&. I\&.e\&. \fIname\fR will become a new command in
the language, and the specified command prefix
(\fIcmdprefix\fR) will be called on use of this new
command\&. Any arguments given to the command are
simply passed to the prefix\&. There is no fixed siganture\&.
.sp
Note that the prefix is run in the context of the
drawing language, allowing the direct use of any
existing commands\&.
.TP
\fIdiagramObject\fR \fBnew command\fR \fIname\fR \fIarguments\fR \fIbody\fR
This is like \fBnew alias\fR except that the new
command is defined as a procedure in the language's
context, with regular argument list and body\&.
.TP
\fIdiagramObject\fR \fBnew attribute\fR \fIname\fR ?\fIkey\fR \fIvalue\fR\&.\&.\&.?
This method defines a new named attribute which can be
used by graphical elements\&. The handling of the
attribute by the processor is declared through the
\fIkey\fR/\fIvalue\fR pairs coming after the \fIname\fR\&.
.sp
The accepted keys and their meanings are:
.RS
.TP
\fBkey\fR
The value of this key is the name of the key
under which the attribute's value shall be
stored in the attribute dictionary given to
the drawing command after attribute processing
is complete\&.
.sp
This key is optional\&. If it is not specified it
defaults to the name of the attribute\&.
.TP
\fBget\fR
The value of this key is a command prefix
which will be invoked to retrieve the
attribute's argument(s) from the command
line\&.
.sp
This key is optional\&. If it is not specified a
default is used which takes the single word
after the attribute name as the attribute's
value\&.
.sp
The signature of the command prefix is
.RS
.TP
\fBcmdprefix\fR \fIwordqueue\fR
Where \fIwordqueue\fR is the handle of
a queue object conforming to the API
of the queues provided by package
\fBstruct::queue\fR\&. This queue
contains the not-yet-processed part of
the attribute definitions, with one
entry per word, with the first entry
the word \fIafter\fR name of the
attribute\&. In other words, the
attribute's name has already been
removed from the queue\&.
.sp
The result of the command is the value
of the attribute, which may have been
taken from the queue, or not\&.
.RE
.TP
\fBtransform\fR
The value of this key is a command prefix
which will be invoked to transform the
retrieved value (See \fBget\fR) into their
final form\&.
.sp
This key is optional\&. If it is not specified
no transformation is done\&.
The signature of the command prefix is
.RS
.TP
\fBcmdprefix\fR \fIvalue\fR
Where \fIvalue\fR is the value to transform\&.
.sp
The result of the command is the final
value of the attribute\&.
.RE
.TP
\fBtype\fR
The value of this key is a command prefix
which will be invoked to validate the
attribute's argument(s)\&.
.sp
This key is optional\&. If it is not specified
no validation is done\&.
.sp
The signature of the command prefix is that of
snit validation types\&. See the documentation
of the \fBsnit\fR package\&.
.TP
\fBmerge\fR
The value of this key is a command prefix
which will be invoked to insert the
transformed and validated attribute value into
the dictionary of collected attributes\&.
.sp
This key is optional\&. If it is not specified
a default merge is chosen, based on the data
for key \fBaggregate\fR, see below\&.
The signature of the command prefix is
.RS
.TP
\fBcmdprefix\fR \fIvalue\fR \fIdict\fR
Where \fIvalue\fR is the value to
insert, and \fIdict\fR the dictionary
of attributes and values collected so
far\&.
.sp
The result of the command is the new
dictionary of attributes\&.
.RE
.TP
\fBaggregate\fR
The value of this key is a boolean flag\&. It
has an effect if and only if the key \fBmerge\fR was not specified\&. This key is
optional\&. If it is not specified it defaults
to \fBFalse\fR\&.
.sp
If the key is effective, the value of \fBFalse\fR means that the attribute's value is
\fIset\fR into the dictionary using the value
of key \fIkey\fR (see above) as index,
\fIoverwriting\fR any previously specified value\&.
.sp
If the key is effective, the value of \fBTrue\fR means that the attribute's value is
\fIadded\fR to the dictionary using the value
of key \fIkey\fR (see above) as index,
\fIextending\fR any previously specified value\&.
This means that the final value of the
attribute as seen after processing will be a
list of the collected values\&.
.TP
\fBdefault\fR
The value of this key is a command prefix
which will be invoked after collection of
attributes has been completed and this
attribute is in the list of required
attributes for the drawing element (See
argument \fIattributes\fR of method
\fBnew element\fR)\&.
.sp
Note that the connection is made through the
value of key \fIkey\fR, not through the
attribute name per se\&.
.sp
Further note that this command prefix is
invoked even if a user specified attribute
value is present\&. This allows the command
to go beyond simply setting defaults, it
can calculate and store derived values as
well\&.
.sp
This key is optional\&. If an element requires
this attribute, but \fIdefault\fR is not
specified then nothing will be done\&.
.sp
The signature of the command prefix is
.RS
.TP
\fBcmdprefix\fR \fBinit\fR
This method is run when the attribute
is defined, its responsibility is to
initialize anything in the language
namespace for the attribute and
default processing\&.
.sp
The result of this method is ignored\&.
.TP
\fBcmdprefix\fR \fBfill\fR \fIvarname\fR
This method is run to put defaults, or
derived values into the attribute dictionary
named by \fIvarname\fR\&. This variable will
be found in the calling context\&.
.sp
The result of this method is ignored\&.
.TP
\fBcmdprefix\fR \fBset\fR \fIname\fR \fIvalue\fR
This method is run to push current a
attribute value into the language
namespace, to make it the new default\&.
.sp
The result of this method is ignored\&.
.RE
.TP
\fBlinked\fR
This key is effective if and only if key
\fBdefault\fR is not specified\&. In that
case is supplies a default handling for
\fBdefault\fR, linking the attribute to a
variable in the language context\&.
.sp
The value for this key is a 2-element list
containing the name of the variable to link
to, and its initial value, in this order\&.
.RE
.TP
\fIdiagramObject\fR \fBunknown attribute\fR \fIcmdprefix\fR
This method registers the command prefix with the
subsystem processing the attributes for element
commands, telling it to call it when it encounters an
attribute it is unable to handle on its on\&.
.sp
It is allowed to register more than callback, these
will be called in order of registration (i\&.e\&. first to
last), until one of the callbacks accepts the current
input\&.
The command prefix is expected to conform to the
following signature:
.RS
.TP
\fBcmdprefix\fR \fIwordqueue\fR
Where \fIwordqueue\fR is the handle of a queue
object conforming to the API of the queues
provided by package \fBstruct::queue\fR\&.
This queue contains the not-yet-processed part
of the attribute definitions, with one entry
per word, with the first entry the name of the
attribute which could not be processed\&.
.sp
The results of the command has to be a boolean
value where \fBTrue\fR signals that this
callback has accepted the attribute, processed
it, and the new state of the \fIwordqueue\fR
is where the general processing shall continue\&.
.sp
Given the signature the command has basically
two ways of handling (rewriting) the attributes
it recognizes:
.RS
.IP [1]
Replace the attribute (and arguments)
with a different attribute and arguments\&.
.IP [2]
Push additional words in front to get
the general processing unstuck\&.
.RE
.RE
.TP
\fIdiagramObject\fR \fBdraw\fR \fIscript\fR
This method runs the given \fIscript\fR in the
context of the drawing language definitions\&.
See section \fBLanguage Reference\fR for
details on the available commands\&.
.sp
\fINote\fR that \fIscript\fR is \fItrusted\fR\&.
It is executed in the current interpreter with
access to its full abilities\&.
For the execution of untrusted diagram scripts this
interpreter should be a safe one\&.
.PP
.SH "LANGUAGE REFERENCE"
.SS ELEMENTS
This section lists the commands for the predefined drawing elements,
aka shapes\&. These commands are all defined in the language's context\&.
All commands of this section return the handle of the newly created
element as their result\&. This handle also exists as a command which
can be used to query the element for its corners (names, values)\&.
See section \fBMiscellaneous Commands\fR\&.
IMAGE: figure-02-basic-shapes
.TP
\fBarc\fR \fIattr\fR\&.\&.\&.
IMAGE: figure-02-arc
An open element with the corresponding corners, i\&.e\&. "start", "end",
and "center"\&.
Note however that it also has the compass rose of closed elements as
its corners, with the center of the arc's circle as the center of the
compass and the other points on the circle the arc is part of\&.
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
................................................................................
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name\&. I\&.e\&. this attribute defines the text's
position relative to the element's center\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR\&.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetAnchor\&.htm]\&.
The commands without arguments are all shorthands with the anchor
implied\&. Note that they do not combine, only the last is used\&. For
comined directions the main attribute command, \fBanchor\fR has to be
used\&.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
"anchor north"
.RE
.TP
\fBclockwise\fR
.TP
\fBcw\fR
Specifies the direction of the \fBarc\fR element, here going
clockwise\&.
The complementary attribute is \fBcounterclockwise\fR\&.
If not specified the system falls back to the value taken from the
language variable \fBclockwise\fR, which itself defaults to
\fBfalse\fR, for counter-clockwise direction\&.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR\&.
.TP
\fBcounterclockwise\fR
.TP
\fBccw\fR
Specifies the direction of the \fBarc\fR element, here
counter-clockwise\&.
The complementary attribute is \fBclockwise\fR\&.
If not specified the system falls back to the value taken from the
language variable \fBclockwise\fR, which itself defaults to
\fBfalse\fR, for counter-clockwise direction\&.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling"\&.
.TP
\fBfrom\fR \fIlocation\fR
Specifies the location where the \fBarc\fR element begins\&.
Defaults to the current location as maintained by the layouting
system\&.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR\&.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR\&.
.TP
\fBradius\fR \fIlength\fR
Specifies the radius of the \fBarc\fR element, or rather, the radius
of the circle the shown arc is a part of\&.
If not specified the system falls back to the value taken from the
language variable \fBarcradius\fR, which itself defaults to the pixel
equivalent of \fB1 cm\fR\&.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels\&.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR\&.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines\&.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetDash\&.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line\&.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line\&.
.TP
\fBdot\fR, \fBdotted\fR, \fB\&.\fR
Draw a dotted line\&.
.TP
\fBdash-dot\fR, \fB-\&.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-\&.\&.\fR
Draw a dash-dot-dotted line\&.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument\&.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element\&.
Defaults to nothing\&.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element\&.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR\&.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR\&.
.TP
\fBto\fR \fIlocation\fR
Specifies the location where the \fBarc\fR element ends\&.
Defaults to a location such that a 90-degree arc is drawn in the
chosen direction, starting at \fBfrom\fR\&.
.RE
.TP
\fBarrow\fR \fIattr\fR\&.\&.\&.
.TP
\fB-->\fR \fIattr\fR\&.\&.\&.
.TP
\fB<-->\fR \fIattr\fR\&.\&.\&.
.TP
\fB<-->\fR \fIattr\fR\&.\&.\&.
IMAGE: figure-02-arrow
An alias for the \fBline\fR element (see below), with the attribute
\fBarrowhead\fR preset to \fB->\fR, \fB<->\fR, or \fB<-\fR\&.  The
\fBarrow\fR is equivalent to \fB-->\fR\&.
.TP
\fBblock\fR \fIscript\fR \fIattr\fR\&.\&.\&.
A closed element with the corresponding corners, i\&.e\&. the eight
directions of the compass rose, and "center"\&.
The main effect is the aggregration of all elements created by the
\fIscript\fR into one element\&.
This also means that while the elements created by the script are
visible in the element history while the script is executing,
afterward the history contains only the block itself, and not the
elements it is composed of\&.
.sp
The script has access to the current state of all variables in the
language context\&.
Any changes to the variables will be reverted after execution of the
block\&.
However, also, any variables set in the script will be exported as
corners of the element, allowing users to define their own named
locations in the block\&.
.sp
Regarding the layout mechanism any changes made by the script are
reverted after the element is done\&.
In other words, a block is an implicit \fBgroup\fR\&.
.sp
Blocks handle all attributes, propgating their settings into the
script as the default values active during script execution\&.
.TP
\fBbox\fR \fIattr\fR\&.\&.\&.
IMAGE: figure-02-box
A closed element with the corresponding corners, i\&.e\&. the eight
directions of the compass rose, and "center"\&.
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name\&. I\&.e\&. this attribute defines the text's
position relative to the element's center\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR\&.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetAnchor\&.htm]\&.
The commands without arguments are all shorthands with the anchor
implied\&. Note that they do not combine, only the last is used\&. For
comined directions the main attribute command, \fBanchor\fR has to be
used\&.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
.TP
\fBabove\fR
"anchor south"
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR\&.
Defaults to the current location as maintained by the layouting
system\&.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR\&.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling"\&.
.TP
\fBheight\fR \fIlength\fR
.TP
\fBht\fR \fIlength\fR
Specifies the height of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBboxheight\fR, which itself defaults to the
pixel equivalent of \fB2 cm\fR\&.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR\&.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR\&.
.TP
\fBslant\fR \fIangle\fR
Specifies the angle by which the \fBbox\fR element is slanted, in
degrees\&.
If not specified the system falls back to the value taken from the
language variable \fBslant\fR, which itself defaults to \fB90\fR,
i\&.e\&. vertical, no slant\&.
0 degrees is slanting straight east, pointing to the right\&.
90 degrees is slanting to the north, pointing straight up\&.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels\&.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR\&.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines\&.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetDash\&.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line\&.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line\&.
.TP
\fBdot\fR, \fBdotted\fR, \fB\&.\fR
Draw a dotted line\&.
.TP
\fBdash-dot\fR, \fB-\&.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-\&.\&.\fR
Draw a dash-dot-dotted line\&.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument\&.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element\&.
Defaults to nothing\&.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element\&.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR\&.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR\&.
.TP
\fBwidth\fR \fIlength\fR
.TP
\fBwid\fR \fIlength\fR
Specifies the width of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBboxwidth\fR, which itself defaults to the pixel
equivalent of \fB2 cm\fR\&.
.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR\&.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user\&. In that
case it defaults to \fBcenter\fR\&.
.RE
.TP
\fBcircle\fR \fIattr\fR\&.\&.\&.
.TP
\fBO\fR \fIattr\fR\&.\&.\&.
IMAGE: figure-02-circle
A closed element with the corresponding corners, i\&.e\&. the eight
directions of the compass rose, and "center"\&.
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name\&. I\&.e\&. this attribute defines the text's
position relative to the element's center\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR\&.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetAnchor\&.htm]\&.
The commands without arguments are all shorthands with the anchor
implied\&. Note that they do not combine, only the last is used\&. For
comined directions the main attribute command, \fBanchor\fR has to be
used\&.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
.TP
\fBabove\fR
"anchor south"
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR\&.
Defaults to the current location as maintained by the layouting
system\&.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR\&.
.TP
\fBdiameter\fR \fIlength\fR
.TP
\fBdiam\fR \fIlength\fR
Specifies the diameter of the \fBcircle\fR element, as an alternative
way to specify its \fBradius\fR\&.
Effective if and only if the radius was not specified\&. I\&.e\&. if both
diameter and radius are specified then the radius infomration has
precendence\&.
This attribute has no default, because the defaults are taken from the
radius\&.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling"\&.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR\&.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR\&.
.TP
\fBradius\fR \fIlength\fR
.TP
\fBrad\fR \fIlength\fR
Specifies the radius of the \fBcircle\fR element\&.
If not specified the system falls back to the value taken from the
language variable \fBcircleradius\fR, which itself defaults to the
pixel equivalent of \fB1 cm\fR\&.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels\&.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR\&.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines\&.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetDash\&.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line\&.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line\&.
.TP
\fBdot\fR, \fBdotted\fR, \fB\&.\fR
Draw a dotted line\&.
.TP
\fBdash-dot\fR, \fB-\&.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-\&.\&.\fR
Draw a dash-dot-dotted line\&.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument\&.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element\&.
Defaults to nothing\&.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element\&.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR\&.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR\&.
.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR\&.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user\&. In that
case it defaults to \fBcenter\fR\&.
.RE
.TP
\fBdiamond\fR \fIattr\fR\&.\&.\&.
.TP
\fB<>\fR \fIattr\fR\&.\&.\&.
IMAGE: figure-02-diamond
A closed element with the corresponding corners, i\&.e\&. the eight
directions of the compass rose, and "center"\&.
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name\&. I\&.e\&. this attribute defines the text's
position relative to the element's center\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR\&.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetAnchor\&.htm]\&.
The commands without arguments are all shorthands with the anchor
implied\&. Note that they do not combine, only the last is used\&. For
comined directions the main attribute command, \fBanchor\fR has to be
used\&.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
.TP
\fBabove\fR
"anchor south"
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBaspect\fR \fInumber\fR
Specifies the aspect ratio, i\&.e ratio of width to height, of the
\fBdiamond\fR element\&.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBwidth\fR and
\fBheight\fR, if any\&.
.sp
If both \fBwidth\fR, and \fBheight\fR are specified then any
specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence\&. A missing
specification is ignored in that case well, i\&.e\&. no defaults are
required\&.
.sp
If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified\&. No defaults are required for these
cases either\&.
.sp
If only one of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR\&.
.sp
If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR\&. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph\&.
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR\&.
Defaults to the current location as maintained by the layouting
system\&.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR\&.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling"\&.
.TP
\fBheight\fR \fIlength\fR
Specifies the height of the \fBdiamond\fR element\&.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBaspect\fR and
\fBwidth\fR, if any\&.
.sp
If both \fBwidth\fR, and \fBheight\fR are specified then any
specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence\&. A missing
specification is ignored in that case well, i\&.e\&. no defaults are
required\&.
.sp
If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified\&. No defaults are required for these
cases either\&.
.sp
If only one of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR\&.
.sp
If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR\&. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph\&.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR\&.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR\&.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels\&.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR\&.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines\&.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetDash\&.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line\&.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line\&.
.TP
\fBdot\fR, \fBdotted\fR, \fB\&.\fR
Draw a dotted line\&.
.TP
\fBdash-dot\fR, \fB-\&.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-\&.\&.\fR
Draw a dash-dot-dotted line\&.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument\&.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element\&.
Defaults to nothing\&.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element\&.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR\&.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR\&.
.TP
\fBwidth\fR \fIlength\fR
Specifies the width of the \fBdiamond\fR element\&.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBaspect\fR and
\fBheight\fR, if any\&.
.sp
If both \fBwidth\fR, and \fBheight\fR are specified then any

specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence\&. A missing
specification is ignored in that case well, i\&.e\&. no defaults are
required\&.
















.sp







If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified\&. No defaults are required for these
cases either\&.
.sp



If only one of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR\&.
.sp


If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR\&. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph\&.
.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR\&.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user\&. In that
case it defaults to \fBcenter\fR\&.
.RE
.TP
\fBdrum\fR \fIattr\fR\&.\&.\&.
IMAGE: figure-02-drum
A closed element with the corresponding corners, i\&.e\&. the eight
directions of the compass rose, and "center"\&.
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
................................................................................
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name\&. I\&.e\&. this attribute defines the text's
position relative to the element's center\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR\&.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetAnchor\&.htm]\&.
The commands without arguments are all shorthands with the anchor
implied\&. Note that they do not combine, only the last is used\&. For
comined directions the main attribute command, \fBanchor\fR has to be
used\&.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
.TP
\fBabove\fR
"anchor south"
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBaspect\fR \fInumber\fR
Specifies the aspect ratio, i\&.e ratio of width to height, of the
ellipses which are used to draw the top and bottom of the \fBdrum\fR
element\&.
If not specified the system falls back to the value taken from the
language variable \fBdrumaspect\fR, which itself defaults to
\fB0\&.35\fR\&.
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR\&.
Defaults to the current location as maintained by the layouting
system\&.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR\&.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling"\&.
.TP
\fBheight\fR \fIlength\fR
.TP
\fBht\fR \fIlength\fR
Specifies the height of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBboxheight\fR, which itself defaults to the
pixel equivalent of \fB2 cm\fR\&.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR\&.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR\&.









.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels\&.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR\&.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines\&.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetDash\&.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line\&.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line\&.
.TP
\fBdot\fR, \fBdotted\fR, \fB\&.\fR
Draw a dotted line\&.
.TP
\fBdash-dot\fR, \fB-\&.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-\&.\&.\fR
Draw a dash-dot-dotted line\&.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument\&.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element\&.
Defaults to nothing\&.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element\&.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR\&.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR\&.
.TP
\fBwidth\fR \fIlength\fR
.TP
\fBwid\fR \fIlength\fR
Specifies the width of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBboxwidth\fR, which itself defaults to the pixel
equivalent of \fB2 cm\fR\&.
.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR\&.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user\&. In that
case it defaults to \fBcenter\fR\&.
.RE
.TP


\fBellipse\fR \fIattr\fR\&.\&.\&.
IMAGE: figure-02-ellipse
A closed element with the corresponding corners, i\&.e\&. the eight
directions of the compass rose, and "center"\&.
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
................................................................................
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name\&. I\&.e\&. this attribute defines the text's
position relative to the element's center\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR\&.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetAnchor\&.htm]\&.
The commands without arguments are all shorthands with the anchor
implied\&. Note that they do not combine, only the last is used\&. For
comined directions the main attribute command, \fBanchor\fR has to be
used\&.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR\&.
Defaults to the current location as maintained by the layouting
system\&.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR\&.











.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling"\&.
.TP
\fBheight\fR \fIlength\fR
.TP
\fBht\fR \fIlength\fR
Specifies the height of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBboxheight\fR, which itself defaults to the
pixel equivalent of \fB2 cm\fR\&.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR\&.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR\&.








.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels\&.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR\&.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines\&.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetDash\&.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line\&.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line\&.
.TP
\fBdot\fR, \fBdotted\fR, \fB\&.\fR
Draw a dotted line\&.
.TP
\fBdash-dot\fR, \fB-\&.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-\&.\&.\fR
Draw a dash-dot-dotted line\&.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument\&.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element\&.
Defaults to nothing\&.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element\&.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR\&.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR\&.
.TP
\fBwidth\fR \fIlength\fR
.TP
\fBwid\fR \fIlength\fR
Specifies the width of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBboxwidth\fR, which itself defaults to the pixel
equivalent of \fB2 cm\fR\&.
.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR\&.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user\&. In that
case it defaults to \fBcenter\fR\&.
.RE
.TP
\fBline\fR \fIattr\fR\&.\&.\&.
.TP
\fB--\fR \fIattr\fR\&.\&.\&.
IMAGE: figure-02-line
An open element with the corresponding corners, i\&.e\&. "start", "end",
and "center"\&.
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
................................................................................
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name\&. I\&.e\&. this attribute defines the text's
position relative to the element's center\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR\&.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetAnchor\&.htm]\&.
The commands without arguments are all shorthands with the anchor
implied\&. Note that they do not combine, only the last is used\&. For
comined directions the main attribute command, \fBanchor\fR has to be
used\&.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
\fBabove\fR
"anchor south"
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBarrowhead\fR \fIspec\fR
IMAGE: figure-19-style-arrowheads
Specifies where to draw arrowheads on the \fBline\fR element, at the
beginning or end, at both ends, or none\&.
If not specified the system falls back to the value taken from the
language variable \fBarrowhead\fR, which itself defaults to

\fBnone\fR\&.
The legal values are
.RS
.TP
\fBnone\fR, \fB-\fR
Draw no arrowheads, at neither end of the line\&.
.TP
\fBstart\fR, \fBfirst\fR, \fB<-\fR
Draw an arrowhead at the beginning of the line, but not at its end\&.
.TP
\fBend\fR, \fBlast\fR, \fB->\fR
Draw an arrowhead at the end of the line, but not at its beginning\&.

.TP
\fBboth\fR, \fB<->\fR
Draw arrowheads at both ends of the line\&.
.RE
.IP
Note that the values "start", "end", "-", "->", "<-", and "<->" are
all accepted as shorthands for the \fBarrowhead\fR command using them
as argument\&.



.TP
\fBat\fR \fIlocation\fR
\fBLine\fR elements are normally positioned absolutely, using the
locations specified through the attributes \fBfrom\fR, \fBthen\fR, and
\fBto\fR\&.
If \fBat\fR is specified however then these positions are translated a
last time, moving the line's corner named by the attribute \fBwith\fR

to the location given by this attribute\&.
.TP
\fBchop\fR ?\fIlength\fR?
Specifies the length of the \fBline\fR element to remove from the
beginning and/or end\&.
Defaults to nothing\&.
If specified once the chopping applies to both beginning and end of
the line\&.
If specified twice or more the last two specifications are used, and
applied to beginning and end of the line, in this order\&.
Whenever the attribute is specified without an explicit length, the
system falls back to the value taken from the language variable
\fBcircleradius\fR, which itself defaults to the pixel equivalent of
\fB1 cm\fR
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR\&.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling"\&.
.TP
\fBfrom\fR \fIlocation\fR
Specifies the location where the \fBline\fR element begins\&.
Defaults to the current location as maintained by the layouting
system\&.
























.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR\&.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR\&.
.TP
\fBnoturn\fR
Specifies that the direction of \fBline\fR element at its end is not
propagated to the layout management\&.
If not specified the direction of the line becomes the new direction
the layout\&.
.TP
\fBsmooth\fR
Specifies the use of bezier splines for the \fBline\fR element\&.
If not specified lines are drawn exactly through the specified
waypoints, without any smooth curves\&.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels\&.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR\&.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines\&.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetDash\&.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line\&.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line\&.
.TP
\fBdot\fR, \fBdotted\fR, \fB\&.\fR
Draw a dotted line\&.
.TP
\fBdash-dot\fR, \fB-\&.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-\&.\&.\fR
Draw a dash-dot-dotted line\&.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument\&.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element\&.
Defaults to nothing\&.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element\&.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR\&.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR\&.
.TP
\fBthen\fR \fIlocation\fR
.TP
\fBthen\fR (<direction> ?\fIlength\fR?)\&.\&.\&.

.TP
(<direction> ?\fIlength\fR?)\&.\&.\&.
This attribute specifies an intermediate location the \fBline\fR
element has to go through\&.
It can be specified multiple times, with each use adding one
additional location to the series which the line will go
through\&. These location will be traversed in the order they were
specified\&.
.sp
The location can be given explicitly, or as a series of directions
with distances\&. In the latter case the names of all known directions
are accepted for the direction part\&.
If no distance is specified for a direction the system falls back to
the value taken from the language variable \fBmovelength\fR, which
itself defaults to the pixel equivalent of \fB2 cm\fR\&.
The whole set of direction,distance pairs is treated as a series of
translations which are added up to provide the final translation
specifying the intermediate point (relative to the preceding point)\&.
.sp




The last named direction is propagated to the layout system as the
direction to follow\&. The use of \fBnoturn\fR is not able to overide
this behaviour\&.
.sp




At last, the names of the registered directions also serve as
attribute commands, with an implicit attribute \fBthen\fR in front of
them\&.
.sp
If no intermediate or last location is specified for the line the
system falls back to a point \fBmovelength\fR pixels away from the
starting location, in the current direction as maintained by the
layouting system
.TP
\fBto\fR \fIlocation\fR
Specifies the location where the \fBline\fR element ends\&.
This attribute has no default\&. The default is handled by the attribute
\fBthen\fR, which makes it appear as if \fBto\fR has a default when
not specified\&.
.TP
\fBwith\fR \fIcorner\fR
\fBLine\fR elements are normally positioned absolutely, using the
locations specified through the attributes \fBfrom\fR, \fBthen\fR, and
\fBto\fR\&.
If \fBat\fR is specified however then these positions are translated a
last time, moving the line's corner named by the attribute \fBwith\fR
to the location given by this attribute\&.


This means that \fIwith\fR is effective if and only if the attribute
\fBat\fR was specified as well for the line\&.

.RE
.TP
\fBmove\fR \fIattr\fR
An open element with the corresponding corners, i\&.e\&. "start", "end",
and "center"\&.
A \fBmove\fR element is in essence an invisible \fBline\fR\&.
While the main effect we are interested in is the change it makes to
the layout system, it is an actual element, i\&.e\&. it has the same
corners as an ordinary line, and shows up in the history as well,
allowing future references to all the places it touched\&.
It handles the same attibutes as \fBline\fR elements\&.
.TP
\fBspline\fR \fIattr\fR\&.\&.\&.
IMAGE: figure-02-spline
An alias for the \fBline\fR element (see above), with the attribute
\fBsmooth\fR preset\&.
.TP
\fBtext\fR \fIattr\fR\&.\&.\&.
IMAGE: figure-02-text
A closed element with the corresponding corners, i\&.e\&. the eight
directions of the compass rose, and "center"\&.
It handles the attributes
.RS
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
................................................................................
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name\&. I\&.e\&. this attribute defines the text's
position relative to the element's center\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR\&.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetAnchor\&.htm]\&.
The commands without arguments are all shorthands with the anchor
implied\&. Note that they do not combine, only the last is used\&. For
comined directions the main attribute command, \fBanchor\fR has to be
used\&.



































































































































































.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
.TP
\fBbelow\fR
"anchor north"
.RE
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR\&.
Defaults to the current location as maintained by the layouting
system\&.
.TP













\fBheight\fR \fIlength\fR


Specifies the height of the \fBtext\fR element\&.



Defaults to the natural height of its text\&.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR\&.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR\&.
.TP





































\fBtext\fR \fIstring\fR
Specifies the text to associate with the element\&.
Defaults to nothing\&.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element\&.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR\&.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR\&.
.TP
\fBwidth\fR \fIlength\fR


Specifies the width of the \fBtext\fR element\&.



Defaults to the natural width of its text\&.
.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR\&.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user\&. In that
case it defaults to \fBcenter\fR\&.
.RE
.PP
.SS ATTRIBUTES
The set of all attributes supported by all the element commands is
shown below\&.
While we speak of them as commands, and provide a syntax, they are not
truly available as actual commands, but only as part of the arguments
for an element command\&.

.PP
Note that some of the attribute names are overloaded, i\&.e\&. have
multiple, different, definitions\&. During processing of attributes for
an element the actual definition used is chosen based on the type of
the element the processing is for\&.
.PP
Further, as a catch-all clause, any attribute which could not be
processed according to the definitions below will be treated as the
argument of an implicit \fBtext\fR attribute\&.
.TP
\fBanchor\fR \fIname\fR
.TP
\fBljust\fR
.TP
\fBrjust\fR
.TP
\fBabove\fR
.TP
\fBbelow\fR
IMAGE: figure-22-text-anchoring-3
Specifies the anchor of the text which is to be placed at the
element's center, by name\&. I\&.e\&. this attribute defines the text's
position relative to the element's center\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBanchor\fR, which itself defaults to
\fBcenter\fR\&.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetAnchor\&.htm]\&.
The commands without arguments are all shorthands with the anchor
implied\&. Note that they do not combine, only the last is used\&. For
comined directions the main attribute command, \fBanchor\fR has to be
used\&.
.RS
.TP
\fBljust\fR
"anchor west"
.TP
\fBrjust\fR
"anchor east"
................................................................................
\fBbelow\fR
"anchor north"
.RE
.TP
\fBarrowhead\fR \fIspec\fR
IMAGE: figure-19-style-arrowheads
Specifies where to draw arrowheads on the \fBline\fR element, at the
beginning or end, at both ends, or none\&.
If not specified the system falls back to the value taken from the
language variable \fBarrowhead\fR, which itself defaults to
\fBnone\fR\&.
The legal values are
.RS
.TP
\fBnone\fR, \fB-\fR
Draw no arrowheads, at neither end of the line\&.
.TP
\fBstart\fR, \fBfirst\fR, \fB<-\fR
Draw an arrowhead at the beginning of the line, but not at its end\&.
.TP
\fBend\fR, \fBlast\fR, \fB->\fR
Draw an arrowhead at the end of the line, but not at its beginning\&.
.TP
\fBboth\fR, \fB<->\fR
Draw arrowheads at both ends of the line\&.
.RE
.IP
Note that the values "start", "end", "-", "->", "<-", and "<->" are
all accepted as shorthands for the \fBarrowhead\fR command using them
as argument\&.
.TP
\fBaspect\fR \fInumber\fR
Specifies the aspect ratio, i\&.e ratio of width to height, of the
\fBdiamond\fR element\&.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBwidth\fR and
\fBheight\fR, if any\&.
.sp
If both \fBwidth\fR, and \fBheight\fR are specified then any
specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence\&. A missing
specification is ignored in that case well, i\&.e\&. no defaults are
required\&.
.sp
If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified\&. No defaults are required for these
cases either\&.
.sp
If only one of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR\&.
.sp
If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR\&. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph\&.
.TP
\fBaspect\fR \fInumber\fR
Specifies the aspect ratio, i\&.e ratio of width to height, of the
ellipses which are used to draw the top and bottom of the \fBdrum\fR
element\&.
If not specified the system falls back to the value taken from the
language variable \fBdrumaspect\fR, which itself defaults to
\fB0\&.35\fR\&.
.TP
\fBat\fR \fIlocation\fR
Specifies the location of the element's corner named by the attribute
\fBwith\fR\&.
Defaults to the current location as maintained by the layouting
system\&.
.TP
\fBat\fR \fIlocation\fR
\fBLine\fR elements are normally positioned absolutely, using the
locations specified through the attributes \fBfrom\fR, \fBthen\fR, and
\fBto\fR\&.
If \fBat\fR is specified however then these positions are translated a
last time, moving the line's corner named by the attribute \fBwith\fR
to the location given by this attribute\&.
.TP
\fBchop\fR ?\fIlength\fR?
Specifies the length of the \fBline\fR element to remove from the
beginning and/or end\&.
Defaults to nothing\&.
If specified once the chopping applies to both beginning and end of
the line\&.
If specified twice or more the last two specifications are used, and
applied to beginning and end of the line, in this order\&.
Whenever the attribute is specified without an explicit length, the
system falls back to the value taken from the language variable
\fBcircleradius\fR, which itself defaults to the pixel equivalent of
\fB1 cm\fR
.TP






















































































































































































































































































































































































































\fBclockwise\fR
.TP
\fBcw\fR
Specifies the direction of the \fBarc\fR element, here going
clockwise\&.
The complementary attribute is \fBcounterclockwise\fR\&.
If not specified the system falls back to the value taken from the
language variable \fBclockwise\fR, which itself defaults to
\fBfalse\fR, for counter-clockwise direction\&.
.TP
\fBcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinecolor\fR, which itself defaults to \fBblack\fR\&.
.TP
\fBcounterclockwise\fR
.TP
\fBccw\fR
Specifies the direction of the \fBarc\fR element, here
counter-clockwise\&.
The complementary attribute is \fBclockwise\fR\&.
If not specified the system falls back to the value taken from the
language variable \fBclockwise\fR, which itself defaults to
\fBfalse\fR, for counter-clockwise direction\&.
.TP
\fBdiameter\fR \fIlength\fR
.TP
\fBdiam\fR \fIlength\fR
Specifies the diameter of the \fBcircle\fR element, as an alternative
way to specify its \fBradius\fR\&.
Effective if and only if the radius was not specified\&. I\&.e\&. if both
diameter and radius are specified then the radius infomration has
precendence\&.
This attribute has no default, because the defaults are taken from the
radius\&.
.TP
\fBfillcolor\fR \fIspec\fR
IMAGE: figure-21-style-colors
Specifies the color used to draw the inside of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBfillcolor\fR, which itself defaults to the empty
string, signaling "no filling"\&.
.TP
\fBfrom\fR \fIlocation\fR
Specifies the location where the \fBline\fR element begins\&.
Defaults to the current location as maintained by the layouting
system\&.
.TP
\fBfrom\fR \fIlocation\fR
Specifies the location where the \fBarc\fR element begins\&.
Defaults to the current location as maintained by the layouting
system\&.
.TP
\fBheight\fR \fIlength\fR
.TP
\fBht\fR \fIlength\fR
Specifies the height of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBboxheight\fR, which itself defaults to the
pixel equivalent of \fB2 cm\fR\&.
.TP
\fBheight\fR \fIlength\fR
Specifies the height of the \fBdiamond\fR element\&.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBaspect\fR and
\fBwidth\fR, if any\&.
.sp
If both \fBwidth\fR, and \fBheight\fR are specified then any
specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence\&. A missing
specification is ignored in that case well, i\&.e\&. no defaults are
required\&.
.sp
If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified\&. No defaults are required for these
cases either\&.
.sp
If only one of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR\&.
.sp
If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR\&. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph\&.
.TP
\fBheight\fR \fIlength\fR
Specifies the height of the \fBtext\fR element\&.
Defaults to the natural height of its text\&.
.TP
\fBjustify\fR \fBleft\fR|\fBcenter\fR|\fBright\fR
Specifies how multi-line text associated with the element is
positioned within its box\&.
The value is ignored if no text was specified for the element\&.
If not specified the system falls back to the value taken from the
language variable \fBjustify\fR, which itself defaults to
\fBleft\fR\&.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR\&.
.TP
\fBnoturn\fR
Specifies that the direction of \fBline\fR element at its end is not
propagated to the layout management\&.
If not specified the direction of the line becomes the new direction
the layout\&.
.TP
\fBradius\fR \fIlength\fR
.TP
\fBrad\fR \fIlength\fR
Specifies the radius of the \fBcircle\fR element\&.
If not specified the system falls back to the value taken from the
language variable \fBcircleradius\fR, which itself defaults to the
pixel equivalent of \fB1 cm\fR\&.
.TP
\fBradius\fR \fIlength\fR
Specifies the radius of the \fBarc\fR element, or rather, the radius
of the circle the shown arc is a part of\&.
If not specified the system falls back to the value taken from the
language variable \fBarcradius\fR, which itself defaults to the pixel
equivalent of \fB1 cm\fR\&.
.TP
\fBslant\fR \fIangle\fR
Specifies the angle by which the \fBbox\fR element is slanted, in
degrees\&.
If not specified the system falls back to the value taken from the
language variable \fBslant\fR, which itself defaults to \fB90\fR,
i\&.e\&. vertical, no slant\&.
0 degrees is slanting straight east, pointing to the right\&.
90 degrees is slanting to the north, pointing straight up\&.
.TP
\fBsmooth\fR
Specifies the use of bezier splines for the \fBline\fR element\&.
If not specified lines are drawn exactly through the specified
waypoints, without any smooth curves\&.
.TP
\fBstroke\fR \fIwidth\fR
IMAGE: figure-20-style-stroke
Specifies the width of the lines drawn for the the element, in pixels\&.
If not specified the system falls back to the value taken from the
language variable \fBlinewidth\fR, which itself defaults to \fB1\fR\&.
.TP
\fBstyle\fR \fIspec\fR
IMAGE: figure-18-style-dash
Specifies the style used to draw the lines of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBlinestyle\fR, which itself defaults to
\fBsolid\fR lines\&.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetDash\&.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line\&.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line\&.
.TP
\fBdot\fR, \fBdotted\fR, \fB\&.\fR
Draw a dotted line\&.
.TP
\fBdash-dot\fR, \fB-\&.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-\&.\&.\fR
Draw a dash-dot-dotted line\&.
.RE
.IP
Note that the values "solid", "dot(ted)", "dash(ed)", "dash-dot", and
"dash-dot-dot" are all accepted as shorthands for the \fBstyle\fR
command using them as argument\&.
.TP
\fBtext\fR \fIstring\fR
Specifies the text to associate with the element\&.
Defaults to nothing\&.
When specified multiple times the actually shown text is the
concatenation of the individual strings, vertically stacked, with the
first string specified being the topmost element\&.
.TP
\fBtextcolor\fR \fIspec\fR
Specifies the color used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextcolor\fR, which itself defaults to
\fBblack\fR\&.
.TP
\fBtextfont\fR \fIspec\fR
Specifies the font used to draw the text of an element with\&.
Ignored if there is no text\&.
If not specified the system falls back to the value taken from the
language variable \fBtextfont\fR, which itself defaults to
\fBHelvetica 12pt\fR\&.
.TP
\fBthen\fR \fIlocation\fR
.TP
\fBthen\fR (<direction> ?\fIlength\fR?)\&.\&.\&.
.TP
(<direction> ?\fIlength\fR?)\&.\&.\&.
This attribute specifies an intermediate location the \fBline\fR
element has to go through\&.
It can be specified multiple times, with each use adding one
additional location to the series which the line will go
through\&. These location will be traversed in the order they were
specified\&.
.sp
The location can be given explicitly, or as a series of directions
with distances\&. In the latter case the names of all known directions
are accepted for the direction part\&.
If no distance is specified for a direction the system falls back to
the value taken from the language variable \fBmovelength\fR, which
itself defaults to the pixel equivalent of \fB2 cm\fR\&.
The whole set of direction,distance pairs is treated as a series of
translations which are added up to provide the final translation
specifying the intermediate point (relative to the preceding point)\&.
.sp
The last named direction is propagated to the layout system as the
direction to follow\&. The use of \fBnoturn\fR is not able to overide
this behaviour\&.
.sp
At last, the names of the registered directions also serve as
attribute commands, with an implicit attribute \fBthen\fR in front of
them\&.
.sp
If no intermediate or last location is specified for the line the
system falls back to a point \fBmovelength\fR pixels away from the
starting location, in the current direction as maintained by the
layouting system
.TP
\fBto\fR \fIlocation\fR
Specifies the location where the \fBline\fR element ends\&.
This attribute has no default\&. The default is handled by the attribute
\fBthen\fR, which makes it appear as if \fBto\fR has a default when
not specified\&.
.TP
\fBto\fR \fIlocation\fR
Specifies the location where the \fBarc\fR element ends\&.
Defaults to a location such that a 90-degree arc is drawn in the
chosen direction, starting at \fBfrom\fR\&.
.TP
\fBwidth\fR \fIlength\fR
.TP
\fBwid\fR \fIlength\fR
Specifies the width of the element\&.
If not specified the system falls back to the value taken from the
language variable \fBboxwidth\fR, which itself defaults to the pixel
equivalent of \fB2 cm\fR\&.
.TP
\fBwidth\fR \fIlength\fR
Specifies the width of the \fBdiamond\fR element\&.
The manner in which a default is calculated when not specified also
depends on the specifications of the attributes \fBaspect\fR and
\fBheight\fR, if any\&.
.sp
If both \fBwidth\fR, and \fBheight\fR are specified then any
specification of \fBaspect\fR is ignored, as it is implicitly defined
in the width and height as well, and this takes precedence\&. A missing
specification is ignored in that case well, i\&.e\&. no defaults are
required\&.
.sp
If the \fBaspect\fR is specified, and one of the attributes
\fBwidth\fR or \fBheight\fR, then the missing attribute is calculated
from the two which are specified\&. No defaults are required for these
cases either\&.
.sp
If only one of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBaspect\fR, the value taken
from the language variable \fBdiamondaspect\fR, which itselfs defaults
to \fB2\fR\&.
.sp
If none of of the attributes \fBwidth\fR or \fBheight\fR is specified
then the system uses a fallback for the \fBwidth\fR, the value taken
from the language variable \fBboxwidth\fR, which itselfs defaults to
the pixel equivalent of \fB2 cm\fR\&. For the aspect it uses either
the user-specified value or the default taken as described in the
previous paragraph\&.
.TP
\fBwidth\fR \fIlength\fR
Specifies the width of the \fBtext\fR element\&.
Defaults to the natural width of its text\&.
.TP
\fBwith\fR \fIcorner\fR
Specifies the corner of the element to place at the location given by
the attribute \fBat\fR\&.
Defaults to the current corner as maintained by the layouting system,
except if the value for \fBat\fR was specified by the user\&. In that
case it defaults to \fBcenter\fR\&.
.TP
\fBwith\fR \fIcorner\fR
\fBLine\fR elements are normally positioned absolutely, using the
locations specified through the attributes \fBfrom\fR, \fBthen\fR, and
\fBto\fR\&.
If \fBat\fR is specified however then these positions are translated a
last time, moving the line's corner named by the attribute \fBwith\fR
to the location given by this attribute\&.
This means that \fIwith\fR is effective if and only if the attribute
\fBat\fR was specified as well for the line\&.
.PP
.SS CORNERS
Corners are named values for in elements, usually locations\&.
.IP \(bu
The \fIclosed\fR elements define corners for the compass rose,
including the "center", and their "width" and "height"\&.
.sp
IMAGE: figure-27-corners-closed
.sp
.IP \(bu
\fBblock\fR elements additionally export all variables which were set
during their definition as corners\&.
.IP \(bu
The \fIopen\fR elements on the other hand define "start", "end", and
"center"\&. The first two map to the locations originally provided
through the attributes \fBfrom\fR and \fBto\fR of the element\&.
.sp
IMAGE: figure-28-corners-open
.sp
.IP \(bu
The center of \fBline\fR and \fBmove\fR elements is the location
halfway between "start" and "end" corners, this is regardless of any
intermediate locations the element may have\&.
.IP \(bu
The \fBline\fR and \fBmove\fR elements additionally name all their
locations as corners using numbers as names, starting from \fB1\fR
(equivalent to "start"), in order of traversal\&.
.sp
IMAGE: figure-15-spline-1
.sp
.IP \(bu
The center of \fBarc\fR elements is the center of the circle the arc
is part off\&.
.IP \(bu
The \fBarc\fR elements additionally define the compass rose of
closed elements as well\&.
.PP
.SS "NAMED DIRECTIONS"
The named directions are commands which tell the layout system in
which direction to go when placing the next element without an
explicit position specification\&.
They can also be used as arguments to the attribute \fBthen\fR, and
the command \fBby\fR for relative points, see there for the relevant
syntax\&.
.PP
The diagram core defines the directions of the compass rose, plus a
number of aliases\&. See below for the full list\&.
.PP
IMAGE: figure-27-corners-closed
.PP
This overlaps with the pre-defined corners for closed elements\&. This
is used by the layout system, when are going in direction X the name
of the opposite direction is the name of the corner at which the new
element will be attached to the current position, and if this corner
does not exist the nearest actual corner by angle is used\&.
.PP
.TP
\fBwest\fR
.TP
\fBw\fR
.TP
\fBleft\fR
................................................................................
.TP
\fInumber\fR \fBinch\fR
.TP
\fInumber\fR \fBpt\fR
These commands allow the specification of distances and coordinates in
metric and imperial units, returning the equivalent distance or
coordinate in pixels, which is the unit used internally for all
calculations\&.
.sp
The conversion factors are based on the result of \fBtk scaling\fR
and are computed once, at the time the package is sourced, future
changes of the \fBtk scaling\fR factor have no effect\&.
.TP
\fInumber\fR \fInumber\fR
.sp
IMAGE: figure-50-point-cons-absolute
.sp
This command takes the x and y coordinates of a location and returns
the \fIabsolute\fR point for it\&.
.TP
\fBby\fR \fIdistance\fR \fIdirection\fR
.sp
IMAGE: figure-51-point-cons-relative
.sp
This command takes a \fIdistance\fR and \fIdirection\fR (angle in
degress, or registered direction name) and returns the \fIrelative\fR
point for it, i\&.e\&. the \fIdelta\fR or \fItranslation\fR it
represents\&.
.sp
Note also the (dis)similarities to the directional specifications for
the attribute \fBthen\fR of \fBline\fR and \fBmove\fR elements\&.
Where we say here
.CS

by 50 east
.CE
.IP
for the attribute we say
.CS

\&.\&.\&. then east 50 \&.\&.\&.
.CE
.IP
or just
.CS

\&.\&.\&. then east \&.\&.\&.
.CE
.TP
\fIpoint1\fR \fB+\fR \fIpoint2\fR
.sp
IMAGE: figure-48-point-vectoradd
.sp
This command interprets two points as vectors and adds them together\&.
If at least one of the points is \fIabsolute\fR the result is
absolute as well\&.
The result is a \fIrelative\fR point if and only if both points are
\fIrelative\fR\&.
.TP
\fIpoint1\fR \fB-\fR \fIpoint2\fR
.sp
IMAGE: figure-49-point-vectorsub
.sp
This command interprets two points as vectors and subtracts the second
from the first\&.
If at least one of the points is \fIabsolute\fR the result is
absolute as well\&.
The result is a \fIrelative\fR point if and only if both points are
\fIrelative\fR\&.
.TP
\fIpoint\fR \fBby\fR \fIdistance\fR \fIdirection\fR
This command is a more convenient, or at least shorter, form of
.CS


    [$point + [by $distance $direction]]
................................................................................

.CE
.TP
\fIpoint1\fR \fB|\fR \fIpoint2\fR
.sp
IMAGE: figure-31-point-projection
.sp
This command calculates the \fIprojection\fR of two points, i\&.e\&. the
result is the point having the x-coordinate of \fIpoint1\fR and the
y-coordinate of \fIpoint2\fR\&.
.TP
\fIn\fR \fBbetween\fR \fIpoin1\fR \fIpoint2\fR
.sp
IMAGE: figure-29-point-interpolation-1
.sp
This command computes the point which is \fIn\fR*100 percent of the
way between \fIpoint1\fR and \fIpoint2\fR, and returns it as its
result\&.
This means that for
.RS
.TP
\fIn\fR == 0
The result is \fIpoint1\fR\&.
.TP
\fIn\fR == 1
The result is \fIpoint2\fR\&.
.TP
\fIn\fR == 0\&.5
The result is half way between the two points\&.
.RE
.IP
etc\&.
\fINote\fR that it is allowed to use values < 0 and > 1 for \fIn\fR
.TP
\fBintersect\fR \fIelem1\fR \fIelem2\fR
.sp
IMAGE: figure-32-point-intersection
.sp
This command takes two \fIopen\fR elements, computes the lines going
through their "start"- and "end"-corners, and returns the point where
these two lines intersect\&.
The command throws an error if the lines do not intersect, or are
coincident\&.
.TP
\fIelement\fR \fBnames\fR ?\fIpattern\fR?
This command returns a list containing the names of all corners for
the \fIelement\fR\&. If a pattern is specified then only the names
matching it (via \fBstring match\fR are returned\&. Otherwise all
names are returned (equivalent to a default pattern of \fB*\fR)\&.
.TP
\fIelement\fR \fIcorner\fR
This command returns the value for the \fIcorner\fR of the
\fIelement\fR\&.
This can be anything, including points and elements\&.
.TP
\fIelement\fR \fIcorner1\fR \fIcorner2\fR\&.\&.\&.
This is a convenience shorthand for
.CS


[[[$elem $corner1] $corner2] \&.\&.\&.]

.CE
.IP
assuming that the value for
.CS

 [$elem $corner1]
.CE
.IP, etc\&. is
again an element\&.
.TP
\fIelement\fR ?\fIcorner1\fR\&.\&.\&. ?\fBnames\fR ?\fIpattern\fR??]?
This is a convenience shorthand for
.CS


[[[$elem $corner1] \&.\&.\&.] names ?pattern?]

.CE
.IP
assuming that the value for
.CS

 [$elem $corner1]
.CE
.IP, etc\&. is
again an element\&.
.TP
\fB\fBn\fRth\fR ?\fIcorner\fR?
This command asks the diagram history for the \fBn\fRth element
created, searching from the beginning of the history (counting from 1)
and returns it as its result\&.
If the \fIcorner\fR is specified then the value for this corner is
returned instead\&.
.TP
\fB\fBn\fRth\fR \fBlast\fR ?\fIcorner\fR?
This command asks the diagram history for the \fBn\fRth element
created, searching from the end of the history and returns it as its
result\&.
If the \fIcorner\fR is specified then the value for this corner is
returned instead\&.
.TP
\fB\fBn\fRth\fR \fIshape\fR ?\fIcorner\fR?
This command asks the diagram history for the \fBn\fRth element
created, of the given \fIshape\fR, searching from the beginning of the
history (counting from 1) and returns it as its result\&.
If the \fIcorner\fR is specified then the value for this corner is
returned instead\&.
.TP
\fB\fBn\fRth\fR \fBlast\fR \fIshape\fR ?\fIcorner\fR?
This command asks the diagram history for the \fBn\fRth element
created, of the given \fIshape\fR, searching from the end of the
history and returns it as its result\&.
If the \fIcorner\fR is specified then the value for this corner is
returned instead\&.
.TP
\fBlast\fR ?\fIcorner\fR?
.TP
\fBlast\fR \fIshape\fR ?\fIcorner\fR?
Convenience commands mapping to "\fB1st last\fR"
and "\fB1st last\fR \fIshape\fR"\&.
.TP
\fB1st\fR
.TP
\fB2nd\fR
.TP
\fB3rd\fR
Aliases for \fB1th\fR, \fB2th\fR, and \fB3th\fR, for readability,
usable whereever \fB\fBn\fRth\fR can ocur\&.
.PP
.SS VARIABLES
The language context contains a number of predefined variables which
hold the default values for various attributes\&. These variables, their
uses, and values are:
.TP
\fBanchor\fR
The default value for the attribute \fBanchor\fR\&.
Initialized to \fBcenter\fR\&.
The legal values are all those accepted by
\fITk_GetAnchor\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetAnchor\&.htm]\&.
.TP
\fBarcradius\fR
The default value for the attribute \fBradius\fR of \fBarc\fR
elements\&.
Initialized to the pixel equivalent of \fB1 cm\fR\&.
.TP
\fBarrowhead\fR
The default value for the attribute \fBarrowhead\fR\&.
Initialized to \fBnone\fR\&.
The legal values are
.RS
.TP
\fBnone\fR, \fB-\fR
Draw no arrowheads, at neither end of the line\&.
.TP
\fBstart\fR, \fBfirst\fR, \fB<-\fR
Draw an arrowhead at the beginning of the line, but not at its end\&.
.TP
\fBend\fR, \fBlast\fR, \fB->\fR
Draw an arrowhead at the end of the line, but not at its beginning\&.
.TP
\fBboth\fR, \fB<->\fR
Draw arrowheads at both ends of the line\&.
.RE
.TP
\fBboxheight\fR
The default value for the attribute \fBheight\fR of \fBbox\fR,
\fBdiamond\fR and \fBellipse\fR elements\&.
Initialized to the pixel equivalent of \fB2 cm\fR\&.
.TP
\fBboxwidth\fR
The default value for the attribute \fBwidth\fR of \fBbox\fR,
\fBdiamond\fR and \fBellipse\fR elements\&.
Initialized to the pixel equivalent of \fB2 cm\fR\&.
.TP
\fBclockwise\fR
The default value for the attributes \fBclockwise\fR and
\fBcounterclockwise\fR of \fBarc\fR elements\&.
Initialized to \fBFalse\fR, for counter-clockwise direction\&.
.TP
\fBcircleradius\fR
The default value for the attribute \fBradius\fR of \fBcircle\fR
elements, and also the default for the attribute \fBchop\fR, when
specified without an explicit length\&.
Initialized to the pixel equivalent of \fB1 cm\fR\&.
.TP
\fBdrumaspect\fR
The default value for the attribute \fBaspect\fR of \fBdrum\fR
elements\&.
Initialized to \fB0\&.35\fR\&.
.TP
\fBfillcolor\fR
The default value for the attribute \fBfillcolor\fR of all elements
which can be filled\&.
Initialized to the empty string, signaling that the element is not
filled\&.
.TP
\fBjustify\fR
The default value for the attribute \fBjustify\fR\&.
Initialized to \fBleft\fR\&.
The legal values are \fBleft\fR, \fBright\fR, and \fBcenter\fR\&.
.TP
\fBlinecolor\fR
The default value for the attribute \fBcolor\fR of all elements having
to draw lines (all but \fBtext\fR)\&.
Initialized to \fBblack\fR\&.
.TP
\fBlinestyle\fR
The default value for the attribute \fBstyle\fR of all elements
having to draw some line\&.
Initialized to \fBsolid\fR\&.
The legal values are all those accepted by
\fITk_GetDash\fR [http://www\&.tcl\&.tk/man/tcl8\&.5/TkLib/GetDash\&.htm],
and additionally all which are listed below:
.RS
.TP
\fBsolid\fR, empty string
Draw solid line\&.
.TP
\fBdash\fR, \fBdashed\fR, \fB-\fR
Draw a dashed line\&.
.TP
\fBdot\fR, \fBdotted\fR, \fB\&.\fR
Draw a dotted line\&.
.TP
\fBdash-dot\fR, \fB-\&.\fR
Draw a dash-dotted line
.TP
\fBdash-dot-dot\fR, \fB-\&.\&.\fR
Draw a dash-dot-dotted line\&.
.RE
.TP
\fBlinewidth\fR
The default value for the attribute \fBstroke\fR of all elements
having to draw some line\&.
Initialized to \fB1\fR (pixels)\&.
.TP
\fBmovelength\fR
The default value for the directional specification of intermediate
locations by the attribute \fBthen\fR of \fBline\fR and \fBmove\fR
elements\&.
Initialized to the pixel equivalent of \fB2 cm\fR\&.
.TP
\fBslant\fR
The default value for the attribute \fBslant\fR of \fBbox\fR elements\&.
Initialized to 90 degrees, i\&.e\&. slant straight up\&.
.TP
\fBtextcolor\fR
The default value for the attribute \fBtextcolor\fR of all elements
having to draw some text\&.
Initialized to \fBblack\fR\&.
.TP
\fBtextfont\fR
The default value for the attribute \fBtextfont\fR of all elements
having to draw some text\&.
Initialized to \fBHelvetica 12pt\fR\&.
.PP
.SH "DIAGRAM CLASSES"     The intended audience of this section are developers wishing to work
on the internals of the diagram package\&.
Regular users of \fBdiagram\fR can skip this section without
missing anything\&.
.PP
The main information seen here is the figure below, showing the
hierarchy of the classes implementing diagram\&.
.PP
IMAGE: figure-00-dependencies
.PP
At the bottom, all at the same level are the supporting packages like
\fBsnit\fR, etc\&. These can all be found in Tcllib\&.
.PP
Above them is the set of diagram classes implementing the various
aspects of the system, i\&.e\&.:
.TP
\fBdiagram\fR
The main class, that which is seen by the user\&.
.TP
\fBdiagram::core\fR
The core engine, itself distributed over four helper classes\&.
.TP
\fBdiagram::basic\fR
The implementation of the standard shapes, like box, circle, etc\&.,
based on the extension features of the core\&.
.TP
\fBdiagram::element\fR
Core support class, the database of created elements\&. It also keeps
the history, i\&.e\&. the order in which elements were created\&.
.TP
\fBdiagram::attribute\fR
Core support class, the generic handling of definition and processing
of attributes\&.
.TP
\fBdiagram::direction\fR
Core support class, the database of named directions\&.
.TP
\fBdiagram::navigation\fR
Core support class, the state of layout engine, i\&.e\&. current position
and directin, and operations on it\&.
.TP
\fBdiagram::point\fR
General support class handling various vector operations\&.
.PP
.SH REFERENCES
.SH KEYWORDS
2D geometry, arc, arrow, box, canvas, circle, diagram, diamond, drawing, drum, ellipse, image, interpolation, intersection, line, move, picture, plane geometry, plotting, point, raster image, spline, text, vector
.SH CATEGORY
Documentation tools

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/getstring/tk_getString.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "getstring" n 0.1 tklib "A dialog which prompts for a string input"
.BS
.SH NAME
getstring \- A string dialog
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBgetstring  ?0.1?\fR
.sp
\fB::getstring::tk_getString\fR \fIpathName\fR \fIvariable\fR \fItext\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides a dialog which consists of an Entry, OK, and
Cancel buttons.
.PP
.TP
\fB::getstring::tk_getString\fR \fIpathName\fR \fIvariable\fR \fItext\fR ?options?
Creates a dialog which prompts the user with \fItext\fR to input a text string.
The contents of the entry are put in the \fIvariable\fR upon closure of the
dialog. The command returns a boolean indicating if the user pressed OK or
not. If -geometry is not specified, the dialog is centered in its parent
toplevel unless its parent is . in which case the dialog is centered in the
screen.
Options:
-title
-allowempty a boolean argument indicating if the dialog should accept an empty entry
-entryoptions simply passes its arguments through to the entry widget. This is valuble for performing extra validation
using the Entry widget validation hooks.
-geometry specifies the geometry of the window
.PP
.SH EXAMPLE
.CS


package require getstring
namespace import getstring::*

if {[tk_getString .gs text "Feed me a string please:"]} {
    puts "user entered: $text"
}


.CE
.SH KEYWORDS
dialog, entry, string

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/getstring/tk_getString\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "getstring" n 0\&.1 tklib "A dialog which prompts for a string input"
.BS
.SH NAME
getstring \- A string dialog
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBgetstring  ?0\&.1?\fR
.sp
\fB::getstring::tk_getString\fR \fIpathName\fR \fIvariable\fR \fItext\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides a dialog which consists of an Entry, OK, and
Cancel buttons\&.
.PP
.TP
\fB::getstring::tk_getString\fR \fIpathName\fR \fIvariable\fR \fItext\fR ?options?
Creates a dialog which prompts the user with \fItext\fR to input a text string\&.
The contents of the entry are put in the \fIvariable\fR upon closure of the
dialog\&. The command returns a boolean indicating if the user pressed OK or
not\&. If -geometry is not specified, the dialog is centered in its parent
toplevel unless its parent is \&. in which case the dialog is centered in the
screen\&.
Options:
-title
-allowempty a boolean argument indicating if the dialog should accept an empty entry
-entryoptions simply passes its arguments through to the entry widget\&. This is valuble for performing extra validation
using the Entry widget validation hooks\&.
-geometry specifies the geometry of the window
.PP
.SH EXAMPLE
.CS


package require getstring
namespace import getstring::*

if {[tk_getString \&.gs text "Feed me a string please:"]} {
    puts "user entered: $text"
}


.CE
.SH KEYWORDS
dialog, entry, string

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/history/tklib_history.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "history" n 0.1 tklib "Provides a history for Entry widgets"
.BS
.SH NAME
history \- Provides a history for Entry widgets
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBTk  8.4\fR
.sp
package require \fBhistory  ?0.1?\fR
.sp
\fB::history::init\fR \fIpathName\fR ?length?
.sp
\fB::history::remove\fR \fIpathName\fR
.sp
\fB::history::add\fR \fIpathName\fR \fItext\fR
.sp
................................................................................
.sp
\fB::history::configure\fR \fIpathName\fR \fIoption\fR ?value?
.sp
bell
.sp
.BE
.SH DESCRIPTION
This package provides a convenient history mechanism for Entry widgets.
The history may be accessed with the up and down arrow keys.
.PP
.TP
\fB::history::init\fR \fIpathName\fR ?length?
Arranges to remember the history of the named Entry widget. An optional length
determines the number of history entries to keep. This may be changed later
with \fB::history::configure\fR. History entries must be added with the
\fB::history::add\fR command before they can be seen.
.TP
\fB::history::remove\fR \fIpathName\fR
Forgets all history entries for the Entry \fIpathName\fR and removes the history
bindings.
.TP
\fB::history::add\fR \fIpathName\fR \fItext\fR
This command is used to add history entries to an Entry that has previously had
\fB::history::init\fR called on it. This command should be called from your Entry
handler with the contents of the entry (or whatever you wish to add to the history).
.TP
\fB::history::get\fR \fIpathName\fR
This command returns a list containing the history entries for the Entry \fIpathName\fR
.TP
\fB::history::clear\fR \fIpathName\fR
This command clears the history list for the named Entry.
.TP
\fB::history::configure\fR \fIpathName\fR \fIoption\fR ?value?
This command queries or sets configuration options. Currently the options recognized
are \fIlength\fR and \fIalert\fR. Setting the length determines the number of history entries to keep for
the named Entry. Alert specifies the command to run when the user reaches the end of the history, it defaults to
.TP
bell
. Although configure requires a \fIpathName\fR argument, the setting for alert is global and the path is ignored.
.PP
.CS


entry .e
bind .e <Return> [list ProcessEntry %W]
::history::init .e
pack .e

proc ProcessEntry {w} {
    set text [$w get]
    if {$text == ""} { return }
    ::history::add $w $text
    puts $text
    $w delete 0 end
}


.CE
.SH KEYWORDS
entry, history

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/history/tklib_history\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "history" n 0\&.1 tklib "Provides a history for Entry widgets"
.BS
.SH NAME
history \- Provides a history for Entry widgets
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBTk  8\&.4\fR
.sp
package require \fBhistory  ?0\&.1?\fR
.sp
\fB::history::init\fR \fIpathName\fR ?length?
.sp
\fB::history::remove\fR \fIpathName\fR
.sp
\fB::history::add\fR \fIpathName\fR \fItext\fR
.sp
................................................................................
.sp
\fB::history::configure\fR \fIpathName\fR \fIoption\fR ?value?
.sp
bell
.sp
.BE
.SH DESCRIPTION
This package provides a convenient history mechanism for Entry widgets\&.
The history may be accessed with the up and down arrow keys\&.
.PP
.TP
\fB::history::init\fR \fIpathName\fR ?length?
Arranges to remember the history of the named Entry widget\&. An optional length
determines the number of history entries to keep\&. This may be changed later
with \fB::history::configure\fR\&. History entries must be added with the
\fB::history::add\fR command before they can be seen\&.
.TP
\fB::history::remove\fR \fIpathName\fR
Forgets all history entries for the Entry \fIpathName\fR and removes the history
bindings\&.
.TP
\fB::history::add\fR \fIpathName\fR \fItext\fR
This command is used to add history entries to an Entry that has previously had
\fB::history::init\fR called on it\&. This command should be called from your Entry
handler with the contents of the entry (or whatever you wish to add to the history)\&.
.TP
\fB::history::get\fR \fIpathName\fR
This command returns a list containing the history entries for the Entry \fIpathName\fR
.TP
\fB::history::clear\fR \fIpathName\fR
This command clears the history list for the named Entry\&.
.TP
\fB::history::configure\fR \fIpathName\fR \fIoption\fR ?value?
This command queries or sets configuration options\&. Currently the options recognized
are \fIlength\fR and \fIalert\fR\&. Setting the length determines the number of history entries to keep for
the named Entry\&. Alert specifies the command to run when the user reaches the end of the history, it defaults to
.TP
bell
\&. Although configure requires a \fIpathName\fR argument, the setting for alert is global and the path is ignored\&.
.PP
.CS


entry \&.e
bind \&.e <Return> [list ProcessEntry %W]
::history::init \&.e
pack \&.e

proc ProcessEntry {w} {
    set text [$w get]
    if {$text == ""} { return }
    ::history::add $w $text
    puts $text
    $w delete 0 end
}


.CE
.SH KEYWORDS
entry, history

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ico/ico.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ico" n 1.0.5 tklib "Windows ICO handling"
.BS
.SH NAME
ico \- Reading and writing windows icons
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBico  ?1.0.5?\fR
.sp
\fB::ico::icons\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR...?
.sp
\fB::ico::iconMembers\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...?
.sp
\fB::ico::getIcon\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...?
.sp
\fB::ico::getIconByName\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...?
.sp
\fB::ico::getFileIcon\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR...?
.sp
\fB::ico::writeIcon\fR \fIfile\fR \fIname\fR \fIdepth\fR \fIdata\fR ?\fIoption\fR \fIvalue\fR...?
.sp
\fB::ico::copyIcon\fR \fIfile\fR \fIindex\fR \fIfile2\fR \fIindex2\fR ?\fIoption\fR \fIvalue\fR...?
.sp
\fB::ico::EXEtoICO\fR \fIfile\fR ?dir?
.sp
\fB::ico::clearCache\fR ?file?
.sp
\fB::ico::transparentColor\fR \fIimage\fR \fIcolor\fR
.sp
\fB::ico::Show\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR...?
.sp
.BE
.SH DESCRIPTION
This package provides functions for reading and writing Windows icons
from ICO, EXE, DLL, ICL, and BMP files.
As used in this module an icon is a visual representation of an object.
An icon consists of one or more images usually with varying resolution
and color depth. Each icon and image has a resource identifier which
may be a text string or a positive integer value. Most commands use this
identifier to specify which icon or image to operate on.
.SH API
.TP
\fB::ico::icons\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR...?
Returns a list of icons found in \fIfile\fR where each element is the
name or numeric ID. Recognizes the following options:
.RS
.TP
\fB-type\fR fileFormat
.RE
.sp
.TP
\fB::ico::iconMembers\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...?
Returns a list of images that make up the icon with ID \fIname\fR. Each element is itself a
sublist in the format {name width height bpp}. Recognizes the following options:
.RS
.TP
\fB-type\fR fileFormat
.RE
.sp
.TP
\fB::ico::getIcon\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...?
Extracts the icon with ID \fIname\fR from \fIfile\fR.
The default \fB-format\fR is \fBimage\fR which will return the
name of a Tk image containing the icon. The resolution and color depth
are selected with the ?-res?, ?-bpp?, and ?-exact? options.
If -exact is specified and there is no exact match, an error is thrown.
Optionally \fB-image\fR may be used to specify the name of the Tk
image that is created. If \fB-format\fR is \fBcolors\fR then a
list of color names in the #RRGGBB format is returned. Each list element
is a horizontal row. Each horizontal row contains a list of colors for
all the pixels in that row from left to right. If \fB-format\fR is
\fBname\fR then the resource name of the image chosen is returned.
This is useful for calling writeIcon or getIconByName.
Recognizes the following \fIoption\fRs.
.RS
.TP
\fB-type\fR fileFormat
.TP
\fB-format\fR value
.TP
\fB-image\fR value
................................................................................
.TP
\fB-bpp\fR value
.TP
\fB-exact\fR value
.RE
.sp
.TP
\fB::ico::getIconByName\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...?
Extracts the image with ID \fIname\fR from \fIfile\fR. This name should be the name of a
specific image as returned by \fB::ico::iconMembers\fR, not an icon name returned from
\fB::ico::icons\fR. If there is no matching resource ID
in \fIfile\fR an error is thrown. Recognizes the following options:
.RS
.TP
\fB-type\fR fileFormat
.TP
\fB-format\fR value
.RE
.sp
.TP
\fB::ico::getFileIcon\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR...?
This command is only functional when running under Windows. It reads the Windows
registry to determine the display icon for \fIfile\fR as it would appear in Explorer
or similar. \fIfile\fR does not need to exist and may also be specified as a file
extension with a leading dot. If \fIfile\fR is a directory or you specify the
special name \fBFolder\fR then the icon representing a folder is returned. This
command takes the same arguments and usage as \fBgetIcon\fR:
.RS
.TP
\fB-format\fR value
.TP
\fB-image\fR value
.TP
................................................................................
.TP
\fB-bpp\fR value
.TP
\fB-exact\fR value
.RE
.sp
.TP
\fB::ico::writeIcon\fR \fIfile\fR \fIname\fR \fIdepth\fR \fIdata\fR ?\fIoption\fR \fIvalue\fR...?
Writes an image to \fIfile\fR. \fIname\fR is the resource identifier of the
image in \fIfile\fR to write.
When writing to an EXE, DLL, or ICL file you may only overwrite existing icons with an
icon of the same dimensions and color depth. No icons may be added to these file types.
.sp
When writing to BMP the name is ignored as this type can contain only one image. This means
if the file already existed it is completely overwritten.
.sp
When writing to an ICO or ICODATA file if the name
specified does not exist then an image is appended and will be named the next in sequence
(the specified name is ignored). Images in ICO and ICODATA files may be overwritten with differing
dimensions or color depths.
Note that you will get strange results when displaying icons if you fail to change every image
which makes up a given icon.
.RS
.TP
integer \fIdepth\fR (in)
This argument must have a value of \fB1\fR, \fB4\fR, \fB8\fR,
\fB24\fR, or \fB32\fR. If \fIdata\fR has more colors than the
color depth allows an error will be generated.
.TP
options \fIdata\fR (in)
This argument is either a list of colors in the format returned by
\fB::ico::getIcon -format colors\fR or the name of a Tk image.
.RE
.sp
Recognizes the following \fIoption\fRs.
.RS
.TP
\fB-type\fR fileFormat
.RE
.sp
.TP
\fB::ico::copyIcon\fR \fIfile\fR \fIindex\fR \fIfile2\fR \fIindex2\fR ?\fIoption\fR \fIvalue\fR...?
Copies the icon at \fIindex\fR in \fIfile\fR to \fIindex2\fR in \fIfile2\fR.
.RS
.TP
\fB-fromtype\fR fileFormat
.TP
\fB-totype\fR fileFormat
.RE
.sp
.TP
\fB::ico::EXEtoICO\fR \fIfile\fR ?dir?
Extracts all icons from the executable \fIfile\fR to ICO files placed in \fIdir\fR. ?dir? defaults to the directory \fIfile\fR is located in. Icon files will be named in the form \fIfile\fR-ID.ico where ID is the icon resource identifier.
.RS
.TP
\fB-type\fR fileFormat
.RE
.sp
.TP
\fB::ico::clearCache\fR ?file?
The \fB::ico::getIconList\fR command caches icon offsets inside EXE, DLL, ICL,
and ICO files in order to speed up extraction.  This command clears that
cache for the specific ?file? or all files.
.TP
\fB::ico::transparentColor\fR \fIimage\fR \fIcolor\fR
If \fIimage\fR is a single word it is assumed to be the name of a Tk image.
All pixels matching \fIcolor\fR in the \fIimage\fR will be set transparent.
Alternatively, \fIimage\fR may be a color list in which case a modified list
is returned.
.TP
\fB::ico::Show\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR...?
Application level command which displays a window showing all the
icons in \fIfile\fR and their name.
.RS
.TP
\fB-type\fR fileFormat
.TP
\fB-parent\fR pathName
.RE
.PP
.SH EXAMPLE
.CS


    button .explore -image [::ico::getIcon explorer.exe 0 -name explore -res 16 -bpp 8]

    set i [lsearch -inline [::ico::iconMembers tclkit.exe 0] {* 32 32 8}]
    set colorlist [::ico::getIconByName tclkit.exe [lindex $i 0] -format colors]

.CE
.SH LIMITATIONS
Icons may not be added or removed from file types other than ICO. Icons in these files
may only be replaced with icons of the same dimensions and color depth.
.PP
Icons of 8bpp or lower must include black in the pallete, this means if your icon does
not have black in it, you will need to leave a color free so that it may be included by
writeIcon.
.PP
There is currently no way to read alpha channel information from 32bpp icons.
.PP
Tk images do not have an alpha channel so the only way to write a true 32bpp icon is from
a color list. writing a 32bpp icon from a Tkimage is identical to writing a 24bpp icon.
.SH KEYWORDS
dll, entry, exe, ico, icon

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ico/ico\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ico" n 1\&.0\&.5 tklib "Windows ICO handling"
.BS
.SH NAME
ico \- Reading and writing windows icons
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBico  ?1\&.0\&.5?\fR
.sp
\fB::ico::icons\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
.sp
\fB::ico::iconMembers\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
.sp
\fB::ico::getIcon\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
.sp
\fB::ico::getIconByName\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
.sp
\fB::ico::getFileIcon\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
.sp
\fB::ico::writeIcon\fR \fIfile\fR \fIname\fR \fIdepth\fR \fIdata\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
.sp
\fB::ico::copyIcon\fR \fIfile\fR \fIindex\fR \fIfile2\fR \fIindex2\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
.sp
\fB::ico::EXEtoICO\fR \fIfile\fR ?dir?
.sp
\fB::ico::clearCache\fR ?file?
.sp
\fB::ico::transparentColor\fR \fIimage\fR \fIcolor\fR
.sp
\fB::ico::Show\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
.sp
.BE
.SH DESCRIPTION
This package provides functions for reading and writing Windows icons
from ICO, EXE, DLL, ICL, and BMP files\&.
As used in this module an icon is a visual representation of an object\&.
An icon consists of one or more images usually with varying resolution
and color depth\&. Each icon and image has a resource identifier which
may be a text string or a positive integer value\&. Most commands use this
identifier to specify which icon or image to operate on\&.
.SH API
.TP
\fB::ico::icons\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
Returns a list of icons found in \fIfile\fR where each element is the
name or numeric ID\&. Recognizes the following options:
.RS
.TP
\fB-type\fR fileFormat
.RE
.sp
.TP
\fB::ico::iconMembers\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
Returns a list of images that make up the icon with ID \fIname\fR\&. Each element is itself a
sublist in the format {name width height bpp}\&. Recognizes the following options:
.RS
.TP
\fB-type\fR fileFormat
.RE
.sp
.TP
\fB::ico::getIcon\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
Extracts the icon with ID \fIname\fR from \fIfile\fR\&.
The default \fB-format\fR is \fBimage\fR which will return the
name of a Tk image containing the icon\&. The resolution and color depth
are selected with the ?-res?, ?-bpp?, and ?-exact? options\&.
If -exact is specified and there is no exact match, an error is thrown\&.
Optionally \fB-image\fR may be used to specify the name of the Tk
image that is created\&. If \fB-format\fR is \fBcolors\fR then a
list of color names in the #RRGGBB format is returned\&. Each list element
is a horizontal row\&. Each horizontal row contains a list of colors for
all the pixels in that row from left to right\&. If \fB-format\fR is
\fBname\fR then the resource name of the image chosen is returned\&.
This is useful for calling writeIcon or getIconByName\&.
Recognizes the following \fIoption\fRs\&.
.RS
.TP
\fB-type\fR fileFormat
.TP
\fB-format\fR value
.TP
\fB-image\fR value
................................................................................
.TP
\fB-bpp\fR value
.TP
\fB-exact\fR value
.RE
.sp
.TP
\fB::ico::getIconByName\fR \fIfile\fR \fIname\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
Extracts the image with ID \fIname\fR from \fIfile\fR\&. This name should be the name of a
specific image as returned by \fB::ico::iconMembers\fR, not an icon name returned from
\fB::ico::icons\fR\&. If there is no matching resource ID
in \fIfile\fR an error is thrown\&. Recognizes the following options:
.RS
.TP
\fB-type\fR fileFormat
.TP
\fB-format\fR value
.RE
.sp
.TP
\fB::ico::getFileIcon\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
This command is only functional when running under Windows\&. It reads the Windows
registry to determine the display icon for \fIfile\fR as it would appear in Explorer
or similar\&. \fIfile\fR does not need to exist and may also be specified as a file
extension with a leading dot\&. If \fIfile\fR is a directory or you specify the
special name \fBFolder\fR then the icon representing a folder is returned\&. This
command takes the same arguments and usage as \fBgetIcon\fR:
.RS
.TP
\fB-format\fR value
.TP
\fB-image\fR value
.TP
................................................................................
.TP
\fB-bpp\fR value
.TP
\fB-exact\fR value
.RE
.sp
.TP
\fB::ico::writeIcon\fR \fIfile\fR \fIname\fR \fIdepth\fR \fIdata\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
Writes an image to \fIfile\fR\&. \fIname\fR is the resource identifier of the
image in \fIfile\fR to write\&.
When writing to an EXE, DLL, or ICL file you may only overwrite existing icons with an
icon of the same dimensions and color depth\&. No icons may be added to these file types\&.
.sp
When writing to BMP the name is ignored as this type can contain only one image\&. This means
if the file already existed it is completely overwritten\&.
.sp
When writing to an ICO or ICODATA file if the name
specified does not exist then an image is appended and will be named the next in sequence
(the specified name is ignored)\&. Images in ICO and ICODATA files may be overwritten with differing
dimensions or color depths\&.
Note that you will get strange results when displaying icons if you fail to change every image
which makes up a given icon\&.
.RS
.TP
integer \fIdepth\fR (in)
This argument must have a value of \fB1\fR, \fB4\fR, \fB8\fR,
\fB24\fR, or \fB32\fR\&. If \fIdata\fR has more colors than the
color depth allows an error will be generated\&.
.TP
options \fIdata\fR (in)
This argument is either a list of colors in the format returned by
\fB::ico::getIcon -format colors\fR or the name of a Tk image\&.
.RE
.sp
Recognizes the following \fIoption\fRs\&.
.RS
.TP
\fB-type\fR fileFormat
.RE
.sp
.TP
\fB::ico::copyIcon\fR \fIfile\fR \fIindex\fR \fIfile2\fR \fIindex2\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
Copies the icon at \fIindex\fR in \fIfile\fR to \fIindex2\fR in \fIfile2\fR\&.
.RS
.TP
\fB-fromtype\fR fileFormat
.TP
\fB-totype\fR fileFormat
.RE
.sp
.TP
\fB::ico::EXEtoICO\fR \fIfile\fR ?dir?
Extracts all icons from the executable \fIfile\fR to ICO files placed in \fIdir\fR\&. ?dir? defaults to the directory \fIfile\fR is located in\&. Icon files will be named in the form \fIfile\fR-ID\&.ico where ID is the icon resource identifier\&.
.RS
.TP
\fB-type\fR fileFormat
.RE
.sp
.TP
\fB::ico::clearCache\fR ?file?
The \fB::ico::getIconList\fR command caches icon offsets inside EXE, DLL, ICL,
and ICO files in order to speed up extraction\&.  This command clears that
cache for the specific ?file? or all files\&.
.TP
\fB::ico::transparentColor\fR \fIimage\fR \fIcolor\fR
If \fIimage\fR is a single word it is assumed to be the name of a Tk image\&.
All pixels matching \fIcolor\fR in the \fIimage\fR will be set transparent\&.
Alternatively, \fIimage\fR may be a color list in which case a modified list
is returned\&.
.TP
\fB::ico::Show\fR \fIfile\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
Application level command which displays a window showing all the
icons in \fIfile\fR and their name\&.
.RS
.TP
\fB-type\fR fileFormat
.TP
\fB-parent\fR pathName
.RE
.PP
.SH EXAMPLE
.CS


    button \&.explore -image [::ico::getIcon explorer\&.exe 0 -name explore -res 16 -bpp 8]

    set i [lsearch -inline [::ico::iconMembers tclkit\&.exe 0] {* 32 32 8}]
    set colorlist [::ico::getIconByName tclkit\&.exe [lindex $i 0] -format colors]

.CE
.SH LIMITATIONS
Icons may not be added or removed from file types other than ICO\&. Icons in these files
may only be replaced with icons of the same dimensions and color depth\&.
.PP
Icons of 8bpp or lower must include black in the pallete, this means if your icon does
not have black in it, you will need to leave a color free so that it may be included by
writeIcon\&.
.PP
There is currently no way to read alpha channel information from 32bpp icons\&.
.PP
Tk images do not have an alpha channel so the only way to write a true 32bpp icon is from
a color list\&. writing a 32bpp icon from a Tkimage is identical to writing a 24bpp icon\&.
.SH KEYWORDS
dll, entry, exe, ico, icon

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ipentry/ipentry.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ipentry" n 0.3 tklib "An IP address entry widget"
.BS
.SH NAME
ipentry \- An IP address entry widget
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBTk  8.4\fR
.sp
package require \fBipentry  ?0.3?\fR
.sp
\fB::ipentry::ipentry\fR \fIpathName\fR ?\fIoption\fR \fIvalue\fR...?
.sp
\fB::ipentry::ipentry6\fR \fIpathName\fR ?\fIoption\fR \fIvalue\fR...?
.sp
\fIpathName\fR \fBcomplete\fR
.sp
\fIpathName\fR \fBget\fR
.sp
\fIpathName\fR \fBinsert\fR \fIiplist\fR
.sp
\fIpathName\fR \fBicursor\fR \fIindex\fR
.sp
\fIpathName\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR...
.sp
\fIpathName\fR \fBcget\fR \fIoption\fR
.sp
.BE
.SH DESCRIPTION
This package provides a widget for the entering of a IP address.
.PP
.TP
\fB::ipentry::ipentry\fR \fIpathName\fR ?\fIoption\fR \fIvalue\fR...?
Creates a new IPv4 ipentry widget and configures it with the given options and
their values.
.TP
\fB::ipentry::ipentry6\fR \fIpathName\fR ?\fIoption\fR \fIvalue\fR...?
Creates a new ipentry widget for the entry of an IPv6 address. All options
are the same as the IPv4 widget.
.PP
Each widget created with the command above supports the following methods:
.TP
\fIpathName\fR \fBcomplete\fR
Returns a boolean value. True indicates that the entry contains a
complete IP address, meaning all fields have a value. In some cases
IPv6 address are valid when fields are missing. You will need to do your
own validation to detect this.
.TP
\fIpathName\fR \fBget\fR
Returns the contents of the entry as a list consisting of 4 or 8 elements.
.TP
\fIpathName\fR \fBinsert\fR \fIiplist\fR
IPv4
Takes a list of 4 elements and inserts one into each quad of the entry, in order.
All values in the list must be empty or integers. Values outside the range 0 to 255
are modified to be within the range.
IPv6
Takes a list of 8 elements and inserts one into each quad of the entry, in order.
All values in the list must be empty or 1 to 4 hex digits.
.TP
\fIpathName\fR \fBicursor\fR \fIindex\fR
Sets the position of the widgets insertion cursor. Only integer values between
0 and 15 are valid for ipentry and 0 to 31 for ipentry6.
Setting the icursor will only have an effect if the widget
already has the input focus.
.TP
\fIpathName\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR...
Modifies the configuration of the widget. For options and
their meaning see the widget options section.
.TP
\fIpathName\fR \fBcget\fR \fIoption\fR
Returns information about the current configuration of the widget, for
the specified option. For options and their meaning see the widget
options section.
.PP
.SH "WIDGET OPTIONS"
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-textvariable\fR
Database Name:	\fBtextvariable\fR
Database Class:	\fBVariable\fR

.fi
.IP
The name of a variable which holds the value of the IP address.
The value must be a string of the form NNN.NNN.NNN.NNN for IPv4 or
HHHH:HHHH:HHHH:HHHH:HHHH:HHHH:HHHH:HHHH for IPv6 where H is a hex digit.
The variable will be modified to represent a valid IP address if it is not
already.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-state\fR
Database Name:	\fBstate\fR
Database Class:	\fBState\fR

.fi
.IP
Specifies one of three states for the entry: \fBnormal\fR,
\fBdisabled\fR, or \fBreadonly\fR.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-font\fR
Database Name:	\fBfont\fR
Database Class:	\fBFont\fR

................................................................................
.ta 6c
Command-Line Switch:	\fB-insertbackground\fR
Database Name:	\fBinsertBackground\fR
Database Class:	\fBBackground\fR

.fi
.IP
Standard widget options. See \fBoptions\fR for a description of their
meanings and values.
.PP
.SH KEYWORDS
entry, ip address, network
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ipentry/ipentry\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ipentry" n 0\&.3 tklib "An IP address entry widget"
.BS
.SH NAME
ipentry \- An IP address entry widget
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBTk  8\&.4\fR
.sp
package require \fBipentry  ?0\&.3?\fR
.sp
\fB::ipentry::ipentry\fR \fIpathName\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
.sp
\fB::ipentry::ipentry6\fR \fIpathName\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
.sp
\fIpathName\fR \fBcomplete\fR
.sp
\fIpathName\fR \fBget\fR
.sp
\fIpathName\fR \fBinsert\fR \fIiplist\fR
.sp
\fIpathName\fR \fBicursor\fR \fIindex\fR
.sp
\fIpathName\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR\&.\&.\&.
.sp
\fIpathName\fR \fBcget\fR \fIoption\fR
.sp
.BE
.SH DESCRIPTION
This package provides a widget for the entering of a IP address\&.
.PP
.TP
\fB::ipentry::ipentry\fR \fIpathName\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
Creates a new IPv4 ipentry widget and configures it with the given options and
their values\&.
.TP
\fB::ipentry::ipentry6\fR \fIpathName\fR ?\fIoption\fR \fIvalue\fR\&.\&.\&.?
Creates a new ipentry widget for the entry of an IPv6 address\&. All options
are the same as the IPv4 widget\&.
.PP
Each widget created with the command above supports the following methods:
.TP
\fIpathName\fR \fBcomplete\fR
Returns a boolean value\&. True indicates that the entry contains a
complete IP address, meaning all fields have a value\&. In some cases
IPv6 address are valid when fields are missing\&. You will need to do your
own validation to detect this\&.
.TP
\fIpathName\fR \fBget\fR
Returns the contents of the entry as a list consisting of 4 or 8 elements\&.
.TP
\fIpathName\fR \fBinsert\fR \fIiplist\fR
IPv4
Takes a list of 4 elements and inserts one into each quad of the entry, in order\&.
All values in the list must be empty or integers\&. Values outside the range 0 to 255
are modified to be within the range\&.
IPv6
Takes a list of 8 elements and inserts one into each quad of the entry, in order\&.
All values in the list must be empty or 1 to 4 hex digits\&.
.TP
\fIpathName\fR \fBicursor\fR \fIindex\fR
Sets the position of the widgets insertion cursor\&. Only integer values between
0 and 15 are valid for ipentry and 0 to 31 for ipentry6\&.
Setting the icursor will only have an effect if the widget
already has the input focus\&.
.TP
\fIpathName\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR\&.\&.\&.
Modifies the configuration of the widget\&. For options and
their meaning see the widget options section\&.
.TP
\fIpathName\fR \fBcget\fR \fIoption\fR
Returns information about the current configuration of the widget, for
the specified option\&. For options and their meaning see the widget
options section\&.
.PP
.SH "WIDGET OPTIONS"
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-textvariable\fR
Database Name:	\fBtextvariable\fR
Database Class:	\fBVariable\fR

.fi
.IP
The name of a variable which holds the value of the IP address\&.
The value must be a string of the form NNN\&.NNN\&.NNN\&.NNN for IPv4 or
HHHH:HHHH:HHHH:HHHH:HHHH:HHHH:HHHH:HHHH for IPv6 where H is a hex digit\&.
The variable will be modified to represent a valid IP address if it is not
already\&.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-state\fR
Database Name:	\fBstate\fR
Database Class:	\fBState\fR

.fi
.IP
Specifies one of three states for the entry: \fBnormal\fR,
\fBdisabled\fR, or \fBreadonly\fR\&.
.LP
.nf
.ta 6c
Command-Line Switch:	\fB-font\fR
Database Name:	\fBfont\fR
Database Class:	\fBFont\fR

................................................................................
.ta 6c
Command-Line Switch:	\fB-insertbackground\fR
Database Name:	\fBinsertBackground\fR
Database Class:	\fBBackground\fR

.fi
.IP
Standard widget options\&. See \fBoptions\fR for a description of their
meanings and values\&.
.PP
.SH KEYWORDS
entry, ip address, network
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/khim/khim.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "khim" n 1.0 tklib "Kevin's Hacky Input Method"
.BS
.SH NAME
khim \- Provides key bindings for entering international characters on a keyboard that does not support them
.SH SYNOPSIS
package require \fBTcl \fR
.sp
package require \fBkhim  ?1.0?\fR
.sp
\fB::khim::getOptions\fR \fIpath\fR
.sp
\fB::khim::getConfig\fR
.sp
\fB::khim::setConfig\fR \fIversion\fR \fIenabled\fR \fIcompose\fR \fImap\fR
.sp
\fB::khim::showHelp\fR \fIpath\fR
.sp
.BE
.SH DESCRIPTION
This package provides a set of key bindings to allow
a user to enter arbitrary characters on a keyboard that
does not support them.  It works by designating some seldom-used key
of the keyboard as a "Compose" key (this key is distinct from any key
so labeled, and is often "Pause," "F12" or "L2"), and having the
"Compose" key, followed by a two-key sequence, have the effect of
inserting some character in a widget.
In addition, the "Compose" key, when struck twice in succession,
brings up a dialog containing a Unicode character map, allowing
arbitrary characters to be inserted.
.PP
The vast bulk of the package's functionality is implemented in a
single bindtag, \fBKHIM\fR.  An application can request that any
text or entry widget use the package to allow for entry of arbitrary
characters by placing this binding tag ahead of the \fBText\fR or
\fBEntry\fR binding tag for the widget:
.CS


text .t -width 80 -height 24
bindtags .t {.t KHIM Text . all}

.CE
Note that the \fBKHIM\fR tag must precede the \fBText\fR or
\fBEntry\fR class binding, or the package will not function
correctly.
.SH PROCEDURES
In addition to commands supporting the KHIM binding tag, the following
commands are exported from the package:
.TP
\fB::khim::getOptions\fR \fIpath\fR
Posts a top-level modal dialog with the path name \fIpath\fR that
prompts the user for KHIM options.  The user is allowed to reconfigure
the key sequences for the "Compose" key, change the choice of key to
use for the "Compose" function, and enable/disable the KHIM key
bindings entirely.
.TP
\fB::khim::getConfig\fR
Returns a Tcl script that restores the current configuration of KHIM:
the enabled/disabled state, the choice of "Compose" key, and the key
sequences that may be composed.  This script is designed to be
saved to a configuration file for use in a subsequent invocation of
the same application:
.CS


# Save KHIM configuration
set f [open ~/.khimrc w]
puts $f [::khim::getConfig]
close $f

# Restore KHIM configuration
source ~/.khimrc

.CE
.TP
\fB::khim::setConfig\fR \fIversion\fR \fIenabled\fR \fIcompose\fR \fImap\fR
Restores an earlier saved configuration.  Few, if any, applications
will call this command in any other way than to evaluate it as
returned from \fB::khim::getConfig\fR.
.TP
\fB::khim::showHelp\fR \fIpath\fR
Displays a top-level dialog giving user-level help for KHIM; the
dialog will have the path name \fIpath\fR.
.PP
.SH LOCALISATION
.PP
Programmers who wish to make KHIM available in a non-English-speaking
locale may do so by providing a \fB.msg\fR file with the appropriate
localised text.  The catalog requires the following messages:
.TP
\fBApply\fR
Text that will appear on the "Apply" button in the dialog that sets
KHIM options.
.TP
\fBCancel\fR
Text that will appear on the "Cancel" button in several dialogs.
.TP
\fBChange\fR
Text that will appear on the "Change" button, which alters the binding
of a pair of composed characters (creating or replacing as
appropriate).
.TP
\fBCharacter\fR
Text that will appear on the label of the entry widget that accepts a
character resulting from a composed sequence.
.TP
\fB{Compose Key}\fR
Window title for a dialog that prompts the user to strike the key that
will be used for the "Compose" key.
.TP
\fB{Compose key:}\fR
Label that identifies a component showing the "Compose" key choice in
the KHIM options dialog.
.TP
\fB{Composed sequence must be two characters long}\fR
Error message that is displayed if the user attempts to define a
"Compose" sequence that is shorter or longer than two characters.
.TP
\fBDelete\fR
Text for a button that deletes a "Compose" sequence.
.TP
\fBHelp...\fR
Text for a button that displays the KHIM user help dialog.
.TP
\fBHELPTEXT\fR
Complete text for the user-level help for KHIM.  Refer to
"\fIen.msg\fR" for the English-language version of the help.
.TP
\fB{Input key sequence}\fR
Text for a label of the entry widget that prompts the user for a
two-character sequence to use with the "Compose" key.
.TP
\fB{Insert Character}\fR
Window title of the dialog box that displays a Unicode character map
and prompts the user to select a character to insert.
.TP
\fB{Key sequences}\fR
Text for a label at the head of a listbox showing the composed
sequences that are currently bound.
.TP
\fB{KHIM Controls}\fR
Window title for the dialog box that prompts for KHIM settings.
.TP
\fB{KHIM Help}\fR
Window title for the window that display help text for KHIM.
.TP
\fBOK\fR
Label for the OK button on several dialogs.
.TP
\fBSelect code page:\fR
Label for a spinbox that prompts the user for a Unicode code page number.
.TP
\fBSELECT COMPOSE KEY\fR
A message, which should be composed in short lines, prompting the user
to press the key that will become the "Compose" key in KHIM.
.TP
\fBUnicode...\fR
Text for a button that brings up the character map to select the
character to which a composed sequence binds.
.TP
\fB{Use KHIM}\fR
Text for a checkbutton that asks whether the user wishes to use KHIM
to manage composed key sequences.
.PP
.SH ACKNOWLEDGMENTS
KHIM was originally inspired by the key bindings that Brent Welch
developed for the 'sedit' editor used in the 'exmh' mail user agent.
The code for KHIM is entirely separate from that for 'sedit'.
.SH KEYWORDS
character, i18n, input, international, method

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/khim/khim\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "khim" n 1\&.0 tklib "Kevin's Hacky Input Method"
.BS
.SH NAME
khim \- Provides key bindings for entering international characters on a keyboard that does not support them
.SH SYNOPSIS
package require \fBTcl \fR
.sp
package require \fBkhim  ?1\&.0?\fR
.sp
\fB::khim::getOptions\fR \fIpath\fR
.sp
\fB::khim::getConfig\fR
.sp
\fB::khim::setConfig\fR \fIversion\fR \fIenabled\fR \fIcompose\fR \fImap\fR
.sp
\fB::khim::showHelp\fR \fIpath\fR
.sp
.BE
.SH DESCRIPTION
This package provides a set of key bindings to allow
a user to enter arbitrary characters on a keyboard that
does not support them\&.  It works by designating some seldom-used key
of the keyboard as a "Compose" key (this key is distinct from any key
so labeled, and is often "Pause," "F12" or "L2"), and having the
"Compose" key, followed by a two-key sequence, have the effect of
inserting some character in a widget\&.
In addition, the "Compose" key, when struck twice in succession,
brings up a dialog containing a Unicode character map, allowing
arbitrary characters to be inserted\&.
.PP
The vast bulk of the package's functionality is implemented in a
single bindtag, \fBKHIM\fR\&.  An application can request that any
text or entry widget use the package to allow for entry of arbitrary
characters by placing this binding tag ahead of the \fBText\fR or
\fBEntry\fR binding tag for the widget:
.CS


text \&.t -width 80 -height 24
bindtags \&.t {\&.t KHIM Text \&. all}

.CE
Note that the \fBKHIM\fR tag must precede the \fBText\fR or
\fBEntry\fR class binding, or the package will not function
correctly\&.
.SH PROCEDURES
In addition to commands supporting the KHIM binding tag, the following
commands are exported from the package:
.TP
\fB::khim::getOptions\fR \fIpath\fR
Posts a top-level modal dialog with the path name \fIpath\fR that
prompts the user for KHIM options\&.  The user is allowed to reconfigure
the key sequences for the "Compose" key, change the choice of key to
use for the "Compose" function, and enable/disable the KHIM key
bindings entirely\&.
.TP
\fB::khim::getConfig\fR
Returns a Tcl script that restores the current configuration of KHIM:
the enabled/disabled state, the choice of "Compose" key, and the key
sequences that may be composed\&.  This script is designed to be
saved to a configuration file for use in a subsequent invocation of
the same application:
.CS


# Save KHIM configuration
set f [open ~/\&.khimrc w]
puts $f [::khim::getConfig]
close $f

# Restore KHIM configuration
source ~/\&.khimrc

.CE
.TP
\fB::khim::setConfig\fR \fIversion\fR \fIenabled\fR \fIcompose\fR \fImap\fR
Restores an earlier saved configuration\&.  Few, if any, applications
will call this command in any other way than to evaluate it as
returned from \fB::khim::getConfig\fR\&.
.TP
\fB::khim::showHelp\fR \fIpath\fR
Displays a top-level dialog giving user-level help for KHIM; the
dialog will have the path name \fIpath\fR\&.
.PP
.SH LOCALISATION
.PP
Programmers who wish to make KHIM available in a non-English-speaking
locale may do so by providing a \fB\&.msg\fR file with the appropriate
localised text\&.  The catalog requires the following messages:
.TP
\fBApply\fR
Text that will appear on the "Apply" button in the dialog that sets
KHIM options\&.
.TP
\fBCancel\fR
Text that will appear on the "Cancel" button in several dialogs\&.
.TP
\fBChange\fR
Text that will appear on the "Change" button, which alters the binding
of a pair of composed characters (creating or replacing as
appropriate)\&.
.TP
\fBCharacter\fR
Text that will appear on the label of the entry widget that accepts a
character resulting from a composed sequence\&.
.TP
\fB{Compose Key}\fR
Window title for a dialog that prompts the user to strike the key that
will be used for the "Compose" key\&.
.TP
\fB{Compose key:}\fR
Label that identifies a component showing the "Compose" key choice in
the KHIM options dialog\&.
.TP
\fB{Composed sequence must be two characters long}\fR
Error message that is displayed if the user attempts to define a
"Compose" sequence that is shorter or longer than two characters\&.
.TP
\fBDelete\fR
Text for a button that deletes a "Compose" sequence\&.
.TP
\fBHelp\&.\&.\&.\fR
Text for a button that displays the KHIM user help dialog\&.
.TP
\fBHELPTEXT\fR
Complete text for the user-level help for KHIM\&.  Refer to
"\fIen\&.msg\fR" for the English-language version of the help\&.
.TP
\fB{Input key sequence}\fR
Text for a label of the entry widget that prompts the user for a
two-character sequence to use with the "Compose" key\&.
.TP
\fB{Insert Character}\fR
Window title of the dialog box that displays a Unicode character map
and prompts the user to select a character to insert\&.
.TP
\fB{Key sequences}\fR
Text for a label at the head of a listbox showing the composed
sequences that are currently bound\&.
.TP
\fB{KHIM Controls}\fR
Window title for the dialog box that prompts for KHIM settings\&.
.TP
\fB{KHIM Help}\fR
Window title for the window that display help text for KHIM\&.
.TP
\fBOK\fR
Label for the OK button on several dialogs\&.
.TP
\fBSelect code page:\fR
Label for a spinbox that prompts the user for a Unicode code page number\&.
.TP
\fBSELECT COMPOSE KEY\fR
A message, which should be composed in short lines, prompting the user
to press the key that will become the "Compose" key in KHIM\&.
.TP
\fBUnicode\&.\&.\&.\fR
Text for a button that brings up the character map to select the
character to which a composed sequence binds\&.
.TP
\fB{Use KHIM}\fR
Text for a checkbutton that asks whether the user wishes to use KHIM
to manage composed key sequences\&.
.PP
.SH ACKNOWLEDGMENTS
KHIM was originally inspired by the key bindings that Brent Welch
developed for the 'sedit' editor used in the 'exmh' mail user agent\&.
The code for KHIM is entirely separate from that for 'sedit'\&.
.SH KEYWORDS
character, i18n, input, international, method

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/menubar/menubar.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2009 Tom Krehbiel <krehbiel.tom@gmail.com> All rights reserved.
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "menubar" n 0.5 tklib "Create and manipulate menubars"
.BS
.SH NAME
menubar \- Creates an instance of the \fImenubar\fR Class.
.SH SYNOPSIS
package require \fBTcl  8.6\fR
.sp
package require \fBTk  8.6\fR
.sp
package require \fBmenubar  ?0.5?\fR
.sp
\fBmenubar new\fR ?options?
.sp
\fImBarInst\fR \fBdefine\fR \fIbody\fR
.sp
\fImBarInst\fR \fBinstall\fR \fIpathName body\fR
.sp
\fImBarInst\fR \fBmenu.configure\fR \fIoption tag-settings ?option tag-settings ...?\fR
.sp
\fImBarInst\fR \fBmenu.namespace\fR \fItag namespace\fR
.sp
\fImBarInst\fR \fBmenu.hide\fR \fItag\fR
.sp
\fImBarInst\fR \fBmenu.show\fR \fItag\fR
.sp
\fImBarInst\fR \fBtag.add\fR \fItag value\fR
.sp
\fImBarInst\fR \fBtag.configure\fR \fIpathName tag ?option value ...option value?\fR
.sp
\fImBarInst\fR \fBtag.cget\fR \fIpathName tag ?option?\fR
.sp
\fImBarInst\fR \fBgroup.add\fR \fItag label ?cmd? ?accel? ?sequence? ?state?\fR
.sp
\fImBarInst\fR \fBgroup.delete\fR \fItag label\fR
.sp
\fImBarInst\fR \fBgroup.move\fR \fIdirection tag label\fR
.sp
\fImBarInst\fR \fBgroup.configure\fR \fItag label ?option value ...option value?\fR
.sp
\fImBarInst\fR \fBgroup.serialize\fR \fItag\fR
.sp
\fImBarInst\fR \fBgroup.deserialize\fR \fItag stream\fR
.sp
\fImBarInst\fR \fBnotebook.addTabStore\fR \fIpathname\fR
.sp
\fImBarInst\fR \fBnotebook.deleteTabStore\fR \fIpathname\fR
.sp
\fImBarInst\fR \fBnotebook.setTabValue\fR \fIpathname tag\fR
.sp
\fImBarInst\fR \fBnotebook.restoreTabValues\fR \fIpathname\fR
.sp
.BE
.SH DESCRIPTION
.TP
\fBmenubar new\fR ?options?
.PP
.PP
Create and return a new instance of the menubar class. The
menubar class encapsulates the definition, installation and
dynamic behavior of a menubar. The class doesn't depend on a
widget framework and therefore can be used with or without a
framework (e.g. Bwidget, IWidget, Snit, etc.). Unlike other Tk
widget commands, the menubar command doesn't have a \fIpathName\fR
argument because menubars are handled by the window manager (i.e. wm)
and not the application.
.SH OPTIONS
The following options can be passed to the \fImenubar new\fR command.
.PP
These options are inherited from the Tk menu command, their effect is
platform specific.
.TP
\fB\fI-activebackground\fR [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-activebackground]\fR
.TP
\fB\fI-activeborderwidth\fR [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-activeborderwidth]\fR
.TP
\fB\fI-activeforeground\fR [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-activeforeground]\fR
.TP
\fB\fI-background\fR [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-background]\fR
.TP
\fB\fI-borderwidth\fR [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-borderwidth]\fR
.TP
\fB\fI-cursor\fR [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-cursor]\fR
.TP
\fB\fI-disabledforeground\fR [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-disabledforeground]\fR
.TP
\fB\fI-font\fR [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-font]\fR
.TP
\fB\fI-foreground\fR [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-foreground]\fR
.TP
\fB\fI-relief\fR [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-relief]\fR
.PP
.SH INTRODUCTION
.PP
An instance of the menubar class provides methods for compiling a
description of the menubar, configuring menu items and
installing the menubar in toplevel windows.
.PP
A menubar can be thought of as a tree of cascading menus. Users define
a menubar using a language that results in a human readable description
of a menubar. The description of the menubar is then compiled by an
instance of the menubar class after which it can be installed in one or more
toplevel windows.
.PP
The menubar class provides many unique capabilities that are not
found in other tcl/tk menubar implementation. Some of these are:
.IP \(bu
A tagging system that simplifies access to menu entries in the menu tree.
.IP \(bu
Support for user defined tags that depend on the toplevel window context.
.IP \(bu
A simplified and uniform interface for all callback commands.
.IP \(bu
Namespace support for all callback commands so callback commands can be easily grouped into namespaces.
.IP \(bu
Support for hiding and exposing menus on the menubar.
.IP \(bu
A simplified method for creating radiobutton groups.
.IP \(bu
Automatic management of state variables for checkbuttons and radiobuttons.
.IP \(bu
Scope control for the state variables of checkbuttons and radiobuttons.
.IP \(bu
Tear-off menu management that ensures only one tearoff menu is created.
.IP \(bu
Support for dynamic menu extension to simplify the creation of recent document menus.
.IP \(bu
Support for saving and restoring dynamic menu extensions.
.PP
.SH TERMINOLOGY
.TP
MENUBAR
The visible rendering of a menubar in a toplevel window is a horizontally
group of cascading Tk menus.
.TP
MENU
A menu is an ordered list of items that is rendered
vertically. Menus are not visible until a user
preforms some action (normally a <ButtonPress-1> event). A menu
may contain any number of child menus that are rendered as
cascading menus. Cascading menus are rendered next to the parent menu
when they are activated.
.TP
MENU ENTRY
A menu contains an ordered list of items called entries.
Menu entries have a type and the menubar class supports the
following 6 entry types:
\fICommand\fR, \fICheckbutton\fR, \fIRadiobutton\fR, \fISeparator\fR, \fIGroup\fR and \fIMenu\fR.
.TP
ENTRY LABEL
Each menu entry has a visible string that is called the entry label.
.TP
TAG
A tag is name that is normally used to referr to an item in a menu
tree. A tag name is an alphanumeric character string
that may include the underscore character. Menu tree tags are
defined for all nodes and leafs in a menu tree. This provides a
flat abstraction of the tree and simplifies item referencing in
menubar methods. Without this abstraction it would be
necessary to reference menu elements using a tree path which
could change at run-time. The menubar class also has a method that
can create a user defined tag. User
defined tags store values that change based on the currently
active toplevel window. User defined tags can be used to store widget
pathnames use by callback code so that output can be routed to the
appropriate toplevel window.
.PP
.SH METHODS
.TP
\fImBarInst\fR \fBdefine\fR \fIbody\fR
Compiles \fIbody\fR into a tree of menu entries which define the
visual layout of the menubar. The \fIbody\fR argument
describes the layout using the following syntax, where the
elements of the syntax are described below.
.sp
\fIbody == definitions\fR
.CS


definitions    ::= { <ignore> | <definition> | <definition> <definitions> }
ignore         ::= { <nl> | <white-space> <nl> | # <comment> <nl> }
................................................................................

.CE
.IP
\fI \fR
.RS
.TP
C - Command
The C type entry is the most common type of entry. This entry executes
a command when it is invoked.
.TP
X - Checkbutton
A X type entry behaves much like a Tk checkbutton
widget. When it is invoked it toggles back and forth between
a selected and deselected states. The value of a checkbutton
is a boolean (i.e. 1 or 0). By default all checkbuttons are
deselected. If you want the checkbutton to be initially selected
then include a trailing plus (+) with the tag name. See SCOPE CONTROL
below for a description of the scope indicator.
.TP
R - Radiobutton
A R type menu entry behaves much like a Tk radiobutton widget. Each
radiobutton entry is a member of a radiobutton group that
controls the behavior of the radiobuttons in the group. All
radiobuttons in a group are given the same tag name. In the
example below Red, Green and Blue all have the same tag and are
therefore all in the same radiobutton group. A trailing plus
(+) on the tag name of a radiobutton entry will cause the entry to be
the initially selected entry. See SCOPE CONTROL
below for a description of the scope indicator.
.TP
S - Separator
A S type menu entry is an entry that is displayed either as a horizontal
dividing line or a label. Separators are not active elements of a menu and
have no associated behavior if they are invoked. If <stext> is two dashes
(i.e. '--') then the separator will be displayed as a horizontal line
otherwise <stext> will be displayed as a bold label surrounded by double
dashes (e.g. "-- <stext> --") with a lightgray background.
.TP
G - Command Group
The G type menu entry marks a location in the menu tree where
entries can be dynamically added and removed. Menu extension can only
occur at the end of a menu so G type entries must be the last item on a menu.
A G	type entry is rendered as a separator line. The \fIgroup.<xxx>\fR
sub-commands are used to manipulate command group entries.
.TP
M - Menu
An M type entry is used to define both menubar menus and cascading
menus. Menu entries are the most complicated of the 6 menu types.
A menu entry is composed of three list elements. The first element
of the list is its label. The second element of the list is a
composite string consisting of a type identifier (M) followed by
an optional tag (beginning with a ':' separator) and finally an
optional plus (+) which indicates that the menu is a tear-off
menu. The final element of the list is a LIST VALUE.
.RE
.PP
.TP
\fImBarInst\fR \fBinstall\fR \fIpathName body\fR
The \fIinstall\fR method installs the menubar created with the
\fIdefine\fR method into toplevel window \fIpathName\fR. The
\fIbody\fR argument of the command contains a tcl script which
is used to initialize the installed menubar. Normally the tcl
script will contain calls to various menubar methods to perform
the initialization. The initialization code is only run once
when the menubar is installed. The namespace in which the \fIinstall\fR
method is executed becomes the default namespace for callback commands
(see \fImenu.namespace\fR below for more details).
.PP
.SH "METHODS - MENU.XXX"
.TP
\fImBarInst\fR \fBmenu.configure\fR \fIoption tag-settings ?option tag-settings ...?\fR
Configures the tags of a menubar and returns an empty string. This method provides a convenient
way to configure a larger number of tags without the verbosity of using the \fItag.configure\fR method.
.RS
.TP
\fIoption\fR
\fIOption\fR may have any of the values accepted by the \fItag.configure\fR method.
.TP
\fItag-settings\fR
The \fItag-settings\fR argument is a string that is converted to a list of tag-value pairs
using the following syntax.
.sp
Syntax for \fItag-settings\fR.
.CS


tag-settings ::= { <ignore> | <value> | <value> <tag-settings> }
ignore       ::= { <nl> | <white-space> <nl> | # <comment> <nl> }
value        ::= <tag> <option-value> <nl>

.CE
.RE
.PP
.TP
\fImBarInst\fR \fBmenu.namespace\fR \fItag namespace\fR
Change the namespace for a sub-tree of the menubar
starting at entry \fItag\fR. The new value will be \fInamespace\fR.
Each entry in the menubar tree has an
associated namespace which will be used for its callback
procedure. The default namespace is the namespace where
the \fIinstall\fR  method was executed. The \fInamespace\fR
method can be used to change the namespace
that will be used for callbacks in a sub-tree of the
menubar. This method can only be used in the context of
an \fIinstall\fR script.
.PP
.TP
\fImBarInst\fR \fBmenu.hide\fR \fItag\fR
Remove (hide) a menubar entry. When a
menubar tree is defined all entries are visible by default.
This method can be used to hide a menubar entry.
The \fIhide\fR methods can be used in the
context of an \fIinstall\fR script so that a menu will be
initially hidden at application start up. The \fItag\fR argument
is the tag name of the menu to be hidden.
.TP
\fImBarInst\fR \fBmenu.show\fR \fItag\fR
Exposes (shows) a hidden menubar entry. When a
menubar tree is defined all entries are visible by default.
If a entry is hidden from the user (using the menu.hide method)
then it can be exposed again using the show method. The \fItag\fR
argument is the tag name of the menu to be shown.
.PP
.SH "METHODS - TAG.XXX"
.TP
\fImBarInst\fR \fBtag.add\fR \fItag value\fR
Add a user defined \fItag\fR value. The \fItag.add\fR method
adds a new tag-value pair to the the tags defined for a
menubar. User defined tags are different from the tags
created by the \fIdefine\fR method. The \fItag.add\fR
method can only be used in an \fIinstall\fR script and its
value is associated with the toplevel where the menubar is
installed. This makes the tag context sensitive so callback
code that queries the tag value will receive a value that
is associated with the window that performed the callback.
.PP
.TP
\fImBarInst\fR \fBtag.configure\fR \fIpathName tag ?option value ...option value?\fR
Given the \fIpathName\fR of a toplevel window and a \fItag\fR this method configures the
menu entry associated with the tag and return an empty string.
.RS
.TP
\fIStandard Options\fR
These option are the same as those described for menu entries in the Tk \fImenu\fR documentation.
.RS
.TP
\fB-activebackground\fR
.TP
\fB-activeforeground\fR
.TP
\fB-background\fR
................................................................................
.IP
\fI \fR
.TP
Class Specific Options
.RS
.TP
\fB-bind\fR {uline accel sequence}
The value of the \fI-bind\fR option is three element list where the values are as follows.
.RS
.TP
uline
An integer index of a character to underline in the entry.
This value performs the same function as the Tk \fImenu\fR -underline option.
If this value is an empty string then no underlining is performed.
.TP
accel
A string to display at the right side of the menu
entry. The string normally describes an accelerator keystroke sequence that
may be typed to invoke the same function as the menu entry.
This value performs the same function as the Tk \fImenu\fR -accelerator option.
If this value is an empty string then no accelerator is displayed.
.TP
sequence
A bind sequence that will cause the entries associated command to fire.
.RE
.TP
\fB-command\fR cmdprefix
The value of the \fI-command\fR option a command
prefix that is evaluated when the menu entry is invoked.
By default the callback is evaluate in the
namespace where the \fIinstall\fR method was executed. Additional values
are appended to the \fIcmdprefix\fR and are thus passed to the
callback command as argument. These additional arguments are described
in the list below.
.RS
.TP
command entry
1) The pathname of the toplevel window that invoked the callback.
.TP
checkbutton entry
1) The pathname of the toplevel window that invoked the callback.
.sp
2) The checkbutton's tag name
.sp
3) The new value for the checkbutton
.TP
radiobutton entry
1) The pathname of the toplevel window that invoked the callback.
.sp
2) The radiobutton's tag name
.sp
3) The label of the button that was selected
.TP
group entry
1) The pathname of the toplevel window that invoked the callback.
.RE
.RE
.RE
.PP
.TP
\fImBarInst\fR \fBtag.cget\fR \fIpathName tag ?option?\fR
Returns the value of the configuration option given by \fIoption\fR
or the value of a user defined tag. The option argument may be any
of the options accepted by the \fItag.configure\fR method for the
\fItag\fR type. User defined tags are queried without an \fIoption\fR
value.
.PP
.SH "METHODS - GROUP.XXX"
.TP
\fImBarInst\fR \fBgroup.add\fR \fItag label ?cmd? ?accel? ?sequence? ?state?\fR
Add a command to the group with tag name \fItag\fR. This method
appends a new command entry to the end of a command group. The order of the
arguments is fixed but arguments to the right can be ignored. Arguments to
this method have the following meaning.
.RS
.TP
tag \fI(string)\fR
The tag name of the command group.
.TP
label \fI(string)\fR
The displayed label for the menu entry.
.TP
cmd \fI(string)\fR
A command prefix that will be used for callback command.
.TP
accel \fI(string)\fR
An accelerator string that will be displayed next to the entry label.
.TP
sequence \fI(string)\fR
A bind sequence that will be bound to the callback command.
.TP
state \fI(enum)\fR
Sets the active state of the command. One of:  normal, disabled, active
.RE
.PP
.TP
\fImBarInst\fR \fBgroup.delete\fR \fItag label\fR
Delete a command from a group with tag name \fItag\fR. This method
deletes command \fIlabel\fR from a command group.
.PP
.TP
\fImBarInst\fR \fBgroup.move\fR \fIdirection tag label\fR
Change the position of an entry in a group with tag name \fItag\fR.
The \fIdirection\fR argument is the direction ('up' or 'down') the
entry will be moved. The entry that is moved has the name \fIlabel\fR.
.PP
.TP
\fImBarInst\fR \fBgroup.configure\fR \fItag label ?option value ...option value?\fR
Configure the options of an entry in the command group with
tag name \fItag\fR. This method is similar to the \fItag.configure\fR
method except that it works on entries in a command group. Set documentation
for the \fItag.configure\fR method (above) for more details on command
entry options.
.PP
.TP
\fImBarInst\fR \fBgroup.serialize\fR \fItag\fR
Return a string serialization of the entries in a command group. The
argument \fItag\fR is the tag name for the group that is to be serialized.
The resulting serialization is a list containing three
element  (1) the tag name of the group  (2) a dictionary
containing group level options (3) a list of zero or more similar three
element lists that describe the entries in the group.
.PP
.TP
\fImBarInst\fR \fBgroup.deserialize\fR \fItag stream\fR
Replace the contents of group tag \fItag\fR with the commands
defined in the serialization \fIstream\fR. The original contents of
the group are lost.
.PP
.SH "METHODS - NOTEBOOK.XXX"
.TP
\fImBarInst\fR \fBnotebook.addTabStore\fR \fIpathname\fR
This method should be used in code that creates a new notebook tab.
Execution of this method will cause state storage to be allocated
for the new notebook tab. The pathname for the notebook tab is passed
as an argument to the method.
.PP
.TP
\fImBarInst\fR \fBnotebook.deleteTabStore\fR \fIpathname\fR
This command deallocates the state store for a notebook tab. The
pathname for the notebook tab is passed as an argument to the method.
.PP
.TP
\fImBarInst\fR \fBnotebook.setTabValue\fR \fIpathname tag\fR
This method should be used in the callback for menubar checkbuttons or
radiobuttons that have notebook tab scope control. When this method is
executed it will move the value associated with tag into the tab store
for the tab identified by pathname.
.PP
.TP
\fImBarInst\fR \fBnotebook.restoreTabValues\fR \fIpathname\fR
This method should be place in a bind script that is triggered by
a notebooks <<NotebookTabChanged>> event.
.PP
.SH "SCOPE CONTROL"
.PP
By default a menubar instance looks the same in all installed toplevel
windows. As changes are made to one instance of a menubar all the other
instances are immediately updated. This means the internal state of all
the menu entries for the instances are synchronized. This behavior is
called global scope control of the menubar state.
.PP
The menubar class allows finer scope control on check and radio buttons.
The scope of these entry types can be modified by adding a
modifier character to their type character. Two
modifier characters are supported as show in the table below.
.CS


''  ::= global scope (no character)
'@' ::= local scope modifier
'=' ::= notebook tab scope modifier

.CE
.PP
When the local scope character (@) is added to the definition of a button,
the button is given a new variable for each installed toplevel window. This
has the effect of making the button's state local to the window (i.e. local scope).
An example use case for this behavior might be a status bar that can be
toggled on an off by a checkbutton. The developer may want to allow the
user to control the visibility of the status bar on a per window basis. In this
case a local modifier would be added to the status bar selector so the callback
code would receive an appropriate value based on the current toplevel window.
.PP
The notebook tab scope character (=) is similar in effect to the local scope
character but it allows a notebook tab selection to also manage the state of
of a button. Adding the notebook tab scope modifier enables notebook tab
scope control but the developer must then make use of the notebook.xxxx sub-commands
to actively manage state values as tabs are added, deleted and selected.
.SH EXAMPLE
.CS


package require Tcl
package require Tk
package require menubar

set tout [text .t -width 25 -height 12]
pack ${tout} -expand 1 -fill both
set mbar [menubar new \\
    -borderwidth 4 \\
    -relief groove  \\
    -foreground black \\
    -background tan \\
    ]
................................................................................
                }
        }
    }
    Help M:help {
        About               C       about
    }
}
${mbar} install . {
    ${mbar} tag.add tout ${tout}
    ${mbar} menu.configure -command {
        # file menu
        exit            {Exit}
        # Item menu
        cut             {CB Edit cut}
        copy            {CB Edit copy}
        paste           {CB Edit paste}
        # boolean menu
................................................................................
        exit red
    } -foreground {
        exit white
    }
}
proc pout { txt } {
    global mbar
    set tout [${mbar} tag.cget . tout]
    ${tout} insert end "${txt}\\n"
}
proc Exit { args } {
    puts "Goodbye"
    exit
}
proc CB { args } {
    set alist [lassign ${args} cmd]
    pout "${cmd}: [join ${alist} {, }]"
}
wm minsize . 300 300
wm geometry . +4+4
wm protocol . WM_DELETE_WINDOW exit
wm title . "Example"
wm focusmodel . active
pout "Example started ..."

.CE
.SH CAVEATS
.PP
This implementation uses TclOO so it requires 8.6. The code has been
tested on Windows (Vista), Linux and OSX (10.4).
.SH "SEE ALSO"
\fIA command that creates menubar objects\fR [http://wiki.tcl.tk/25231], \fImenu\fR [http://www.tcl.tk/man/tcl8.6/TkCmd/menu.htm]
.SH COPYRIGHT
.nf
Copyright (c) 2009 Tom Krehbiel <krehbiel.tom@gmail.com> All rights reserved.

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/menubar/menubar\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2009 Tom Krehbiel <krehbiel\&.tom@gmail\&.com> All rights reserved\&.
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "menubar" n 0\&.5 tklib "Create and manipulate menubars"
.BS
.SH NAME
menubar \- Creates an instance of the \fImenubar\fR Class\&.
.SH SYNOPSIS
package require \fBTcl  8\&.6\fR
.sp
package require \fBTk  8\&.6\fR
.sp
package require \fBmenubar  ?0\&.5?\fR
.sp
\fBmenubar new\fR ?options?
.sp
\fImBarInst\fR \fBdefine\fR \fIbody\fR
.sp
\fImBarInst\fR \fBinstall\fR \fIpathName body\fR
.sp
\fImBarInst\fR \fBmenu\&.configure\fR \fIoption tag-settings ?option tag-settings \&.\&.\&.?\fR
.sp
\fImBarInst\fR \fBmenu\&.namespace\fR \fItag namespace\fR
.sp
\fImBarInst\fR \fBmenu\&.hide\fR \fItag\fR
.sp
\fImBarInst\fR \fBmenu\&.show\fR \fItag\fR
.sp
\fImBarInst\fR \fBtag\&.add\fR \fItag value\fR
.sp
\fImBarInst\fR \fBtag\&.configure\fR \fIpathName tag ?option value \&.\&.\&.option value?\fR
.sp
\fImBarInst\fR \fBtag\&.cget\fR \fIpathName tag ?option?\fR
.sp
\fImBarInst\fR \fBgroup\&.add\fR \fItag label ?cmd? ?accel? ?sequence? ?state?\fR
.sp
\fImBarInst\fR \fBgroup\&.delete\fR \fItag label\fR
.sp
\fImBarInst\fR \fBgroup\&.move\fR \fIdirection tag label\fR
.sp
\fImBarInst\fR \fBgroup\&.configure\fR \fItag label ?option value \&.\&.\&.option value?\fR
.sp
\fImBarInst\fR \fBgroup\&.serialize\fR \fItag\fR
.sp
\fImBarInst\fR \fBgroup\&.deserialize\fR \fItag stream\fR
.sp
\fImBarInst\fR \fBnotebook\&.addTabStore\fR \fIpathname\fR
.sp
\fImBarInst\fR \fBnotebook\&.deleteTabStore\fR \fIpathname\fR
.sp
\fImBarInst\fR \fBnotebook\&.setTabValue\fR \fIpathname tag\fR
.sp
\fImBarInst\fR \fBnotebook\&.restoreTabValues\fR \fIpathname\fR
.sp
.BE
.SH DESCRIPTION
.TP
\fBmenubar new\fR ?options?
.PP
.PP
Create and return a new instance of the menubar class\&. The
menubar class encapsulates the definition, installation and
dynamic behavior of a menubar\&. The class doesn't depend on a
widget framework and therefore can be used with or without a
framework (e\&.g\&. Bwidget, IWidget, Snit, etc\&.)\&. Unlike other Tk
widget commands, the menubar command doesn't have a \fIpathName\fR
argument because menubars are handled by the window manager (i\&.e\&. wm)
and not the application\&.
.SH OPTIONS
The following options can be passed to the \fImenubar new\fR command\&.
.PP
These options are inherited from the Tk menu command, their effect is
platform specific\&.
.TP
\fB\fI-activebackground\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-activebackground]\fR
.TP
\fB\fI-activeborderwidth\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-activeborderwidth]\fR
.TP
\fB\fI-activeforeground\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-activeforeground]\fR
.TP
\fB\fI-background\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-background]\fR
.TP
\fB\fI-borderwidth\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-borderwidth]\fR
.TP
\fB\fI-cursor\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-cursor]\fR
.TP
\fB\fI-disabledforeground\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-disabledforeground]\fR
.TP
\fB\fI-font\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-font]\fR
.TP
\fB\fI-foreground\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-foreground]\fR
.TP
\fB\fI-relief\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-relief]\fR
.PP
.SH INTRODUCTION
.PP
An instance of the menubar class provides methods for compiling a
description of the menubar, configuring menu items and
installing the menubar in toplevel windows\&.
.PP
A menubar can be thought of as a tree of cascading menus\&. Users define
a menubar using a language that results in a human readable description
of a menubar\&. The description of the menubar is then compiled by an
instance of the menubar class after which it can be installed in one or more
toplevel windows\&.
.PP
The menubar class provides many unique capabilities that are not
found in other tcl/tk menubar implementation\&. Some of these are:
.IP \(bu
A tagging system that simplifies access to menu entries in the menu tree\&.
.IP \(bu
Support for user defined tags that depend on the toplevel window context\&.
.IP \(bu
A simplified and uniform interface for all callback commands\&.
.IP \(bu
Namespace support for all callback commands so callback commands can be easily grouped into namespaces\&.
.IP \(bu
Support for hiding and exposing menus on the menubar\&.
.IP \(bu
A simplified method for creating radiobutton groups\&.
.IP \(bu
Automatic management of state variables for checkbuttons and radiobuttons\&.
.IP \(bu
Scope control for the state variables of checkbuttons and radiobuttons\&.
.IP \(bu
Tear-off menu management that ensures only one tearoff menu is created\&.
.IP \(bu
Support for dynamic menu extension to simplify the creation of recent document menus\&.
.IP \(bu
Support for saving and restoring dynamic menu extensions\&.
.PP
.SH TERMINOLOGY
.TP
MENUBAR
The visible rendering of a menubar in a toplevel window is a horizontally
group of cascading Tk menus\&.
.TP
MENU
A menu is an ordered list of items that is rendered
vertically\&. Menus are not visible until a user
preforms some action (normally a <ButtonPress-1> event)\&. A menu
may contain any number of child menus that are rendered as
cascading menus\&. Cascading menus are rendered next to the parent menu
when they are activated\&.
.TP
MENU ENTRY
A menu contains an ordered list of items called entries\&.
Menu entries have a type and the menubar class supports the
following 6 entry types:
\fICommand\fR, \fICheckbutton\fR, \fIRadiobutton\fR, \fISeparator\fR, \fIGroup\fR and \fIMenu\fR\&.
.TP
ENTRY LABEL
Each menu entry has a visible string that is called the entry label\&.
.TP
TAG
A tag is name that is normally used to referr to an item in a menu
tree\&. A tag name is an alphanumeric character string
that may include the underscore character\&. Menu tree tags are
defined for all nodes and leafs in a menu tree\&. This provides a
flat abstraction of the tree and simplifies item referencing in
menubar methods\&. Without this abstraction it would be
necessary to reference menu elements using a tree path which
could change at run-time\&. The menubar class also has a method that
can create a user defined tag\&. User
defined tags store values that change based on the currently
active toplevel window\&. User defined tags can be used to store widget
pathnames use by callback code so that output can be routed to the
appropriate toplevel window\&.
.PP
.SH METHODS
.TP
\fImBarInst\fR \fBdefine\fR \fIbody\fR
Compiles \fIbody\fR into a tree of menu entries which define the
visual layout of the menubar\&. The \fIbody\fR argument
describes the layout using the following syntax, where the
elements of the syntax are described below\&.
.sp
\fIbody == definitions\fR
.CS


definitions    ::= { <ignore> | <definition> | <definition> <definitions> }
ignore         ::= { <nl> | <white-space> <nl> | # <comment> <nl> }
................................................................................

.CE
.IP
\fI \fR
.RS
.TP
C - Command
The C type entry is the most common type of entry\&. This entry executes
a command when it is invoked\&.
.TP
X - Checkbutton
A X type entry behaves much like a Tk checkbutton
widget\&. When it is invoked it toggles back and forth between
a selected and deselected states\&. The value of a checkbutton
is a boolean (i\&.e\&. 1 or 0)\&. By default all checkbuttons are
deselected\&. If you want the checkbutton to be initially selected
then include a trailing plus (+) with the tag name\&. See SCOPE CONTROL
below for a description of the scope indicator\&.
.TP
R - Radiobutton
A R type menu entry behaves much like a Tk radiobutton widget\&. Each
radiobutton entry is a member of a radiobutton group that
controls the behavior of the radiobuttons in the group\&. All
radiobuttons in a group are given the same tag name\&. In the
example below Red, Green and Blue all have the same tag and are
therefore all in the same radiobutton group\&. A trailing plus
(+) on the tag name of a radiobutton entry will cause the entry to be
the initially selected entry\&. See SCOPE CONTROL
below for a description of the scope indicator\&.
.TP
S - Separator
A S type menu entry is an entry that is displayed either as a horizontal
dividing line or a label\&. Separators are not active elements of a menu and
have no associated behavior if they are invoked\&. If <stext> is two dashes
(i\&.e\&. '--') then the separator will be displayed as a horizontal line
otherwise <stext> will be displayed as a bold label surrounded by double
dashes (e\&.g\&. "-- <stext> --") with a lightgray background\&.
.TP
G - Command Group
The G type menu entry marks a location in the menu tree where
entries can be dynamically added and removed\&. Menu extension can only
occur at the end of a menu so G type entries must be the last item on a menu\&.
A G	type entry is rendered as a separator line\&. The \fIgroup\&.<xxx>\fR
sub-commands are used to manipulate command group entries\&.
.TP
M - Menu
An M type entry is used to define both menubar menus and cascading
menus\&. Menu entries are the most complicated of the 6 menu types\&.
A menu entry is composed of three list elements\&. The first element
of the list is its label\&. The second element of the list is a
composite string consisting of a type identifier (M) followed by
an optional tag (beginning with a ':' separator) and finally an
optional plus (+) which indicates that the menu is a tear-off
menu\&. The final element of the list is a LIST VALUE\&.
.RE
.PP
.TP
\fImBarInst\fR \fBinstall\fR \fIpathName body\fR
The \fIinstall\fR method installs the menubar created with the
\fIdefine\fR method into toplevel window \fIpathName\fR\&. The
\fIbody\fR argument of the command contains a tcl script which
is used to initialize the installed menubar\&. Normally the tcl
script will contain calls to various menubar methods to perform
the initialization\&. The initialization code is only run once
when the menubar is installed\&. The namespace in which the \fIinstall\fR
method is executed becomes the default namespace for callback commands
(see \fImenu\&.namespace\fR below for more details)\&.
.PP
.SH "METHODS - MENU\&.XXX"
.TP
\fImBarInst\fR \fBmenu\&.configure\fR \fIoption tag-settings ?option tag-settings \&.\&.\&.?\fR
Configures the tags of a menubar and returns an empty string\&. This method provides a convenient
way to configure a larger number of tags without the verbosity of using the \fItag\&.configure\fR method\&.
.RS
.TP
\fIoption\fR
\fIOption\fR may have any of the values accepted by the \fItag\&.configure\fR method\&.
.TP
\fItag-settings\fR
The \fItag-settings\fR argument is a string that is converted to a list of tag-value pairs
using the following syntax\&.
.sp
Syntax for \fItag-settings\fR\&.
.CS


tag-settings ::= { <ignore> | <value> | <value> <tag-settings> }
ignore       ::= { <nl> | <white-space> <nl> | # <comment> <nl> }
value        ::= <tag> <option-value> <nl>

.CE
.RE
.PP
.TP
\fImBarInst\fR \fBmenu\&.namespace\fR \fItag namespace\fR
Change the namespace for a sub-tree of the menubar
starting at entry \fItag\fR\&. The new value will be \fInamespace\fR\&.
Each entry in the menubar tree has an
associated namespace which will be used for its callback
procedure\&. The default namespace is the namespace where
the \fIinstall\fR  method was executed\&. The \fInamespace\fR
method can be used to change the namespace
that will be used for callbacks in a sub-tree of the
menubar\&. This method can only be used in the context of
an \fIinstall\fR script\&.
.PP
.TP
\fImBarInst\fR \fBmenu\&.hide\fR \fItag\fR
Remove (hide) a menubar entry\&. When a
menubar tree is defined all entries are visible by default\&.
This method can be used to hide a menubar entry\&.
The \fIhide\fR methods can be used in the
context of an \fIinstall\fR script so that a menu will be
initially hidden at application start up\&. The \fItag\fR argument
is the tag name of the menu to be hidden\&.
.TP
\fImBarInst\fR \fBmenu\&.show\fR \fItag\fR
Exposes (shows) a hidden menubar entry\&. When a
menubar tree is defined all entries are visible by default\&.
If a entry is hidden from the user (using the menu\&.hide method)
then it can be exposed again using the show method\&. The \fItag\fR
argument is the tag name of the menu to be shown\&.
.PP
.SH "METHODS - TAG\&.XXX"
.TP
\fImBarInst\fR \fBtag\&.add\fR \fItag value\fR
Add a user defined \fItag\fR value\&. The \fItag\&.add\fR method
adds a new tag-value pair to the the tags defined for a
menubar\&. User defined tags are different from the tags
created by the \fIdefine\fR method\&. The \fItag\&.add\fR
method can only be used in an \fIinstall\fR script and its
value is associated with the toplevel where the menubar is
installed\&. This makes the tag context sensitive so callback
code that queries the tag value will receive a value that
is associated with the window that performed the callback\&.
.PP
.TP
\fImBarInst\fR \fBtag\&.configure\fR \fIpathName tag ?option value \&.\&.\&.option value?\fR
Given the \fIpathName\fR of a toplevel window and a \fItag\fR this method configures the
menu entry associated with the tag and return an empty string\&.
.RS
.TP
\fIStandard Options\fR
These option are the same as those described for menu entries in the Tk \fImenu\fR documentation\&.
.RS
.TP
\fB-activebackground\fR
.TP
\fB-activeforeground\fR
.TP
\fB-background\fR
................................................................................
.IP
\fI \fR
.TP
Class Specific Options
.RS
.TP
\fB-bind\fR {uline accel sequence}
The value of the \fI-bind\fR option is three element list where the values are as follows\&.
.RS
.TP
uline
An integer index of a character to underline in the entry\&.
This value performs the same function as the Tk \fImenu\fR -underline option\&.
If this value is an empty string then no underlining is performed\&.
.TP
accel
A string to display at the right side of the menu
entry\&. The string normally describes an accelerator keystroke sequence that
may be typed to invoke the same function as the menu entry\&.
This value performs the same function as the Tk \fImenu\fR -accelerator option\&.
If this value is an empty string then no accelerator is displayed\&.
.TP
sequence
A bind sequence that will cause the entries associated command to fire\&.
.RE
.TP
\fB-command\fR cmdprefix
The value of the \fI-command\fR option a command
prefix that is evaluated when the menu entry is invoked\&.
By default the callback is evaluate in the
namespace where the \fIinstall\fR method was executed\&. Additional values
are appended to the \fIcmdprefix\fR and are thus passed to the
callback command as argument\&. These additional arguments are described
in the list below\&.
.RS
.TP
command entry
1) The pathname of the toplevel window that invoked the callback\&.
.TP
checkbutton entry
1) The pathname of the toplevel window that invoked the callback\&.
.sp
2) The checkbutton's tag name
.sp
3) The new value for the checkbutton
.TP
radiobutton entry
1) The pathname of the toplevel window that invoked the callback\&.
.sp
2) The radiobutton's tag name
.sp
3) The label of the button that was selected
.TP
group entry
1) The pathname of the toplevel window that invoked the callback\&.
.RE
.RE
.RE
.PP
.TP
\fImBarInst\fR \fBtag\&.cget\fR \fIpathName tag ?option?\fR
Returns the value of the configuration option given by \fIoption\fR
or the value of a user defined tag\&. The option argument may be any
of the options accepted by the \fItag\&.configure\fR method for the
\fItag\fR type\&. User defined tags are queried without an \fIoption\fR
value\&.
.PP
.SH "METHODS - GROUP\&.XXX"
.TP
\fImBarInst\fR \fBgroup\&.add\fR \fItag label ?cmd? ?accel? ?sequence? ?state?\fR
Add a command to the group with tag name \fItag\fR\&. This method
appends a new command entry to the end of a command group\&. The order of the
arguments is fixed but arguments to the right can be ignored\&. Arguments to
this method have the following meaning\&.
.RS
.TP
tag \fI(string)\fR
The tag name of the command group\&.
.TP
label \fI(string)\fR
The displayed label for the menu entry\&.
.TP
cmd \fI(string)\fR
A command prefix that will be used for callback command\&.
.TP
accel \fI(string)\fR
An accelerator string that will be displayed next to the entry label\&.
.TP
sequence \fI(string)\fR
A bind sequence that will be bound to the callback command\&.
.TP
state \fI(enum)\fR
Sets the active state of the command\&. One of:  normal, disabled, active
.RE
.PP
.TP
\fImBarInst\fR \fBgroup\&.delete\fR \fItag label\fR
Delete a command from a group with tag name \fItag\fR\&. This method
deletes command \fIlabel\fR from a command group\&.
.PP
.TP
\fImBarInst\fR \fBgroup\&.move\fR \fIdirection tag label\fR
Change the position of an entry in a group with tag name \fItag\fR\&.
The \fIdirection\fR argument is the direction ('up' or 'down') the
entry will be moved\&. The entry that is moved has the name \fIlabel\fR\&.
.PP
.TP
\fImBarInst\fR \fBgroup\&.configure\fR \fItag label ?option value \&.\&.\&.option value?\fR
Configure the options of an entry in the command group with
tag name \fItag\fR\&. This method is similar to the \fItag\&.configure\fR
method except that it works on entries in a command group\&. Set documentation
for the \fItag\&.configure\fR method (above) for more details on command
entry options\&.
.PP
.TP
\fImBarInst\fR \fBgroup\&.serialize\fR \fItag\fR
Return a string serialization of the entries in a command group\&. The
argument \fItag\fR is the tag name for the group that is to be serialized\&.
The resulting serialization is a list containing three
element  (1) the tag name of the group  (2) a dictionary
containing group level options (3) a list of zero or more similar three
element lists that describe the entries in the group\&.
.PP
.TP
\fImBarInst\fR \fBgroup\&.deserialize\fR \fItag stream\fR
Replace the contents of group tag \fItag\fR with the commands
defined in the serialization \fIstream\fR\&. The original contents of
the group are lost\&.
.PP
.SH "METHODS - NOTEBOOK\&.XXX"
.TP
\fImBarInst\fR \fBnotebook\&.addTabStore\fR \fIpathname\fR
This method should be used in code that creates a new notebook tab\&.
Execution of this method will cause state storage to be allocated
for the new notebook tab\&. The pathname for the notebook tab is passed
as an argument to the method\&.
.PP
.TP
\fImBarInst\fR \fBnotebook\&.deleteTabStore\fR \fIpathname\fR
This command deallocates the state store for a notebook tab\&. The
pathname for the notebook tab is passed as an argument to the method\&.
.PP
.TP
\fImBarInst\fR \fBnotebook\&.setTabValue\fR \fIpathname tag\fR
This method should be used in the callback for menubar checkbuttons or
radiobuttons that have notebook tab scope control\&. When this method is
executed it will move the value associated with tag into the tab store
for the tab identified by pathname\&.
.PP
.TP
\fImBarInst\fR \fBnotebook\&.restoreTabValues\fR \fIpathname\fR
This method should be place in a bind script that is triggered by
a notebooks <<NotebookTabChanged>> event\&.
.PP
.SH "SCOPE CONTROL"
.PP
By default a menubar instance looks the same in all installed toplevel
windows\&. As changes are made to one instance of a menubar all the other
instances are immediately updated\&. This means the internal state of all
the menu entries for the instances are synchronized\&. This behavior is
called global scope control of the menubar state\&.
.PP
The menubar class allows finer scope control on check and radio buttons\&.
The scope of these entry types can be modified by adding a
modifier character to their type character\&. Two
modifier characters are supported as show in the table below\&.
.CS


''  ::= global scope (no character)
'@' ::= local scope modifier
'=' ::= notebook tab scope modifier

.CE
.PP
When the local scope character (@) is added to the definition of a button,
the button is given a new variable for each installed toplevel window\&. This
has the effect of making the button's state local to the window (i\&.e\&. local scope)\&.
An example use case for this behavior might be a status bar that can be
toggled on an off by a checkbutton\&. The developer may want to allow the
user to control the visibility of the status bar on a per window basis\&. In this
case a local modifier would be added to the status bar selector so the callback
code would receive an appropriate value based on the current toplevel window\&.
.PP
The notebook tab scope character (=) is similar in effect to the local scope
character but it allows a notebook tab selection to also manage the state of
of a button\&. Adding the notebook tab scope modifier enables notebook tab
scope control but the developer must then make use of the notebook\&.xxxx sub-commands
to actively manage state values as tabs are added, deleted and selected\&.
.SH EXAMPLE
.CS


package require Tcl
package require Tk
package require menubar

set tout [text \&.t -width 25 -height 12]
pack ${tout} -expand 1 -fill both
set mbar [menubar new \\
    -borderwidth 4 \\
    -relief groove  \\
    -foreground black \\
    -background tan \\
    ]
................................................................................
                }
        }
    }
    Help M:help {
        About               C       about
    }
}
${mbar} install \&. {
    ${mbar} tag\&.add tout ${tout}
    ${mbar} menu\&.configure -command {
        # file menu
        exit            {Exit}
        # Item menu
        cut             {CB Edit cut}
        copy            {CB Edit copy}
        paste           {CB Edit paste}
        # boolean menu
................................................................................
        exit red
    } -foreground {
        exit white
    }
}
proc pout { txt } {
    global mbar
    set tout [${mbar} tag\&.cget \&. tout]
    ${tout} insert end "${txt}\\n"
}
proc Exit { args } {
    puts "Goodbye"
    exit
}
proc CB { args } {
    set alist [lassign ${args} cmd]
    pout "${cmd}: [join ${alist} {, }]"
}
wm minsize \&. 300 300
wm geometry \&. +4+4
wm protocol \&. WM_DELETE_WINDOW exit
wm title \&. "Example"
wm focusmodel \&. active
pout "Example started \&.\&.\&."

.CE
.SH CAVEATS
.PP
This implementation uses TclOO so it requires 8\&.6\&. The code has been
tested on Windows (Vista), Linux and OSX (10\&.4)\&.
.SH "SEE ALSO"
\fIA command that creates menubar objects\fR [http://wiki\&.tcl\&.tk/25231], \fImenu\fR [http://www\&.tcl\&.tk/man/tcl8\&.6/TkCmd/menu\&.htm]
.SH COPYRIGHT
.nf
Copyright (c) 2009 Tom Krehbiel <krehbiel\&.tom@gmail\&.com> All rights reserved\&.

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ntext/ntext.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ntext" n 0.81 tklib "Alternative Bindings for the Text Widget"
.BS
.SH NAME
ntext \- Alternative Bindings for the Text Widget
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBntext  ?0.81?\fR
.sp
.BE
.SH DESCRIPTION
The purpose of the \fBntext\fR package is to make the text widget behave more like other text-editing applications. It makes the text widget more useful for implementing a text editor, and makes it behave in a way that will be more familiar to most users.
.PP
The package provides a binding tag named \fINtext\fR for use by text widgets in place of the default \fIText\fR binding tag.
.PP
Package \fBntext\fR 's functions and variables are contained entirely in the \fB::ntext\fR namespace; its other code is contained in the binding tag \fINtext\fR.  \fBntext\fR has no exports to the global or other namespaces, and no new widget commands.  It uses modified copies of the Tk code, leaving the original code, and the \fIText\fR binding tag, unchanged.
.PP
The differences between the \fINtext\fR binding tag and the default \fIText\fR binding tag are in three categories:
.IP \(bu
Some \fIText\fR bindings behave differently from most text-editing applications.  \fINtext\fR gives these bindings more familiar behaviour.  For details see \fIntextBindings\fR.
.IP \(bu
When a logical line with leading whitespace is word-wrapped onto more than one display line, the wrapped display lines begin further to the left than the first display line, which can make the text layout untidy and difficult to read.  \fINtext\fR can indent the wrapped lines to match the leading whitespace of the first display line (this facility is switched off by default).  For details see \fIntextIndent\fR.
.IP \(bu
When the user navigates or selects text, Tcl/Tk sometimes needs to detect word boundaries.  \fINtext\fR provides improved rules for word boundary detection.  For details see \fIntextWordBreak\fR.
.PP
The remainder of this page describes the basic use and configuration of all three aspects of \fINtext\fR.  For more detailed information on the different facilities of \fINtext\fR, see the pages \fIntextBindings\fR, \fIntextIndent\fR, and \fIntextWordBreak\fR.
.PP
See Section \fBEXAMPLE\fR for how to apply the \fINtext\fR binding tag in place of the \fIText\fR binding tag.
.SH "CONFIGURATION OPTIONS"
\fINtext\fR provides alternatives to a number of behaviours of the classic \fIText\fR binding tag.  Where there is an option, the \fINtext\fR behaviour (except for display-line indentation) is switched on by default.
.PP
The behaviour of \fINtext\fR may be configured application-wide by setting the values of a number of namespace variables:
.PP
\fB::ntext::classicAnchor\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i.e. the anchor point is fixed
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i.e. the anchor point is variable
.PP
.PP
\fB::ntext::classicExtras\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i.e. several traditional \fIText\fR bindings are de-activated
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i.e. all \fIText\fR bindings are activated
.PP
.PP
\fB::ntext::classicMouseSelect\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i.e. the anchor point for mouse selection operations is moved by keyboard navigation
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour
.PP
.PP
\fB::ntext::classicWordBreak\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i.e. platform-independent, two classes of word characters and one class of non-word characters.
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i.e. platform-dependent, one class of word characters and one class of non-word characters
.IP \(bu
After changing this value, the matching patterns should be recalculated.  See \fIntextWordBreak\fR for details and advanced configuration options.
.PP
.PP
\fB::ntext::classicWrap\fR
.IP \(bu
\fB0\fR - selects \fINtext\fR behaviour, i.e. display lines of text widgets in \fI-wrap\fR \fIword\fR mode are indented to match the initial whitespace of the first display line of a logical line.  If the widget already holds text when this value is set, a function call may be necessary.  See \fIntextIndent\fR for detailed instructions on the use of \fINtext\fR 's indentation.
.IP \(bu
\fB1\fR - (default value) selects classic \fIText\fR behaviour, i.e. no indentation
.PP
.PP
\fB::ntext::overwrite\fR
.IP \(bu
\fB0\fR - (initial value) text typed at the keyboard is inserted into the widget
.IP \(bu
\fB1\fR - text typed at the keyboard overwrites text already in the widget
.IP \(bu
The value is toggled by the \fIInsert\fR key.
.PP
.SH EXAMPLE
To create a text widget .t and use the \fINtext\fR bindings:
.CS


package require ntext
text .t
bindtags .t {.t Ntext . all}

.CE
See bindtags for more information.
.SH "SEE ALSO"
bindtags, ntextBindings, ntextIndent, ntextWordBreak, re_syntax, regexp, text
.SH KEYWORDS
bindtags, re_syntax, regexp, text

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ntext/ntext\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ntext" n 0\&.81 tklib "Alternative Bindings for the Text Widget"
.BS
.SH NAME
ntext \- Alternative Bindings for the Text Widget
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBntext  ?0\&.81?\fR
.sp
.BE
.SH DESCRIPTION
The purpose of the \fBntext\fR package is to make the text widget behave more like other text-editing applications\&. It makes the text widget more useful for implementing a text editor, and makes it behave in a way that will be more familiar to most users\&.
.PP
The package provides a binding tag named \fINtext\fR for use by text widgets in place of the default \fIText\fR binding tag\&.
.PP
Package \fBntext\fR 's functions and variables are contained entirely in the \fB::ntext\fR namespace; its other code is contained in the binding tag \fINtext\fR\&.  \fBntext\fR has no exports to the global or other namespaces, and no new widget commands\&.  It uses modified copies of the Tk code, leaving the original code, and the \fIText\fR binding tag, unchanged\&.
.PP
The differences between the \fINtext\fR binding tag and the default \fIText\fR binding tag are in three categories:
.IP \(bu
Some \fIText\fR bindings behave differently from most text-editing applications\&.  \fINtext\fR gives these bindings more familiar behaviour\&.  For details see \fIntextBindings\fR\&.
.IP \(bu
When a logical line with leading whitespace is word-wrapped onto more than one display line, the wrapped display lines begin further to the left than the first display line, which can make the text layout untidy and difficult to read\&.  \fINtext\fR can indent the wrapped lines to match the leading whitespace of the first display line (this facility is switched off by default)\&.  For details see \fIntextIndent\fR\&.
.IP \(bu
When the user navigates or selects text, Tcl/Tk sometimes needs to detect word boundaries\&.  \fINtext\fR provides improved rules for word boundary detection\&.  For details see \fIntextWordBreak\fR\&.
.PP
The remainder of this page describes the basic use and configuration of all three aspects of \fINtext\fR\&.  For more detailed information on the different facilities of \fINtext\fR, see the pages \fIntextBindings\fR, \fIntextIndent\fR, and \fIntextWordBreak\fR\&.
.PP
See Section \fBEXAMPLE\fR for how to apply the \fINtext\fR binding tag in place of the \fIText\fR binding tag\&.
.SH "CONFIGURATION OPTIONS"
\fINtext\fR provides alternatives to a number of behaviours of the classic \fIText\fR binding tag\&.  Where there is an option, the \fINtext\fR behaviour (except for display-line indentation) is switched on by default\&.
.PP
The behaviour of \fINtext\fR may be configured application-wide by setting the values of a number of namespace variables:
.PP
\fB::ntext::classicAnchor\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i\&.e\&. the anchor point is fixed
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i\&.e\&. the anchor point is variable
.PP
.PP
\fB::ntext::classicExtras\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i\&.e\&. several traditional \fIText\fR bindings are de-activated
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i\&.e\&. all \fIText\fR bindings are activated
.PP
.PP
\fB::ntext::classicMouseSelect\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i\&.e\&. the anchor point for mouse selection operations is moved by keyboard navigation
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour
.PP
.PP
\fB::ntext::classicWordBreak\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i\&.e\&. platform-independent, two classes of word characters and one class of non-word characters\&.
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i\&.e\&. platform-dependent, one class of word characters and one class of non-word characters
.IP \(bu
After changing this value, the matching patterns should be recalculated\&.  See \fIntextWordBreak\fR for details and advanced configuration options\&.
.PP
.PP
\fB::ntext::classicWrap\fR
.IP \(bu
\fB0\fR - selects \fINtext\fR behaviour, i\&.e\&. display lines of text widgets in \fI-wrap\fR \fIword\fR mode are indented to match the initial whitespace of the first display line of a logical line\&.  If the widget already holds text when this value is set, a function call may be necessary\&.  See \fIntextIndent\fR for detailed instructions on the use of \fINtext\fR 's indentation\&.
.IP \(bu
\fB1\fR - (default value) selects classic \fIText\fR behaviour, i\&.e\&. no indentation
.PP
.PP
\fB::ntext::overwrite\fR
.IP \(bu
\fB0\fR - (initial value) text typed at the keyboard is inserted into the widget
.IP \(bu
\fB1\fR - text typed at the keyboard overwrites text already in the widget
.IP \(bu
The value is toggled by the \fIInsert\fR key\&.
.PP
.SH EXAMPLE
To create a text widget \&.t and use the \fINtext\fR bindings:
.CS


package require ntext
text \&.t
bindtags \&.t {\&.t Ntext \&. all}

.CE
See bindtags for more information\&.
.SH "SEE ALSO"
bindtags, ntextBindings, ntextIndent, ntextWordBreak, re_syntax, regexp, text
.SH KEYWORDS
bindtags, re_syntax, regexp, text

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ntext/ntextBindings.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ntextBindings" n 0.81 tklib "Alternative Bindings for the Text Widget"
.BS
.SH NAME
ntextBindings \- Alternative Bindings for the Text Widget
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBntext  ?0.81?\fR
.sp
.BE
.SH DESCRIPTION
The \fBntext\fR package provides a binding tag named \fINtext\fR for use by text widgets in place of the default \fIText\fR binding tag.
.PP
The \fIText\fR binding tag provides around one hundred bindings to the text widget (the exact number is platform-dependent).  A few of these behave in a way that is different from most contemporary text-editing applications.  \fINtext\fR aims to provide more familiar behaviour.
.PP
Features of the \fINtext\fR bindings that differ from the default \fIText\fR bindings:
.IP \(bu
Clicking near the end of a (logical) line moves the cursor to the end of that line \fI(not the start of the next line)\fR.  If the widget is in \fI-wrap\fR \fIword\fR mode, the same rule applies to display lines.
.IP \(bu
Double-clicking or dragging near the end of a (logical) line will highlight/select characters from the end of that line \fI(not the next line, or the region at the end of the line where there are no characters)\fR.  If the widget is in \fI-wrap\fR \fIword\fR mode, the same rule applies to display lines.
.IP \(bu
The \fIEnd\fR key implements "Smart End" (successive keypresses move the cursor to the end of the display line, then to the end of the logical line); the \fIHome\fR key implements "Smart Home" (which is similar to "Smart End", but also toggles between the beginning and end of leading whitespace).
.IP \(bu
When a selection exists, a <<Paste>> operation (e.g. <Control-v>) overwrites the selection (as most editors do), and does so on all platforms.
.IP \(bu
The <Insert> key toggles between "Insert" and "Overwrite" modes for keyboard input.  \fI(In contrast, the Text binding tag uses <Insert> as a method to paste the "primary selection", a task that can be accomplished instead by mouse middle-click.)\fR
.IP \(bu
The <Escape> key clears the selection.
.IP \(bu
Selecting with <Shift-Button1> selects from the previous position of the insertion cursor. \fI(In the Text binding tag, the selection anchor may be the position of the previous mouse click.)\fR
.IP \(bu
<Shift-Button1> operations do not alter the selection anchor. \fI(In the Text binding tag, they do.)\fR
.IP \(bu
By default, the \fINtext\fR binding tag does not provide several of the Control-key bindings supplied by the \fIText\fR binding tag.  Modern keyboards offer alternatives, such as cursor keys for navigation; modern applications often use the Control-key bindings for other purposes (e.g. <Control-p> for "print").
.PP
The last three cases, the behavior of \fIText\fR is often useful, so \fINtext\fR gives you the option of retaining it, by setting variables defined in the ::ntext namespace to 1 (instead of their default 0).  Explaining these features in more detail:
.IP \(bu
If the mouse is clicked at position A, then the keyboard is used to move the cursor to B, then shift is held down, and the mouse is clicked at C: the \fIText\fR binding tag gives a selection from A to C; the \fINtext\fR gives a selection from B to C.  If you want \fINtext\fR to behave like \fIText\fR in this respect, set \fB::ntext::classicMouseSelect\fR to 1.
.IP \(bu
The \fIText\fR binding tag allows successive <Shift-Button-1> events to change both ends of the selection, by moving the selection anchor to the end of the selection furthest from the mouse click.  Instead, the \fINtext\fR binding tag fixes the anchor, and multiple Shift-Button-1 events can only move the non-anchored end of the selection.  If you want \fINtext\fR to behave like \fIText\fR in this respect, set \fB::ntext::classicAnchor\fR to 1.  In both \fIText\fR and \fINtext\fR, keyboard navigation with the Shift key held down alters the selection and keeps the selection anchor fixed.
.IP \(bu
The following "extra" \fIText\fR bindings are switched off by default, but can be activated in \fINtext\fR by setting \fB::ntext::classicExtras\fR to 1: <Control-a>, <Control-b>, <Control-d>, <Control-e>, <Control-f>, <Control-h>, <Control-i>, <Control-k>, <Control-n>, <Control-o>, <Control-p>, <Control-t>, <Control-space>, <Control-Shift-space>.
.PP
.SH "CONFIGURATION OPTIONS"
\fINtext\fR provides alternatives to a number of behaviours of the classic \fIText\fR binding tag.  Where there is an option, the \fINtext\fR behaviour is switched on by default, except for display-line indentation which is discussed on a separate page at \fIntextIndent\fR.
.PP
The behaviour of \fINtext\fR may be configured application-wide by setting the values of a number of namespace variables:
.PP
\fB::ntext::classicAnchor\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i.e. the anchor point is fixed
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i.e. the anchor point is variable
.PP
.PP
\fB::ntext::classicExtras\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i.e. several "extra" \fIText\fR bindings are de-activated
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i.e. the "extra" \fIText\fR bindings are activated
.PP
.PP
\fB::ntext::classicMouseSelect\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i.e. the anchor point for mouse selection operations is moved by keyboard navigation
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour
.PP
.PP
\fB::ntext::overwrite\fR
.IP \(bu
\fB0\fR - (initial value) text typed at the keyboard is inserted into the widget
.IP \(bu
\fB1\fR - text typed at the keyboard overwrites text already in the widget
.IP \(bu
The value is toggled by the \fIInsert\fR key.
.PP
.SH EXAMPLE
To use \fINtext\fR but keep classic \fIText\fR 's variable-anchor feature:
.CS


package require ntext
text .t
set ::ntext::classicAnchor 1
bindtags .t {.t Ntext . all}

.CE
.SH "SEE ALSO"
bindtags, ntext, ntextIndent, text
.SH KEYWORDS
bindtags, text

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ntext/ntextBindings\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ntextBindings" n 0\&.81 tklib "Alternative Bindings for the Text Widget"
.BS
.SH NAME
ntextBindings \- Alternative Bindings for the Text Widget
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBntext  ?0\&.81?\fR
.sp
.BE
.SH DESCRIPTION
The \fBntext\fR package provides a binding tag named \fINtext\fR for use by text widgets in place of the default \fIText\fR binding tag\&.
.PP
The \fIText\fR binding tag provides around one hundred bindings to the text widget (the exact number is platform-dependent)\&.  A few of these behave in a way that is different from most contemporary text-editing applications\&.  \fINtext\fR aims to provide more familiar behaviour\&.
.PP
Features of the \fINtext\fR bindings that differ from the default \fIText\fR bindings:
.IP \(bu
Clicking near the end of a (logical) line moves the cursor to the end of that line \fI(not the start of the next line)\fR\&.  If the widget is in \fI-wrap\fR \fIword\fR mode, the same rule applies to display lines\&.
.IP \(bu
Double-clicking or dragging near the end of a (logical) line will highlight/select characters from the end of that line \fI(not the next line, or the region at the end of the line where there are no characters)\fR\&.  If the widget is in \fI-wrap\fR \fIword\fR mode, the same rule applies to display lines\&.
.IP \(bu
The \fIEnd\fR key implements "Smart End" (successive keypresses move the cursor to the end of the display line, then to the end of the logical line); the \fIHome\fR key implements "Smart Home" (which is similar to "Smart End", but also toggles between the beginning and end of leading whitespace)\&.
.IP \(bu
When a selection exists, a <<Paste>> operation (e\&.g\&. <Control-v>) overwrites the selection (as most editors do), and does so on all platforms\&.
.IP \(bu
The <Insert> key toggles between "Insert" and "Overwrite" modes for keyboard input\&.  \fI(In contrast, the Text binding tag uses <Insert> as a method to paste the "primary selection", a task that can be accomplished instead by mouse middle-click\&.)\fR
.IP \(bu
The <Escape> key clears the selection\&.
.IP \(bu
Selecting with <Shift-Button1> selects from the previous position of the insertion cursor\&. \fI(In the Text binding tag, the selection anchor may be the position of the previous mouse click\&.)\fR
.IP \(bu
<Shift-Button1> operations do not alter the selection anchor\&. \fI(In the Text binding tag, they do\&.)\fR
.IP \(bu
By default, the \fINtext\fR binding tag does not provide several of the Control-key bindings supplied by the \fIText\fR binding tag\&.  Modern keyboards offer alternatives, such as cursor keys for navigation; modern applications often use the Control-key bindings for other purposes (e\&.g\&. <Control-p> for "print")\&.
.PP
The last three cases, the behavior of \fIText\fR is often useful, so \fINtext\fR gives you the option of retaining it, by setting variables defined in the ::ntext namespace to 1 (instead of their default 0)\&.  Explaining these features in more detail:
.IP \(bu
If the mouse is clicked at position A, then the keyboard is used to move the cursor to B, then shift is held down, and the mouse is clicked at C: the \fIText\fR binding tag gives a selection from A to C; the \fINtext\fR gives a selection from B to C\&.  If you want \fINtext\fR to behave like \fIText\fR in this respect, set \fB::ntext::classicMouseSelect\fR to 1\&.
.IP \(bu
The \fIText\fR binding tag allows successive <Shift-Button-1> events to change both ends of the selection, by moving the selection anchor to the end of the selection furthest from the mouse click\&.  Instead, the \fINtext\fR binding tag fixes the anchor, and multiple Shift-Button-1 events can only move the non-anchored end of the selection\&.  If you want \fINtext\fR to behave like \fIText\fR in this respect, set \fB::ntext::classicAnchor\fR to 1\&.  In both \fIText\fR and \fINtext\fR, keyboard navigation with the Shift key held down alters the selection and keeps the selection anchor fixed\&.
.IP \(bu
The following "extra" \fIText\fR bindings are switched off by default, but can be activated in \fINtext\fR by setting \fB::ntext::classicExtras\fR to 1: <Control-a>, <Control-b>, <Control-d>, <Control-e>, <Control-f>, <Control-h>, <Control-i>, <Control-k>, <Control-n>, <Control-o>, <Control-p>, <Control-t>, <Control-space>, <Control-Shift-space>\&.
.PP
.SH "CONFIGURATION OPTIONS"
\fINtext\fR provides alternatives to a number of behaviours of the classic \fIText\fR binding tag\&.  Where there is an option, the \fINtext\fR behaviour is switched on by default, except for display-line indentation which is discussed on a separate page at \fIntextIndent\fR\&.
.PP
The behaviour of \fINtext\fR may be configured application-wide by setting the values of a number of namespace variables:
.PP
\fB::ntext::classicAnchor\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i\&.e\&. the anchor point is fixed
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i\&.e\&. the anchor point is variable
.PP
.PP
\fB::ntext::classicExtras\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i\&.e\&. several "extra" \fIText\fR bindings are de-activated
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i\&.e\&. the "extra" \fIText\fR bindings are activated
.PP
.PP
\fB::ntext::classicMouseSelect\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i\&.e\&. the anchor point for mouse selection operations is moved by keyboard navigation
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour
.PP
.PP
\fB::ntext::overwrite\fR
.IP \(bu
\fB0\fR - (initial value) text typed at the keyboard is inserted into the widget
.IP \(bu
\fB1\fR - text typed at the keyboard overwrites text already in the widget
.IP \(bu
The value is toggled by the \fIInsert\fR key\&.
.PP
.SH EXAMPLE
To use \fINtext\fR but keep classic \fIText\fR 's variable-anchor feature:
.CS


package require ntext
text \&.t
set ::ntext::classicAnchor 1
bindtags \&.t {\&.t Ntext \&. all}

.CE
.SH "SEE ALSO"
bindtags, ntext, ntextIndent, text
.SH KEYWORDS
bindtags, text

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ntext/ntextIndent.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ntextIndent" n 0.81 tklib "ntext Indentation for the Text Widget"
.BS
.SH NAME
ntextIndent \- ntext Indentation for the Text Widget
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBntext  ?0.81?\fR
.sp
.BE
.SH DESCRIPTION
The \fBntext\fR package provides a binding tag named \fINtext\fR for use by text widgets in place of the default \fIText\fR binding tag.
.PP
Tk's text widget may be configured to wrap lines of text that are longer than the width of the text area, a feature that is familiar from text editors and word processors.  A complete line of text (delimited by newlines, or by the beginning or end of the document) is called a "logical line".  When a logical line is wrapped onto more than one line of the display area, these fragments of the logical line are called "display lines".
.PP
If a logical line begins with whitespace, then wrapped display lines begin further to the left than the first display line, which can make the text layout untidy and difficult to read.  The \fINtext\fR binding tag provides facilities so that a text widget in \fI-wrap\fR \fIword\fR mode will automatically indent display lines (other than the first) to match the initial whitespace of the first display line.
.PP
This indentation is available to text widgets only in \fI-wrap\fR \fIword\fR mode.
.SH "CONFIGURATION OPTIONS"
The behavior of \fINtext\fR may be configured application-wide by setting the values of a number of namespace variables:
.PP
\fB::ntext::classicWrap\fR
.IP \(bu
0 - selects \fINtext\fR behaviour, i.e. display lines are indented to match the initial whitespace of the first display line of a logical line.
.sp
No other action is required if this option, and the text widget's \fI-wrap\fR option, are set before any text is entered in the widget, and if text is entered and edited only by the mouse and keyboard.  If, instead, text is manipulated by the script, or if the text widget's \fI-wrap\fR option or the value of \fB::ntext::classicWrap\fR are changed while the widget holds text, then calls to \fIntext\fR functions are needed to alter the indentation.  See the section \fBINDENTING DISPLAY LINES\fR for detailed instructions.
.IP \(bu
1 - (default value) selects classic \fIText\fR behaviour, i.e. no indentation.
.PP
\fIAdvanced Use\fR
.PP
\fB::ntext::newWrapRegexp\fR
.IP \(bu
the value is a regexp pattern that determines the character of a logical line to which display lines other than the first will be aligned.  The default value, \fB[^[:space:]]\fR, ensures alignment with the first non-whitespace character.
.PP
.SH "INDENTING DISPLAY LINES"
To use \fINtext\fR 's display line indentation:
.IP [1]
Set the variable \fB::ntext::classicWrap\fR to \fB0\fR (default value is \fB1\fR).  This enables bindings that will preserve indentation whenever the user modifies the widget contents using the keyboard and mouse.  If the widget already holds text, call \fB::ntext::wrapIndent\fR to initialise indentation.
.sp
Further instructions apply if the program changes the widget's contents, wrap configuration, or indent configuration.
.IP [2]
The program can change the text contents, e.g. by the .text insert command.  Such a change does not trigger a window binding, so the program should explicitly call function \fB::ntext::wrapIndent\fR after inserting text.
.IP [3]
Auto-indentation occurs only if the widget is in \fI-wrap\fR \fIword\fR mode.  If the program changes to or from \fI-wrap\fR \fIword\fR when the widget is not empty, it should call \fB::ntext::wrapIndent\fR to format the widget's text.
.IP [4]
If indentation is used, and then switched off by setting \fB::ntext::classicWrap\fR to \fB1\fR,  call \fB::ntext::wrapIndent\fR to remove indentation.
.PP
.SH FUNCTIONS
\fB::ntext::wrapIndent\fR \fItextWidget\fR ?index1? ?index2?
.IP \(bu
Adjust the indentation of a text widget.  Different cases are discussed below.
.PP
\fB::ntext::wrapIndent\fR \fItextWidget\fR
.IP \(bu
Adjust the indentation of all the text in text widget \fItextWidget\fR.
.PP
\fB::ntext::wrapIndent\fR \fItextWidget\fR \fIindex1\fR
.IP \(bu
Adjust the indentation of a single logical line of a text widget - the line of \fItextWidget\fR that contains the index \fIindex1\fR.
.PP
\fB::ntext::wrapIndent\fR \fItextWidget\fR \fIindex1\fR \fIindex2\fR
.IP \(bu
Adjust the indentation of a range of logical lines of a text widget - the lines of \fItextWidget\fR that contain indices \fIindex1\fR to \fIindex2\fR.
.PP
\fIUsage\fR
.IP \(bu
\fB::ntext::wrapIndent\fR should be called only if the script changes the widget's contents or display properties.  If the contents of the widget have been modified by the keyboard or mouse, it is not necessary for the script to call \fB::ntext::wrapIndent\fR because the appropriate calls are made automatically by the \fINtext\fR bindings.
.IP \(bu
The script should normally call \fB::ntext::wrapIndent\fR if, for example, the script changes one of the following when the widget is not empty: the value of \fB::ntext::classicWrap\fR, or the widget's \fI-wrap\fR status, or the widget's tab spacing, or the font size, or the widget's contents.
.IP \(bu
A call of the form \fB::ntext::wrapIndent\fR \fItextWidget\fR will always suffice, but if changes are needed only to certain lines, it is more efficient to specify those lines with the optional arguments ?index1?, ?index2?.
.IP \(bu
If the widget is in \fI-word\fR \fIwrap\fR mode, and if \fB::ntext::classicWrap\fR is set to \fB0\fR, \fB::ntext::wrapIndent\fR will apply indentation to the logical lines within the range specified by the function's arguments.
.IP \(bu
In other cases, i.e. if the widget is in \fI-word\fR \fIchar\fR or \fI-word\fR \fInone\fR mode, or if \fB::ntext::classicWrap\fR is set to \fB1\fR,  \fB::ntext::wrapIndent\fR will remove the indentation of the logical lines within the range specified by the function's arguments.
.PP
.SH EXAMPLES
To switch on \fINtext\fR 's indentation and use it in widget .t:
.CS


package require ntext
set ::ntext::classicWrap 0
text .t -wrap word
bindtags .t {.t Ntext . all}

.CE
To decide later to switch off \fINtext\fR 's indentation:
.CS


set ::ntext::classicWrap 1
::ntext::wrapIndent .t

.CE
To decide later to switch \fINtext\fR 's indentation back on:
.CS


set ::ntext::classicWrap 0
::ntext::wrapIndent .t 1.0 end

.CE
To inject some text into the widget:
.CS


set foo [.t index end]
.t insert end {This line was added by the script, not the keyboard!}
::ntext::wrapIndent .t $foo end

.CE
To switch to \fI-wrap\fR \fIchar\fR mode:
.CS


.t configure -wrap char
::ntext::wrapIndent .t

.CE
.SH "SEE ALSO"
bindtags, ntext, re_syntax, regexp, text
.SH KEYWORDS
bindtags, re_syntax, regexp, text

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ntext/ntextIndent\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ntextIndent" n 0\&.81 tklib "ntext Indentation for the Text Widget"
.BS
.SH NAME
ntextIndent \- ntext Indentation for the Text Widget
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBntext  ?0\&.81?\fR
.sp
.BE
.SH DESCRIPTION
The \fBntext\fR package provides a binding tag named \fINtext\fR for use by text widgets in place of the default \fIText\fR binding tag\&.
.PP
Tk's text widget may be configured to wrap lines of text that are longer than the width of the text area, a feature that is familiar from text editors and word processors\&.  A complete line of text (delimited by newlines, or by the beginning or end of the document) is called a "logical line"\&.  When a logical line is wrapped onto more than one line of the display area, these fragments of the logical line are called "display lines"\&.
.PP
If a logical line begins with whitespace, then wrapped display lines begin further to the left than the first display line, which can make the text layout untidy and difficult to read\&.  The \fINtext\fR binding tag provides facilities so that a text widget in \fI-wrap\fR \fIword\fR mode will automatically indent display lines (other than the first) to match the initial whitespace of the first display line\&.
.PP
This indentation is available to text widgets only in \fI-wrap\fR \fIword\fR mode\&.
.SH "CONFIGURATION OPTIONS"
The behavior of \fINtext\fR may be configured application-wide by setting the values of a number of namespace variables:
.PP
\fB::ntext::classicWrap\fR
.IP \(bu
0 - selects \fINtext\fR behaviour, i\&.e\&. display lines are indented to match the initial whitespace of the first display line of a logical line\&.
.sp
No other action is required if this option, and the text widget's \fI-wrap\fR option, are set before any text is entered in the widget, and if text is entered and edited only by the mouse and keyboard\&.  If, instead, text is manipulated by the script, or if the text widget's \fI-wrap\fR option or the value of \fB::ntext::classicWrap\fR are changed while the widget holds text, then calls to \fIntext\fR functions are needed to alter the indentation\&.  See the section \fBINDENTING DISPLAY LINES\fR for detailed instructions\&.
.IP \(bu
1 - (default value) selects classic \fIText\fR behaviour, i\&.e\&. no indentation\&.
.PP
\fIAdvanced Use\fR
.PP
\fB::ntext::newWrapRegexp\fR
.IP \(bu
the value is a regexp pattern that determines the character of a logical line to which display lines other than the first will be aligned\&.  The default value, \fB[^[:space:]]\fR, ensures alignment with the first non-whitespace character\&.
.PP
.SH "INDENTING DISPLAY LINES"
To use \fINtext\fR 's display line indentation:
.IP [1]
Set the variable \fB::ntext::classicWrap\fR to \fB0\fR (default value is \fB1\fR)\&.  This enables bindings that will preserve indentation whenever the user modifies the widget contents using the keyboard and mouse\&.  If the widget already holds text, call \fB::ntext::wrapIndent\fR to initialise indentation\&.
.sp
Further instructions apply if the program changes the widget's contents, wrap configuration, or indent configuration\&.
.IP [2]
The program can change the text contents, e\&.g\&. by the \&.text insert command\&.  Such a change does not trigger a window binding, so the program should explicitly call function \fB::ntext::wrapIndent\fR after inserting text\&.
.IP [3]
Auto-indentation occurs only if the widget is in \fI-wrap\fR \fIword\fR mode\&.  If the program changes to or from \fI-wrap\fR \fIword\fR when the widget is not empty, it should call \fB::ntext::wrapIndent\fR to format the widget's text\&.
.IP [4]
If indentation is used, and then switched off by setting \fB::ntext::classicWrap\fR to \fB1\fR,  call \fB::ntext::wrapIndent\fR to remove indentation\&.
.PP
.SH FUNCTIONS
\fB::ntext::wrapIndent\fR \fItextWidget\fR ?index1? ?index2?
.IP \(bu
Adjust the indentation of a text widget\&.  Different cases are discussed below\&.
.PP
\fB::ntext::wrapIndent\fR \fItextWidget\fR
.IP \(bu
Adjust the indentation of all the text in text widget \fItextWidget\fR\&.
.PP
\fB::ntext::wrapIndent\fR \fItextWidget\fR \fIindex1\fR
.IP \(bu
Adjust the indentation of a single logical line of a text widget - the line of \fItextWidget\fR that contains the index \fIindex1\fR\&.
.PP
\fB::ntext::wrapIndent\fR \fItextWidget\fR \fIindex1\fR \fIindex2\fR
.IP \(bu
Adjust the indentation of a range of logical lines of a text widget - the lines of \fItextWidget\fR that contain indices \fIindex1\fR to \fIindex2\fR\&.
.PP
\fIUsage\fR
.IP \(bu
\fB::ntext::wrapIndent\fR should be called only if the script changes the widget's contents or display properties\&.  If the contents of the widget have been modified by the keyboard or mouse, it is not necessary for the script to call \fB::ntext::wrapIndent\fR because the appropriate calls are made automatically by the \fINtext\fR bindings\&.
.IP \(bu
The script should normally call \fB::ntext::wrapIndent\fR if, for example, the script changes one of the following when the widget is not empty: the value of \fB::ntext::classicWrap\fR, or the widget's \fI-wrap\fR status, or the widget's tab spacing, or the font size, or the widget's contents\&.
.IP \(bu
A call of the form \fB::ntext::wrapIndent\fR \fItextWidget\fR will always suffice, but if changes are needed only to certain lines, it is more efficient to specify those lines with the optional arguments ?index1?, ?index2?\&.
.IP \(bu
If the widget is in \fI-word\fR \fIwrap\fR mode, and if \fB::ntext::classicWrap\fR is set to \fB0\fR, \fB::ntext::wrapIndent\fR will apply indentation to the logical lines within the range specified by the function's arguments\&.
.IP \(bu
In other cases, i\&.e\&. if the widget is in \fI-word\fR \fIchar\fR or \fI-word\fR \fInone\fR mode, or if \fB::ntext::classicWrap\fR is set to \fB1\fR,  \fB::ntext::wrapIndent\fR will remove the indentation of the logical lines within the range specified by the function's arguments\&.
.PP
.SH EXAMPLES
To switch on \fINtext\fR 's indentation and use it in widget \&.t:
.CS


package require ntext
set ::ntext::classicWrap 0
text \&.t -wrap word
bindtags \&.t {\&.t Ntext \&. all}

.CE
To decide later to switch off \fINtext\fR 's indentation:
.CS


set ::ntext::classicWrap 1
::ntext::wrapIndent \&.t

.CE
To decide later to switch \fINtext\fR 's indentation back on:
.CS


set ::ntext::classicWrap 0
::ntext::wrapIndent \&.t 1\&.0 end

.CE
To inject some text into the widget:
.CS


set foo [\&.t index end]
\&.t insert end {This line was added by the script, not the keyboard!}
::ntext::wrapIndent \&.t $foo end

.CE
To switch to \fI-wrap\fR \fIchar\fR mode:
.CS


\&.t configure -wrap char
::ntext::wrapIndent \&.t

.CE
.SH "SEE ALSO"
bindtags, ntext, re_syntax, regexp, text
.SH KEYWORDS
bindtags, re_syntax, regexp, text

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ntext/ntextWordBreak.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ntextWordBreak" n 0.81 tklib "ntext Word Boundary Detection for the Text Widget"
.BS
.SH NAME
ntextWordBreak \- ntext Word Boundary Detection for the Text Widget
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBntext  ?0.81?\fR
.sp
.BE
.SH DESCRIPTION
The \fBntext\fR package provides a binding tag named \fINtext\fR for use by text widgets in place of the default \fIText\fR binding tag.
.PP
Navigation and selection in a text widget require the detection of words and their boundaries.  The word boundary detection facilities provided by Tcl/Tk through the \fIText\fR binding tag are limited because they define only one class of "word" characters and one class of "non-word" characters.  The \fINtext\fR binding tag uses more general rules for word boundary detection, that define \fItwo\fR classes of "word" characters and one class of "non-word" characters.
.PP
.SH "CONFIGURATION OPTIONS"
The behaviour of \fINtext\fR may be configured application-wide by setting the values of a number of namespace variables.  One of these is relevant to word boundary detection:
.PP
\fB::ntext::classicWordBreak\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i.e. platform-independent, two classes of word characters and one class of non-word characters.
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i.e. platform-dependent, one class of word characters and one class of non-word characters
.IP \(bu
After changing this value, \fINtext\fR 's regexp matching patterns should be recalculated.  See \fBFUNCTIONS\fR for details and advanced configuration options.
.PP
.PP
.SH "ADVANCED USE"
.SH "VARIABLES (ADVANCED USE)"
\fB::ntext::tcl_match_wordBreakAfter\fR
.PP
\fB::ntext::tcl_match_wordBreakBefore\fR
................................................................................
.PP
\fB::ntext::tcl_match_endOfWord\fR
.PP
\fB::ntext::tcl_match_startOfNextWord\fR
.PP
\fB::ntext::tcl_match_startOfPreviousWord\fR
.PP
These variables hold the regexp patterns that are used by \fINtext\fR to search for word boundaries.  If they are changed, subsequent searches are immediately altered.  In many situations, it it unnecessary to alter the values of these variables directly: instead call one of the functions \fB::ntext::initializeMatchPatterns\fR, \fB::ntext::createMatchPatterns\fR.
.PP
In the \fIText\fR binding tag one can change the search rules by changing the values of the global variables \fBtcl_wordchars\fR and \fBtcl_nonwordchars\fR.  The equivalent operation in the \fINtext\fR binding tag is to call \fB::ntext::createMatchPatterns\fR with appropriate arguments.
.SH "FUNCTIONS (ADVANCED USE)"
If a simple regexp search should prove insufficient, the following functions (analogous to the Tcl/Tk core's \fBtcl_wordBreakAfter\fR etc) may be replaced by the developer:
.PP
\fBntext::new_wordBreakAfter\fR
.PP
\fBntext::new_wordBreakBefore\fR
.PP
................................................................................
\fBntext::new_endOfWord\fR
.PP
\fBntext::new_startOfNextWord\fR
.PP
\fBntext::new_startOfPreviousWord\fR
.PP
.SH FUNCTIONS
Each function calculates the five regexp search patterns that define the word boundary searches.  These values are stored in the namespace variables listed above.
.PP
\fB::ntext::initializeMatchPatterns\fR
.IP \(bu
This function is called when \fINtext\fR is first used, and needs to be called again only if the script changes the value of either \fB::ntext::classicWordBreak\fR or \fB::tcl_platform(platform)\fR.  The function is called with no arguments.  It is useful when the desired search patterns are the default patterns for either the \fINtext\fR or \fIText\fR binding tag, and so are implicitly specified by the values of \fB::ntext::classicWordBreak\fR and \fB::tcl_platform(platform)\fR alone.
.PP
\fB::ntext::createMatchPatterns\fR \fInew_nonwordchars\fR \fInew_word1chars\fR ?new_word2chars?
.IP \(bu
This function is useful in a wider range of situations than \fB::ntext::initializeMatchPatterns\fR.  It calculates the regexp search patterns for any case with one class of "non-word" characters and one or two classes of "word" characters.
.sp
Each argument should be a regexp expression defining a class of characters.  An argument will usually be a bracket expression, but might alternatively be a class-shorthand escape, or a single character.  The third argument may be omitted, or supplied as the empty string, in which case it is unused.
.sp
The first argument is interpreted as the class of non-word characters; the second argument (and the third, if present) are classes of word characters.  The classes should include all possible characters and will normally be mutually exclusive: it is often convenient to define one class as the negation of the other two.
.PP
.SH "WORD BOUNDARY MATCHING"
The problem of word boundary selection is a vexed one, because text is used to represent a universe of different types of information, and there are no simple rules that are useful for all data types or for all purposes.
.PP
\fINtext\fR attempts to improve on the facilities available in classic \fIText\fR by providing facilities for more complex definitions of words (with three classes of characters instead of two).
.PP
\fIWhat is a word?  Why two classes of word?\fR
.PP
When using the modified cursor keys <Control-Left> and <Control-Right> to navigate through a \fINtext\fR widget, the cursor is placed at the start of a word.  A word is defined as a sequence of one or more characters from only one of the two defined "word" classes; it may be preceded by a character from the other "word" class or from the "non-word" class.
.PP
The double-click of mouse button 1 selects a word of text, where in this case a "word" may be as defined above, or alternatively may be a sequence of one or more characters from the "non-word" class of characters.
.PP
Traditionally Tcl has defined only one word class and one non-word class: on Windows, the non-word class is whitespace, and so alphanumerics and punctuation belong to the same class.  On other platforms, punctuation is bundled with whitespace as "non-word" characters.  In either case, the navigation and selection of text are unnecessarily coarse-grained, and sometimes give unhelpful results.
.PP
The use of three classes of characters might make selection too fine-grained; but in this case, holding down the \fIShift\fR key and double-clicking another word is an excellent way to select a longer range of text (a useful binding that Tcl/Tk has long provided but which is missing in other systems).
.PP
As well as its defaults, \fINtext\fR permits the developer to define their own classes of characters, or to revert to the classic \fIText\fR definitions, or to specify their own regexp matching patterns.
.SH EXAMPLE
To use \fINtext\fR with Tcl/Tk's usual word-boundary detection rules:
.CS


package require ntext
text .t
bindtags .t {.t Ntext . all}
set ::ntext::classicWordBreak 1
::ntext::initializeMatchPatterns

.CE
See bindtags for more information.
.PP
To define a different set of word-boundary detection rules:
.CS


package require ntext
text .t
bindtags .t {.t Ntext . all}
::ntext::createMatchPatterns \\
  {[[:space:][:cntrl:]]} {[[:punct:]]} {[^[:punct:][:space:][:cntrl:]]}

.CE
See regexp, re_syntax for more information.
.SH "SEE ALSO"
bindtags, ntext, re_syntax, regexp, text
.SH KEYWORDS
bindtags, re_syntax, regexp, text

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/ntext/ntextWordBreak\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "ntextWordBreak" n 0\&.81 tklib "ntext Word Boundary Detection for the Text Widget"
.BS
.SH NAME
ntextWordBreak \- ntext Word Boundary Detection for the Text Widget
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBntext  ?0\&.81?\fR
.sp
.BE
.SH DESCRIPTION
The \fBntext\fR package provides a binding tag named \fINtext\fR for use by text widgets in place of the default \fIText\fR binding tag\&.
.PP
Navigation and selection in a text widget require the detection of words and their boundaries\&.  The word boundary detection facilities provided by Tcl/Tk through the \fIText\fR binding tag are limited because they define only one class of "word" characters and one class of "non-word" characters\&.  The \fINtext\fR binding tag uses more general rules for word boundary detection, that define \fItwo\fR classes of "word" characters and one class of "non-word" characters\&.
.PP
.SH "CONFIGURATION OPTIONS"
The behaviour of \fINtext\fR may be configured application-wide by setting the values of a number of namespace variables\&.  One of these is relevant to word boundary detection:
.PP
\fB::ntext::classicWordBreak\fR
.IP \(bu
\fB0\fR - (default value) selects \fINtext\fR behaviour, i\&.e\&. platform-independent, two classes of word characters and one class of non-word characters\&.
.IP \(bu
\fB1\fR - selects classic \fIText\fR behaviour, i\&.e\&. platform-dependent, one class of word characters and one class of non-word characters
.IP \(bu
After changing this value, \fINtext\fR 's regexp matching patterns should be recalculated\&.  See \fBFUNCTIONS\fR for details and advanced configuration options\&.
.PP
.PP
.SH "ADVANCED USE"
.SH "VARIABLES (ADVANCED USE)"
\fB::ntext::tcl_match_wordBreakAfter\fR
.PP
\fB::ntext::tcl_match_wordBreakBefore\fR
................................................................................
.PP
\fB::ntext::tcl_match_endOfWord\fR
.PP
\fB::ntext::tcl_match_startOfNextWord\fR
.PP
\fB::ntext::tcl_match_startOfPreviousWord\fR
.PP
These variables hold the regexp patterns that are used by \fINtext\fR to search for word boundaries\&.  If they are changed, subsequent searches are immediately altered\&.  In many situations, it it unnecessary to alter the values of these variables directly: instead call one of the functions \fB::ntext::initializeMatchPatterns\fR, \fB::ntext::createMatchPatterns\fR\&.
.PP
In the \fIText\fR binding tag one can change the search rules by changing the values of the global variables \fBtcl_wordchars\fR and \fBtcl_nonwordchars\fR\&.  The equivalent operation in the \fINtext\fR binding tag is to call \fB::ntext::createMatchPatterns\fR with appropriate arguments\&.
.SH "FUNCTIONS (ADVANCED USE)"
If a simple regexp search should prove insufficient, the following functions (analogous to the Tcl/Tk core's \fBtcl_wordBreakAfter\fR etc) may be replaced by the developer:
.PP
\fBntext::new_wordBreakAfter\fR
.PP
\fBntext::new_wordBreakBefore\fR
.PP
................................................................................
\fBntext::new_endOfWord\fR
.PP
\fBntext::new_startOfNextWord\fR
.PP
\fBntext::new_startOfPreviousWord\fR
.PP
.SH FUNCTIONS
Each function calculates the five regexp search patterns that define the word boundary searches\&.  These values are stored in the namespace variables listed above\&.
.PP
\fB::ntext::initializeMatchPatterns\fR
.IP \(bu
This function is called when \fINtext\fR is first used, and needs to be called again only if the script changes the value of either \fB::ntext::classicWordBreak\fR or \fB::tcl_platform(platform)\fR\&.  The function is called with no arguments\&.  It is useful when the desired search patterns are the default patterns for either the \fINtext\fR or \fIText\fR binding tag, and so are implicitly specified by the values of \fB::ntext::classicWordBreak\fR and \fB::tcl_platform(platform)\fR alone\&.
.PP
\fB::ntext::createMatchPatterns\fR \fInew_nonwordchars\fR \fInew_word1chars\fR ?new_word2chars?
.IP \(bu
This function is useful in a wider range of situations than \fB::ntext::initializeMatchPatterns\fR\&.  It calculates the regexp search patterns for any case with one class of "non-word" characters and one or two classes of "word" characters\&.
.sp
Each argument should be a regexp expression defining a class of characters\&.  An argument will usually be a bracket expression, but might alternatively be a class-shorthand escape, or a single character\&.  The third argument may be omitted, or supplied as the empty string, in which case it is unused\&.
.sp
The first argument is interpreted as the class of non-word characters; the second argument (and the third, if present) are classes of word characters\&.  The classes should include all possible characters and will normally be mutually exclusive: it is often convenient to define one class as the negation of the other two\&.
.PP
.SH "WORD BOUNDARY MATCHING"
The problem of word boundary selection is a vexed one, because text is used to represent a universe of different types of information, and there are no simple rules that are useful for all data types or for all purposes\&.
.PP
\fINtext\fR attempts to improve on the facilities available in classic \fIText\fR by providing facilities for more complex definitions of words (with three classes of characters instead of two)\&.
.PP
\fIWhat is a word?  Why two classes of word?\fR
.PP
When using the modified cursor keys <Control-Left> and <Control-Right> to navigate through a \fINtext\fR widget, the cursor is placed at the start of a word\&.  A word is defined as a sequence of one or more characters from only one of the two defined "word" classes; it may be preceded by a character from the other "word" class or from the "non-word" class\&.
.PP
The double-click of mouse button 1 selects a word of text, where in this case a "word" may be as defined above, or alternatively may be a sequence of one or more characters from the "non-word" class of characters\&.
.PP
Traditionally Tcl has defined only one word class and one non-word class: on Windows, the non-word class is whitespace, and so alphanumerics and punctuation belong to the same class\&.  On other platforms, punctuation is bundled with whitespace as "non-word" characters\&.  In either case, the navigation and selection of text are unnecessarily coarse-grained, and sometimes give unhelpful results\&.
.PP
The use of three classes of characters might make selection too fine-grained; but in this case, holding down the \fIShift\fR key and double-clicking another word is an excellent way to select a longer range of text (a useful binding that Tcl/Tk has long provided but which is missing in other systems)\&.
.PP
As well as its defaults, \fINtext\fR permits the developer to define their own classes of characters, or to revert to the classic \fIText\fR definitions, or to specify their own regexp matching patterns\&.
.SH EXAMPLE
To use \fINtext\fR with Tcl/Tk's usual word-boundary detection rules:
.CS


package require ntext
text \&.t
bindtags \&.t {\&.t Ntext \&. all}
set ::ntext::classicWordBreak 1
::ntext::initializeMatchPatterns

.CE
See bindtags for more information\&.
.PP
To define a different set of word-boundary detection rules:
.CS


package require ntext
text \&.t
bindtags \&.t {\&.t Ntext \&. all}
::ntext::createMatchPatterns \\
  {[[:space:][:cntrl:]]} {[[:punct:]]} {[^[:punct:][:space:][:cntrl:]]}

.CE
See regexp, re_syntax for more information\&.
.SH "SEE ALSO"
bindtags, ntext, re_syntax, regexp, text
.SH KEYWORDS
bindtags, re_syntax, regexp, text

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/plotchart/plotchart.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2011 Arjen Markus <arjenmarkus@users.sourceforge.net>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "Plotchart" n 2.0.2 tklib "Plotchart"
.BS
.SH NAME
Plotchart \- Simple plotting and charting package
.SH SYNOPSIS
package require \fBTcl  ?8.5?\fR
.sp
package require \fBTk  ?8.5?\fR
.sp
package require \fBPlotchart  ?2.1.0?\fR
.sp
\fB::Plotchart::createXYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIargs\fR
.sp
\fB::Plotchart::createStripchart\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
.sp
\fB::Plotchart::createTXPlot\fR \fIw\fR \fItimeaxis\fR \fIxaxis\fR
.sp
................................................................................
.sp
\fB$anyplot\fR xsubtext \fItext\fR
.sp
\fB$anyplot\fR ysubtext \fItext\fR
.sp
\fB$anyplot\fR vsubtext \fItext\fR
.sp
\fB$anyplot\fR xconfig \fB-option\fR \fIvalue\fR ...
.sp
\fB$anyplot\fR yconfig \fB-option\fR \fIvalue\fR ...
.sp
\fB$anyplot\fR background \fIpart\fR \fIcolour_or_image\fR \fIdir\fR ?brightness?
.sp
\fB$anyplot\fR xticklines \fIcolour\fR ?dash?
.sp
\fB$anyplot\fR yticklines \fIcolour\fR ?dash?
.sp
\fB$anyplot\fR legend \fIseries\fR \fItext\fR ?spacing?
.sp
\fB$anyplot\fR removefromlegend \fIseries\fR
.sp
\fB$anyplot\fR legendconfig \fB-option\fR \fIvalue\fR ...
.sp
\fB$anyplot\fR balloon \fIx\fR \fIy\fR \fItext\fR \fIdir\fR
.sp
\fB$anyplot\fR balloonconfig \fIargs\fR
.sp
\fB$anyplot\fR plaintext \fIx\fR \fIy\fR \fItext\fR \fIdir\fR
.sp
................................................................................
.sp
\fB$xyplot\fR interval \fIseries\fR \fIxcrd\fR \fIymin\fR \fIymax\fR ?ycentr?
.sp
\fB$xyplot\fR box-and-whiskers \fIseries\fR \fIxcrd\fR \fIycrd\fR
.sp
\fB$xyplot\fR vector \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIucmp\fR \fIvcmp\fR
.sp
\fB$xyplot\fR vectorconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
.sp
\fB$xyplot\fR dot \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIvalue\fR
.sp
\fB$xyplot\fR dotconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
.sp
\fB$xyplot\fR contourlines \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
.sp
\fB$xyplot\fR contourlinesfunctionvalues \fIxvec\fR \fIyvec\fR \fIvaluesmat\fR ?classes?
.sp
\fB$xyplot\fR contourfill \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
.sp
................................................................................
.sp
\fB$plot3d\fR colours \fIfill\fR \fIborder\fR
.sp
\fB$plot3d\fR ribbon \fIyzpairs\fR
.sp
\fB$plot3d\fR plot \fIyzpairs\fR
.sp
\fB$xyplot\fR dataconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
.sp
\fB$pie\fR plot \fIdata\fR
.sp
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR ...
.sp
\fB$pie\fR explode \fIsegment\fR
.sp
\fB$radial\fR plot \fIdata\fR \fIcolour\fR \fIthickness\fR
.sp
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR ...
.sp
\fB$barchart\fR plot \fIseries\fR \fIydata\fR \fIcolour\fR ?dir? ?brightness?
.sp
\fB$barchart\fR config \fB-option\fR \fIvalue\fR ...
.sp
\fB$barchart\fR plot \fIseries\fR \fIxdata\fR \fIcolour\fR ?dir? ?brightness?
.sp
\fB$barchart\fR config \fB-option\fR \fIvalue\fR ...
.sp
\fB$barchart\fR plot \fIlabel\fR \fIyvalue\fR \fIcolour\fR
.sp
\fB$barchart\fR config \fB-option\fR \fIvalue\fR ...
.sp
\fB$ribbon\fR line \fIxypairs\fR \fIcolour\fR
.sp
\fB$ribbon\fR area \fIxypairs\fR \fIcolour\fR
.sp
\fB$boxplot\fR plot \fIseries\fR \fIlabel\fR \fIvalues\fR
.sp
................................................................................
.sp
\fB$anyplot\fR bindlast \fIseries\fR \fIevent\fR \fIcommand\fR
.sp
.BE
.SH DESCRIPTION
.PP
Plotchart is a Tcl-only package that focuses on the easy creation of
xy-plots, barcharts and other common types of graphical presentations.
The emphasis is on ease of use, rather than flexibility. The procedures
that create a plot use the entire canvas window, making the layout
of the plot completely automatic.
.PP
This results in the creation of an xy-plot in, say, ten lines of code:
.PP
.CS


    package require Plotchart

    canvas .c -background white -width 400 -height 200
    pack   .c -fill both

    #
    # Create the plot with its x- and y-axes
    #
    set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]

    foreach {x y} {0.0 32.0 10.0 50.0 25.0 60.0 78.0 11.0 } {
        $s plot series1 $x $y
    }

    $s title "Data series"

.CE
.PP
A drawback of the package might be that it does not do any data
management. So if the canvas that holds the plot is to be resized, the
whole plot must be redrawn.
The advantage, though, is that it offers a number of plot and chart
types:
.IP \(bu
XY-plots like the one shown above with any number of data series.
.IP \(bu
Stripcharts, a kind of XY-plots where the horizontal axis is adjusted
automatically. The result is a kind of sliding window on the data
series.
.IP \(bu
Polar plots, where the coordinates are polar instead of cartesian.
.IP \(bu
Histograms, for plotting statistical information.
.IP \(bu
Isometric plots, where the scale of the coordinates in the two
directions is always the same, i.e. a circle in world coordinates
appears as a circle on the screen.
.sp
You can zoom in and out, as well as pan with these plots (\fINote:\fR
this works best if no axes are drawn, the zooming and panning routines
do not distinguish the axes), using the mouse buttons with the control
key and the arrow keys with the control key.
.IP \(bu
Piecharts, with automatic scaling to indicate the proportions.
.IP \(bu
Barcharts, with either vertical or horizontal bars, stacked bars or
bars side by side.
.IP \(bu
Timecharts, where bars indicate a time period and milestones or other
important moments in time are represented by triangles.
.IP \(bu
3D plots (both for displaying surfaces and 3D bars)
.PP
With version 1.5 a new command has been introduced: plotconfig, which
can be used to configure the plot options for particular types of plots
and charts (cf. \fBCONFIGURATION OPTIONS\fR)
With version 1.8.3 several new features were introduced, which allow more interactivity
(cf. \fBINTERACTIVE USE\fR)
.SH "PLOT CREATION COMMANDS"
You create the plot or chart with one single command and then fill the
plot with data:
.TP
\fB::Plotchart::createXYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIargs\fR
Create a new xy-plot (configuration type: xyplot).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
For an inverted axis, where the maximum appears on the left-hand side,
use: maximum, minimum and a \fInegative\fR stepsize.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
For an inverted axis, where the maximum appears at the bottom,
use: maximum, minimum and a \fInegative\fR stepsize.
.TP
list \fIargs\fR (in)
Zero or more options that influence the appearance of the plot:
.RS
.IP \(bu
\fI-xlabels {labels}:\fR Custom labels for the x-axis. If the labels
are numeric, they are positioned according to the given scale,
otherwise they are positioned with equal distance, based on the number
of labels. Note: this only works if the stepsize of the xaxis argument is
the empty string.
.IP \(bu
\fI-ylabels {labels}:\fR Similarly, custom labels for the y-axis.
.IP \(bu
\fI-box {measures}:\fR See \fBARRANGING MULTIPLE PLOTS IN A CANVAS\fR
.IP \(bu
\fI-axesbox {measures}:\fR See \fBARRANGING MULTIPLE PLOTS IN A CANVAS\fR
.RE
.RE
.sp
.TP
\fB::Plotchart::createStripchart\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new strip chart (configuration type: stripchart). The
only difference to a regular XY plot is
that the x-axis will be automatically adjusted when the x-coordinate
of a new point exceeds the maximum.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
Note that an inverted x-axis is \fInot\fR supported for this type of plot.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
For an inverted axis, where the maximum appears at the bottom,
use: maximum, minimum and a \fInegative\fR stepsize.
.RE
.sp
.TP
\fB::Plotchart::createTXPlot\fR \fIw\fR \fItimeaxis\fR \fIxaxis\fR
Create a new time-x-plot (configuration type: txplot). The horizontal axis represents the date/time
of the data and the vertical axis the values themselves.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fItimeaxis\fR (in)
A 3-element list containing the minimum and maximum date/time to be
shown and the stepsize (\fIin days\fR) for the time-axis, in this order.
Note that an inverted time-axis is \fInot\fR supported.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the
vertical axis, in this order.
For an inverted axis, where the maximum appears at the bottom,
use: maximum, minimum and a \fInegative\fR stepsize.
.RE
.sp
.TP
\fB::Plotchart::createXLogYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new xy-plot where the y-axis has a logarithmic scale (configuration type: xlogyplot).
.sp
The data should be given as for a linear scale, as the logarithmic transformation
is taken of internally.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
For an inverted axis, where the maximum appears on the left-hand side,
use: maximum, minimum and a \fInegative\fR stepsize.
.TP
list \fIyaxis\fR (in)
A 2-element list containing minimum and maximum for the y-axis, in this order.
Note that an inverted logarithmic axis is \fInot\fR supported.
.RE
.sp
.TP
\fB::Plotchart::createLogXYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new xy-plot where the x-axis has a logarithmic scale (configuration type: logxyplot).
.sp
The data should be given as for a linear scale, as the logarithmic transformation
is taken of internally.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 2-element list containing minimum and maximum for the x-axis, in this order.
Note that an inverted logarithmic axis is \fInot\fR supported.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
For an inverted axis, where the maximum appears on the left-hand side,
use: maximum, minimum and a \fInegative\fR stepsize.
.RE
.sp
.TP
\fB::Plotchart::createLogXLogYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new xy-plot where both the x-axis and the y-axis have a logarithmic scale
(configuration type: logxlogyplot).
.sp
The data should be given as for a linear scale, as the logarithmic transformation
is taken of internally.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 2-element list containing minimum and maximum for the x-axis, in this order.
Note that an inverted logarithmic axis is \fInot\fR supported.
.TP
list \fIyaxis\fR (in)
A 2-element list containing minimum and maximum for the y-axis, in this order.
Note that an inverted logarithmic axis is \fInot\fR supported.
.RE
.sp
.TP
\fB::Plotchart::createPolarPlot\fR \fIw\fR \fIradius_data\fR
Create a new polar plot (configuration type: polarplot).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIradius_data\fR (in)
A 2-element list containing maximum radius and stepsize for the radial
axis, in this order.
.RE
.sp
.TP
\fB::Plotchart::createWindrose\fR \fIw\fR \fIradius_data\fR \fIsectors\fR
Create a new windrose diagram. The diagram will consist of concentric
circles as defined by the \fIradius_data\fR argument and a number of
sectors (given by the \fIsectors\fR argument). The sectors are drawn in
the "nautical" convention, that is: the first is located at the positive
y-axis, the second is to the right and so on in a clockwise direction.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the diagram
.TP
list \fIradius_data\fR (in)
A 2-element list, the first element is the maximum radius, the second is
the step to be used for the circles.
.TP
int \fIsectors\fR
Number of sectors to use (defaults to 16).
.RE
.sp
.TP
\fB::Plotchart::createIsometricPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIstepsize\fR
Create a new isometric plot, where the vertical and the horizontal
coordinates are scaled so that a circle will truly appear as a circle (configuration type: isometric).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 2-element list containing minimum, and maximum for the x-axis, in this order.
.TP
list \fIyaxis\fR (in)
A 2-element list containing minimum, and maximum for the y-axis, in this order.
.TP
float|\fBnoaxes\fR \fIstepsize\fR (in)
Either the stepsize used by both axes or the keyword \fBnoaxes\fR to
signal the plot that it should use the full area of the widget, to not
draw any of the axes.
.RE
.sp
.TP
\fB::Plotchart::createHistogram\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new histogram (configuration type: histogram).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.RE
.sp
.TP
\fB::Plotchart::create3DPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIzaxis\fR
Create a new 3D plot.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.TP
list \fIzaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the z-axis, in this order.
.RE
.sp
.TP
\fB::Plotchart::create3DRibbonPlot\fR \fIw\fR \fIyaxis\fR \fIzaxis\fR
Create a new 3D ribbon plot. It is a simplification of the full 3D plot and allows for
the drawing of a ribbon only (the x-axis is dropped).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.TP
list \fIzaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the z-axis, in this order.
.RE
.sp
.TP
\fB::Plotchart::createPiechart\fR \fIw\fR
Create a new piechart (configuration type: piechart).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.RE
.sp
.TP
\fB::Plotchart::createSpiralPie\fR \fIw\fR
Create a new "spiral pie" (configuration type: spiralpie), a variation on the ordinary
piechart. The value is used to scale the radius, rather than the angle. By default the
data are sorted.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.RE
.sp
.TP
\fB::Plotchart::createRadialchart\fR \fIw\fR \fInames\fR \fIscale\fR \fIstyle\fR
Create a new radial chart (the data are drawn as a line connecting the
spokes of the diagram) (configuration type: radialchart).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fInames\fR (in)
Names for the spokes.
.TP
float \fIscale\fR (in)
Scale value to determine the position of the data along the spokes.
.TP
string \fIstyle\fR (in)
Style of the chart (optional). One of:
.RS
.IP \(bu
\fIlines\fR - the default: draw the data as independent polylines.
.IP \(bu
\fIcumulative\fR - draw the data as polylines where the data are
accumulated.
.IP \(bu
\fIfilled\fR - draw the data as filled polygons where the data are
accumulated
.RE
.RE
.sp
.TP
\fB::Plotchart::createBarchart\fR \fIw\fR \fIxlabels\fR \fIyaxis\fR \fInoseries\fR
Create a new barchart with vertical bars (configuration type: vertbars). The horizontal axis will
display the labels contained in the argument \fIxlabels\fR. The number
of series given by \fInoseries\fR determines both the width of the
bars, and the way the series will be drawn.
.sp
If the keyword \fBstacked\fR was specified the series will be drawn
stacked on top of each other. Otherwise each series that is drawn will
be drawn shifted to the right.
.sp
The number of series determines the width of the bars, so that there is
space of that number of bars. If you use a floating-point number, like
2.2, instead of an integer, like 2, a small gap between the sets of bars
will be drawn - the width depends on the fractional part.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxlabels\fR (in)
List of labels for the x-axis. Its length also determines the number of
bars that will be plotted per series.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.TP
int|\fBstacked\fR \fInoseries\fR (in)
The number of data series that will be plotted. This has to be an
integer number greater than zero (if \fBstacked\fR is not used).
.RE
.sp
.TP
\fB::Plotchart::createHorizontalBarchart\fR \fIw\fR \fIxaxis\fR \fIylabel\fR \fInoseries\fR
Create a new barchart with horizontal bars (configuration type: horizbars). The vertical axis will
display the labels contained in the argument \fIylabels\fR. The number
of series given by \fInoseries\fR determines both the width of the
bars, and the way the series will be drawn.
.sp
If the keyword \fBstacked\fR was specified the series will be drawn
stacked from left to right. Otherwise each series that is drawn will
be drawn shifted upward.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
.TP
list \fIylabels\fR (in)
List of labels for the y-axis. Its length also determines the number of
bars that will be plotted per series.
.TP
int|\fBstacked\fR \fInoseries\fR (in)
The number of data series that will be plotted. This has to be an
integer number greater than zero (if \fBstacked\fR is not used).
.RE
.sp
.TP
\fB::Plotchart::create3DBarchart\fR \fIw\fR \fIyaxis\fR \fInobars\fR
Create a new barchart with 3D vertical bars (configuration type: 3dbars). The horizontal axis will
display the labels per bar. The number of bars given by \fInobars\fR
determines the position and the width of the bars. The colours can be
varied per bar. (This type of chart was inspired by the Wiki page on 3D
bars by Richard Suchenwirth.)
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.TP
int \fInobars\fR (in)
The number of bars that will be plotted.
.RE
.sp
.TP
\fB::Plotchart::create3DRibbonChart\fR \fIw\fR \fInames\fR \fIyaxis\fR \fIzaxis\fR
Create a new "ribbon chart" (configuration type: 3dribbon). This is
a chart where the data series are
represented as ribbons in a three-dimensional axis system. Along the
x-axis (which is "into" the screen) the names are plotted, each
representing a single series. The first plot command draws the furthest
series, the second draws the series in front of that and so on.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
widget \fIw\fR (in)
Names of the series, plotted as labels along the x-axis
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis
(drawn horizontally!), in this order.
.TP
list \fIzaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the z-axis
(drawn vertically), in this order.
.TP
int \fInobars\fR (in)
The number of bars that will be plotted.
.RE
.sp
.TP
\fB::Plotchart::createBoxplot\fR \fIw\fR \fIxdata\fR \fIydata\fR \fIorientation\fR
Create a new boxplot with horizontal or vertical boxes (box-and-whiskers) (configuration type: boxplot). Depending
on the orientation the x- or y-axis is drawn with labels. The boxes are drawn based on the raw data
(see the plot subcommand for this type of plot).
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIxdata\fR (in)
This is either a 3-element list containing minimum, maximum and stepsize for the x-axis, in this order
(when orientation is horizontal), or a list of labels for the x-axis (when orientation is vertical). The length
of the label list also determines the number of boxes that can be plotted. The labels are also used in the plot
subcommand.
.TP
list \fIydata\fR (in)
This is either a 3-element list containing minimum, maximum and stepsize for the y-axis, in this order
(when orientation is vertical), or a list of labels for the y-axis (when orientation is horizontal). The length
of the label list also determines the number of boxes that can be plotted. The labels are also used in the plot
subcommand.
.TP
string \fIorientation\fR (in)
If given, "horizontal" or "vertical" determines the orientation of the boxes. This optional value (default: horizontal)
also determines the interpretation of the xdata and ydata arguments.
.RE
.sp
.TP
\fB::Plotchart::createTimechart\fR \fIw\fR \fItime_begin\fR \fItime_end\fR \fIargs\fR
Create a new timechart (configuration type: timechart).
The time axis (= x-axis) goes from \fItime_begin\fR to \fItime_end\fR,
and the vertical spacing is determined by the number of items to plot.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
string \fItime_begin\fR (in)
The start time given in a form that is recognised by the \fBclock scan\fR
command (e.g. "1 january 2004").
.TP
string \fItime_end\fR (in)
The end time given in a form that is recognised by the \fBclock scan\fR
command (e.g. "1 january 2004").
.TP
arguments \fIargs\fR (in)
The remaining arguments can be:
.RS
.IP \(bu
The expected/maximum number of items. This determines the vertical
spacing. (If given, it must be the first argument after "time_end"
.IP \(bu
The keyword -barheight and the number of pixels per bar. This is an
alternative method to determine the vertical spacing.
.IP \(bu
The keyword -ylabelwidth and the number of pixels to reserve for the
labels at the y-axis.
.RE
.RE
.TP
\fB::Plotchart::createGanttchart\fR \fIw\fR \fItime_begin\fR \fItime_end\fR \fIargs\fR
Create a new Gantt chart (configuration type: ganttchart).
The time axis (= x-axis) goes from \fItime_begin\fR to \fItime_end\fR,
and the vertical spacing is determined by the number of items to plot.
Via the specific commands you can then add tasks and connections between
the tasks.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
string \fItime_begin\fR (in)
The start time given in a form that is recognised by the \fBclock scan\fR
command (e.g. "1 january 2004").
.TP
string \fItime_end\fR (in)
The end time given in a form that is recognised by the \fBclock scan\fR
command (e.g. "1 january 2004").
.TP
arguments \fIargs\fR (in)
The remaining arguments can be:
.RS
.IP \(bu
The expected/maximum number of items. This determines the vertical
spacing. (If given this way, it must be the first argument after "time_end")
.IP \(bu
The expected/maximum width of the descriptive text (roughly in characters,
for the actual space reserved for the text, it is assumed that a
character is about ten pixels wide). Defaults to 20. (If given this way,
it must be the second argument after "time_end").
.IP \(bu
The keyword -barheight and the number of pixels per bar. This is an
alternative method to determine the vertical spacing.
.IP \(bu
The keyword -ylabelwidth and the number of pixels to reserve for the
labels at the y-axis.
.RE
.RE
.TP
\fB::Plotchart::createRightAxis\fR \fIw_or_plot\fR \fIyaxis\fR
Create a plot command that will use a right axis instead of the left
axis (configuration type: inherited from the existing plot). The canvas widget
must already contain an ordinary plot, as the
horizontal axis and other properties are reused. Preferably use the
plot command, as with multiple plots in a canvas (also when redefining an existing
plot!), the wrong geometry might be used.
.sp
To plot data using the
right axis, use this new command, to plot data using the \fIleft\fR
axis, use the original plot command.
.RS
.TP
widget \fIw_or_plot\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot or preferably the
plot command for the plot with the left axis.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
.RE
.TP
\fB::Plotchart::createTableChart\fR \fIw\fR \fIcolumns\fR ?widths?
Create a command to draw a table. You can use a variety of commands to
draw the actual rows of the table, but the number of columns is fixed.
(See \fBTABLE CHARTS\fR for an example)
.RS
.TP
widget \fIw\fR (in)
Name of the canvas widget to hold the table.
.TP
list \fIcolumns\fR (in)
The headers of the columns in the table. The number of elements
determines the number of columns.
.TP
list \fIwidths\fR (in)
If given, either a single value, the width in pixels for all columns or
for each column the width of that column. If not given, the table is
spread out over the width of the canvas (minus the margins).
.RE
.sp
.PP
.SH "PLOT METHODS"
Each of the creation commands explained in the last section returns
the name of a new object command that can be used to manipulate the
plot or chart. The subcommands available to a chart command depend on
the type of the chart.
.PP
General subcommands for all types of charts. \\$anyplot is the command
returned by the creation command:
.TP
\fB$anyplot\fR title \fItext\fR \fIposition\fR
Specify the title of the whole chart.
.RS
.TP
string \fItext\fR (in)
The text of the title to be drawn.
.TP
string \fIposition\fR (in)
The position of the title. The default position is "center", but you can
alternatively use "left" or "right". You can use multiple titles with
different positions.
.RE
.sp
.TP
\fB$anyplot\fR subtitle \fItext\fR
Specify the subtitle of the whole chart.
.RS
.TP
string \fItext\fR (in)
The text of the subtitle to be drawn.
.RE
.sp
.TP
\fB$anyplot\fR canvas
Return the name of the canvas (or the alias if you use more than one plot within a
canvas). Use this value for the coordinate transformations.
.sp
.TP
\fB$anyplot\fR saveplot \fIfilename\fR \fIargs\fR
Draws the plot into a file, using PostScript.
.RS
.TP
string \fIfilename\fR (in)
Contain the path name of the file to write the plot to.
.TP
list \fIargs\fR (in)
If the standard PostScript output is used, the option -plotregion can be specifed
to save the whole plot (value: bbox) regardless of what is visible in the window.
The default (value: window) is to only plot the visible part of the plot.
.sp
Optionally you can specify the option -format "some picture format" to
store the plot in a different file than a PostScript file. This,
however, relies on the Img package to do the actual job.
.sp
\fINote:\fR
Because the window holding the plot must be fully visible before Img can
successfully grab it, it is raised first.
On some systems, for instance Linux with KDE, raising
a window is not done automatically, but instead you need to click on the
window in the task bar. Similar things happen on Windows XP.
.sp
There seems to be something wrong under some circumstances, so instead
of waiting for the visibility of the window, the procedure simply waits
two seconds. It is not ideal, but it seems to work better.
.RE
.sp
.TP
\fB$anyplot\fR xtext \fItext\fR
Specify the title of the (horizontal) x-axis, for those plots that have
a straight x-axis.
.RS
.TP
string \fItext\fR (in)
The text of the x-axis label to be drawn.
.RE
.sp
.TP
\fB$anyplot\fR ytext \fItext\fR
Specify the title of the (horizontal) y-axis, for those plots that have
a straight y-axis.
.RS
.TP
string \fItext\fR (in)
The text of the y-axis label to be drawn.
.RE
.TP
\fB$anyplot\fR vtext \fItext\fR
Draw a \fIvertical\fR label to the y-axis. Note: this requires Tk 8.6
or later, for older versions it does nothing.
.RS
.TP
string \fItext\fR (in)
Text to drawn to the y-axis
.RE
.sp
.TP
\fB$anyplot\fR xsubtext \fItext\fR
Specify the subtext of the (horizontal) x-axis, for those plots that have
a straight x-axis. This text is drawn below the primary text.
.sp
Since this involves positioning the primary text and setting margins, you need to
set the option "usesubtext" for the bottom axis via the plotstyle command. The relevant
options are: usesubtext, subtextcolor and subtextfont.
.RS
.TP
string \fItext\fR (in)
The secondary text of the x-axis label to be drawn.
.RE
.sp
.TP
\fB$anyplot\fR ysubtext \fItext\fR
Specify the subtext of the (vertical) y-axis, for those plots that have
a straight y-axis. This text is drawn below the primary text, for both
axes on the left and the right.
.sp
Since this involves positioning the primary text and setting margins, you need to
set the option "usesubtext" for the left or right axis via the plotstyle command. The relevant
options are: usesubtext, subtextcolor and subtextfont.
.RS
.TP
string \fItext\fR (in)
The secondary text of the y-axis label to be drawn.
.RE
.sp
.TP
\fB$anyplot\fR vsubtext \fItext\fR
Specify the subtext of the (vertical) y-axis, for those plots that have
a straight y-axis. This text is drawn to the \fIright\fR of the primary text, for both
axes on the left and the right.
.sp
Since this involves positioning the primary text and setting margins, you need to
set the option "usesubtext" for the left or right axis via the plotstyle command. The relevant
options are: usevsubtext, vsubtextcolor and vsubtextfont. (Note the "v" to distinguish this
option from the text at the top of a vertical axis that is drawn via \fI$anyplot ytext\fR or
\fI$anyplot ysubtext\fR.)
.RS
.TP
string \fItext\fR (in)
The secondary (vertical) text of the y-axis label to be drawn.
.RE
.sp
.TP
\fB$anyplot\fR xconfig \fB-option\fR \fIvalue\fR ...
Set one or more configuration parameters for the x-axis.
The following options are supported:
.RS
.TP
\fBformat\fR fmt
The format for the numbers along the axis.
.TP
\fBticklength\fR length
The length of the tickmarks (in pixels).
.TP
\fBticklines\fR boolean
Whether to draw ticklines (\fBtrue\fR) or not (\fBfalse\fR).
.TP
\fBscale\fR scale_data
New scale data for the axis, i.e. a 3-element list containing minimum,
maximum and stepsize for the axis, in this order.
.sp
\fIBeware:\fR Setting this option will clear all data from the plot.
.RE
.sp
.TP
\fB$anyplot\fR yconfig \fB-option\fR \fIvalue\fR ...
Set one or more configuration parameters for the y-axis. This method
accepts the same options and values as the method \fBxconfig\fR.
.TP
\fB$anyplot\fR background \fIpart\fR \fIcolour_or_image\fR \fIdir\fR ?brightness?
Set the background of a part of the plot
.RS
.TP
string \fIpart\fR
Which part of the plot: "axes" for the axes area and "plot" for the
inner part. The interpretation depends on the type of plot. Two further
possibilities are:
.RS
.IP \(bu
\fIimage\fR, in which case a predefined image is loaded
into the background of the plot.
.IP \(bu
\fIgradient\fR, in which case the background is coloured in different
shades of the given colour. The "dir" argument specifies the direction
in which the colour gets whiter.
.RE
.TP
string \fIcolour_or_image\fR
Colour for that part or the name of the image if "part" is "image"
.TP
string \fIdir\fR
The direction of the gradient. One of: top-down, bottom-up, left-right
or right-left.
.TP
string \fIbrightness\fR
Indicates whether the colour should become brighter (bright) or darker (dark). Defaults to bright
.RE
.sp
.TP
\fB$anyplot\fR xticklines \fIcolour\fR ?dash?
Draw vertical ticklines at each tick location
.RS
.TP
string \fIcolour\fR
Colour of the lines. Specifying an empty colour ("") removes them again.
Defaults to "black"
.TP
string \fIdash\fR
Optional argument to specify the dash pattern for the lines. Defaults to "lines"
Possible values: lines, dots1, dots2, dots3, dots4, dots5.
The actual effect depends on the platform.
.RE
.sp
.TP
\fB$anyplot\fR yticklines \fIcolour\fR ?dash?
Draw horizontal ticklines at each tick location
.RS
.TP
string \fIcolour\fR
Colour of the lines. Specifying an empty colour ("") removes them again
Defaults to "black"
.TP
string \fIdash\fR
Optional argument to specify the dash pattern for the lines. Defaults to "lines"
Possible values: lines, dots1, dots2, dots3, dots4, dots5.
The actual effect depends on the platform.
.RE
.sp
.TP
\fB$anyplot\fR legend \fIseries\fR \fItext\fR ?spacing?
Add an entry to the legend. The series determines which graphical
symbol is to be used. (As a side effect the legend is actually drawn.)
.RS
.TP
string \fIseries\fR
Name of the data series. This determines the colour of the line and the
symbol (if any) that will be drawn.
.TP
string \fItext\fR
Text to be drawn next to the line/symbol.
.TP
integer \fIspacing\fR
Optional argument to specify the vertical spacing between the entries (in pixels).
(Note that this spacing will be reused later.)
.RE
.sp
.TP
\fB$anyplot\fR removefromlegend \fIseries\fR
Remove an entry for a series from the legend and redraw it.
.RS
.TP
string \fIseries\fR
Name of the data series to be removed.
.RE
.sp
.TP
\fB$anyplot\fR legendconfig \fB-option\fR \fIvalue\fR ...
Set one or more options for the legend. The legend is drawn as a
rectangle with text and graphics inside.
.RS
.TP
\fBbackground\fR colour
Set the colour of the background (the default colour is white).
Set to the empty string for a transparant legend.
.TP
\fBborder\fR colour
Set the colour of the border (the default colour is black). Set to the
empty string if you do not want a border.
.TP
\fBcanvas\fR c
Draw the legend in a different canvas widget. This gives you the freedom
to position the legend outside the actual plot.
.TP
\fBfont\fR font
Set the font used to draw the text next to the symbol.
.TP
\fBlegendtype\fR
Override the type of the legend, that is pre-defined for the current type of
plot. May be one of: rectangle or line.
.TP
\fBposition\fR corner
Set the position of the legend. May be one of: top-left, top-right,
bottom-left or bottom-right. (Default value is top-right.)
.RE
.sp
.TP
\fB$anyplot\fR balloon \fIx\fR \fIy\fR \fItext\fR \fIdir\fR
Add balloon text to the plot (except for 3D plots). The arrow will point
to the given x- and y-coordinates. For xy-graphs and such, the
coordinates are directly related to the axes; for vertical barcharts the
x-coordinate is measured as the number of bars minus 1 and similar for
horizontal barcharts.
.RS
.TP
float \fIx\fR
X-coordinate of the point that the arrow of the balloon will point to.
.TP
float \fIy\fR
Y-coordinate of the point that the arrow of the balloon will point to.
.TP
string \fItext\fR
Text to be drawn in the balloon.
.TP
string \fIdir\fR
Direction of the arrow, one of: north, north-east, east, south-east,
south, south-west, west or north-west.
.RE
.sp
.TP
\fB$anyplot\fR balloonconfig \fIargs\fR
Configure the balloon text for the plot. The new settings will be used
for the next balloon text.
.RS
.TP
\fBfont\fR fontname
Font to be used for the text
.TP
\fBjustify\fR left|center|right
Way to justify multiline text
................................................................................
Width of the outline of the balloon (in pixels)
.TP
\fBarrowsize\fR value
Length factor for the arrow (in pixels)
.RE
.TP
\fB$anyplot\fR plaintext \fIx\fR \fIy\fR \fItext\fR \fIdir\fR
Add plain text to the plot (except for 3D plots). The text is positioned at
the given x- and y-coordinates. For xy-graphs and such, the
coordinates are directly related to the axes; for vertical barcharts the
x-coordinate is measured as the number of bars minus 1 and similar for
horizontal barcharts.
.RS
.TP
float \fIx\fR
X-coordinate of the text position
.TP
float \fIy\fR
Y-coordinate of the text position
.TP
string \fItext\fR
Text to be drawn.
.TP
string \fIdir\fR
Anchor for the text, one of: north, north-east, east, south-east,
south, south-west, west or north-west.
.RE
.sp
.TP
\fB$anyplot\fR plaintextconfig \fIargs\fR
Configure the plain text annotation for the plot. The new settings will be used
for the next plain text.
.RS
.TP
\fBfont\fR fontname
Font to be used for the text
.TP
\fBjustify\fR left|center|right
Way to justify multiline text
................................................................................
.TP
\fBtextcolour\fR colour
Colour for the text (synonym: textcolor)
.RE
.TP
\fB$anyplot\fR object \fIitemtype\fR \fIseries\fR \fIargs\fR
Draw a canvas item in the plot where the coordinates are scaled using the
coordinate system of the plot. In addition to the standard canvas types, it
also supports circles, dots and crosses.
.sp
\fINote:\fR Currently implemented for xy-plots, (vertical and horizontal)
barcharts, and piecharts.
.sp
\fINote:\fR To add an entry in the legend for the object, you can use the
\fIdataconfig\fR subcommand with a type "rectangle". This will cause a rectangle
to be shown.
.RS
.TP
string \fIitemtype\fR (in)
Name of a standard canvas item or "circle", "dot" or "cross"
.TP
string \fIseries\fR (in)
The data series it belongs to, used for setting the default drawing options
................................................................................
.TP
list \fIargs\fR (in)
List of coordinates and drawing options
.RE
.TP
\fB$anyplot\fR deletedata
Remove the lines, symbols and other graphical object associated with the
actual data from the plot.
.sp
\fINote:\fR Currently implemented for xy-plots only
.sp
\fINote:\fR The existing options for data series and the legend entry are
kept as they were.
.sp
\fINote:\fR Currently there are side effects if the canvas contains more than
one plot.
.PP
.PP
\fINote:\fR The commands \fBxconfig\fR and \fByconfig\fR are
currently implemented only for XY-plots
and only the option \fB-format\fR has any effect.
.PP
For \fIxy plots\fR, \fIstripcharts\fR, \fIhistograms\fR and
\fItime-x-plots\fR:
.TP
\fB$xyplot\fR plot \fIseries\fR \fIxcrd\fR \fIycrd\fR
Add a data point to the plot.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the new point belongs to.
.TP
float \fIxcrd\fR (in)
X-coordinate of the new point. (For time-x plots this must be valid
date/time that can be read with the \fIclock scan\fR command).
.TP
float \fIycrd\fR (in)
Y-coordinate of the new point.
.RE
.PP
.PP
For \fIxy plots\fR there is the additional command \fIplotlist\fR,
which is useful for plotting a large amount of data:
.TP
\fB$xyplot\fR plotlist \fIseries\fR \fIxlist\fR \fIylist\fR \fIevery\fR
Draw a series of data as a whole. If symbols are asked for, draw them only
for every Nth data point.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the new point belongs to.
.TP
float \fIxlist\fR (in)
List of X-coordinates for the data series.
.TP
float \fIycrd\fR (in)
List of Y-coordinates for the data series.
.TP
int \fIevery\fR (in)
Optional argument stating how often a symbol (if any) should be drawn.
If left out, use a simple heuristic: N = sqrt(number of data points).
.RE
.PP
.PP
\fINote on histograms:\fR
.PP
For histograms the x-coordinate that is given is interpreted to be
the x-coordinate of the \fIright\fR side of the bar (or line segment). The first
bar starts at the y-axis on the left. To completely fill the range
of the x-axis, you should draw a bar at the maximum x-coordinate.
.PP
For histograms you can also use the \fBplotcumulative\fR command:
.TP
\fB$histogram\fR plotcumulative \fIseries\fR \fIxcrd\fR \fIycrd\fR
.PP
The arguments mean exactly the same as for the \fBplot\fR command, but
the data are accumulated to the previous values.
.PP
For \fIxy plots\fR:
.TP
\fB$xyplot\fR trend \fIseries\fR \fIxcrd\fR \fIycrd\fR
Draw or update a trend line using the data given sofar.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the trend line belongs to.
.TP
float \fIxcrd\fR (in)
X-coordinate of the new data point
.TP
float \fIycrd\fR (in)
Y-coordinate of the new data point
.RE
.TP
\fB$xyplot\fR rchart \fIseries\fR \fIxcrd\fR \fIycrd\fR
Draw data in the same way as the plot method, but with two lines added
that indicate the expected range (+/- 3*standard deviation) of the data.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the data point belongs to.
.TP
float \fIxcrd\fR (in)
X-coordinate of the new data point
.TP
float \fIycrd\fR (in)
Y-coordinate of the new data point
.RE
.TP
\fB$xyplot\fR interval \fIseries\fR \fIxcrd\fR \fIymin\fR \fIymax\fR ?ycentr?
Add a vertical error interval to the plot. The interval is drawn from
ymin to ymax. If the ycentr argument is given, a symbol is drawn at that
position.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the interval belongs to.
.TP
float \fIxcrd\fR (in)
X-coordinate of the interval
.TP
float \fIymin\fR (in)
Minimum y-coordinate of the interval.
.TP
float \fIymax\fR (in)
Maximum y-coordinate of the interval.
.TP
float \fIycentr\fR (in)
Y-coordinate to draw the symbol at (optional)
.RE
.TP
\fB$xyplot\fR box-and-whiskers \fIseries\fR \fIxcrd\fR \fIycrd\fR
Draw a box and whiskers in the plot. If the argument \fIxcrd\fR is a
list of
several values and the argument \fIycrd\fR is a single value, a
horizontal
box is drawn with the quartiles determined from the list of values
contained in \fIxcrd\fR.
.sp
If, instead, the argument \fIycrd\fR contains a list of several values
and the argument \fIxcrd\fR a single value, then a vertical box is
drawn and the quartiles are determined from \fIycrd\fR. (There must be
exactly one list of several values. Otherwise an error is reported.)
.sp
The option -boxwidth to the dataconfig command determines the width (or
height) of the box (default: 10 pixels).
.sp
The option -whiskers to the dataconfig command determines whether the
whiskers are drawn to the extreme values (value: extremes), to 1.5
times the interquartile range (value: IQR or iqr), or not at all (value: none).
If the value is 'IQR' (uppercase), then
also extreme values will be shown (from 1.5 to 3 times the IQR as dots,
above 3 times IQR as stars). If the value is 'iqr' (lowercase) no extreme
values will be shown (default value: IQR).
.sp
The option -whiskerwidth to the dataconfig command determines the thickness of the line
that draws the whiskers (default: 1 pixel).
.sp
The option -mediancolour to the dataconfig command determines the
colour of the line used to draw the median within the box (default: same as -colour).
.sp
The option -medianwidth to the dataconfig command determines the thickness of the line
that draws the median within the box (default: 1 pixel).
.RS
.TP
string \fIseries\fR (in)
Name of the data series the box-and-whiskers belongs to.
.TP
float \fIxcrd\fR (in)
X-coordinate of the box or a list of values.
.TP
float \fIymin\fR (in)
Y-coordinate of the box or a list of values.
.RE
.sp
The box ends at the 1st and 3rd quartile, while the whiskers by default
are plotted to span 1.5 IQR (interquartile range) from the 1st and 3rd quartile.
.TP
\fB$xyplot\fR vector \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIucmp\fR \fIvcmp\fR
Draw a vector in the plot. The vector can be given as either cartesian
coordinates or as length/angle, where the angle is in degrees and is
interpreted according to the mathematical convention or the nautical.
(See the vectorconfig subcommand)
.RS
.TP
string \fIseries\fR (in)
Name of the series the vector belongs to. Determines the appearance and
interpretation.
.TP
float \fIxcrd\fR (in)
X-coordinate of the point where the arrow appears
.TP
float \fIycrd\fR (in)
Y-coordinate of the point where the arrow appears
.TP
................................................................................
float \fIucmp\fR (in)
X-component or the length of the vector
.TP
float \fIycentr\fR (in)
Y-component or the angle of the vector
.RE
.TP
\fB$xyplot\fR vectorconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
]
Set the vector drawing options for a particular series
.RS
.TP
string \fIseries\fR (in)
Name of the series the vector belongs to.
.RE
.IP
The options can be one of the following:
.RS
.TP
\fBcolour\fR
The colour of the arrow (default: black; synonym: color)
.TP
\fBscale\fR value
The scale factor used to convert the length of the
arrow into a number of pixels (default: 1.0)
.TP
\fBcentred\fR onoff
Logical value indicating that the xy-coordinates
are to be used as the start of the arrow or as the centre (default: 0;
synonym: centered)
.TP
\fBtype\fR keyword
Interpretation of the vector components. Can be "cartesian"
(default), in which case the x- and y-components are expected, "polar"
(the angle 0 coincides with the positive x-axis, 90 coincides with the
positive y-axis) or "nautical" (0 is "north" and 90 is "east").
.RE
.sp
.TP
\fB$xyplot\fR dot \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIvalue\fR
Draw a dot in the plot. The size and colour is determined by the value
and by the options set for the series it belongs to.
(See the dotconfig subcommand)
.RS
.TP
string \fIseries\fR (in)
Name of the series the dot belongs to. Determines size and colour
.TP
float \fIxcrd\fR (in)
X-coordinate of the point where the arrow appears
.TP
float \fIycrd\fR (in)
Y-coordinate of the point where the arrow appears
.TP
float \fIvalue\fR (in)
Value determining size and colour
.RE
.TP
\fB$xyplot\fR dotconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
]
Set the dot drawing options for a particular series
.RS
.TP
string \fIseries\fR (in)
Name of the series the dot belongs to.
.RE
.IP
The options can be one of the following:
.RS
.TP
\fBcolour\fR
The colour of the dot if no scaling is used or the value exceeds the
last limit of the classes.
.TP
\fBscale\fR value
The scale factor used to convert the value into the radius of the dot
in pixels (default: 1.0)
.TP
\fBradius\fR value
The default radius of the dots, used if there is no scaling by value
(in pixels; default: 3)
.TP
\fBscalebyvalue\fR onoff
Determines whether the dots all have the same size or a size depending
on the given value (default: on).
.TP
\fBoutline\fR onoff
Draw a black circle around the dot or not (default: on)
.TP
\fBclasses\fR list
Set the limits and the corresponding colours. For instance:
.CS


    $xyplot series1 -classes {0 blue 1 green} -colour red

.CE
.IP
will cause a blue dot to be drawn for values smaller than 0, a green dot
for values larger/equal 0 but lower than 1 and a red dot for values
larger/equal 1.
.TP
\fB3deffect\fR onoff
Show a highlight in the dots, to mimick a 3D effect (default: off)
.sp
If there is no list of classes for the particular series, the dots are
scaled by the value.
.sp
You can combine the colouring by value and the scaling by value by
setting a list of classes and setting the \fIscalebyvalue\fR option on.
.RE
.sp
.TP
\fB$xyplot\fR contourlines \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
Draw contour lines for the values given on the grid. The grid is defined
by the xcrd and ycrd arguments. The xcrd argument (resp. ycrd)
is expected to be a matrix, implemented as a list of lists which gives the
x-coordinates (resp. y-coordinates) of the grid cell corners.
The function values are given at these corners.
The number of rows in xvec (resp. yvec) is ny and each row contains nx values
so that the total number of values in xvec (resp. yvec) is nx * ny.
The classes determine which contour lines are drawn. If a value on one of
the corners is missing, the contour lines in that cell will not be
drawn.
.sp
Entries in the legend are drawn via the \fIlegendisolines\fR subcommand.
.RS
.TP
list \fIxcrd\fR (in)
List of lists, each value is an x-coordinate for a grid cell corner
.TP
list \fIycrd\fR (in)
List of lists, each value is an y-coordinate for a grid cell corner
.TP
list \fIvalues\fR (in)
List of lists, each value is the value at a grid cell corner
.TP
list \fIclasses\fR (in)
List of class values or a list of lists of two elements (each inner list
the class value and the colour to be used). If empty or missing, the
classes are determined automatically.
.sp
\fINote:\fR The class values must enclose the whole range of values.
\fINote:\fR The xcrd argument is generally made of nypoints identical rows, while
each row of ycrd is made with one single value.
.sp
.RE
.TP
\fB$xyplot\fR contourlinesfunctionvalues \fIxvec\fR \fIyvec\fR \fIvaluesmat\fR ?classes?
Draw contour lines for the values given on the grid. The grid is defined
by the xvec and yvec arguments. Here, xvec (resp. yvec) is a list of x-coordinates
(resp. y-coordinates). The number of values in xvec (resp. yvec) is the number of points in
the x-coordinate (resp. y-coordinate).
The function values are given at these corners. The
classes determine which contour lines are drawn. If a value on one of
the corners is missing, the contour lines in that cell will not be
drawn.
.sp
Entries in the legend are drawn via the \fIlegendisolines\fR subcommand.
.RS
.TP
list \fIxcrd\fR (in)
List of x-coordinates in increasing order.
.TP
list \fIycrd\fR (in)
List y-coordinates in increasing order.
.TP
list \fIvaluesmat\fR (in)
List of lists, each value is the value at a grid cell corner.
The total number of values is valuesmat is nx * ny.
.TP
list \fIclasses\fR (in)
List of class values or a list of lists of two elements (each inner list
the class value and the colour to be used). If empty or missing, the
classes are determined automatically.
.sp
\fINote:\fR The class values must enclose the whole range of values.
.sp
.RE
.TP
\fB$xyplot\fR contourfill \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
Draw filled contours for the values given on the grid. (The use of this
method is identical to the "contourlines" method).
.sp
Entries in the legend are drawn via the \fIlegendshades\fR subcommand.
.TP
\fB$xyplot\fR contourbox \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
Draw the cells as filled quadrangles. The colour is determined from
the average of the values on all four corners.
.sp
Entries in the legend are drawn via the \fIlegendshades\fR subcommand.
.TP
\fB$xyplot\fR colorMap \fIcolours\fR
Set the colours to be used with the contour methods. The argument is
either a predefined colourmap (grey/gray, jet, hot or cool)
or a list of colours. When selecting the colours for actually drawing the
contours, the given colours will be interpolated (based on the HLS scheme).
.RS
.TP
list \fIcolours\fR (in)
List of colour names or colour values or one of the predefined maps:
.RS
.IP \(bu
grey or gray: gray colours from dark to light
................................................................................
hot: colours from yellow via red to darkred
.IP \(bu
cool: colours from cyan via blue to magenta
.RE
.RE
.TP
\fB$xyplot\fR legendisolines \fIvalues\fR \fIclasses\fR
Add the contour classes to the legend as coloured lines. The text indicates the
values.
.RS
.TP
list \fIvalues\fR (in)
The list of values as used for the actual drawing. This argument is used only
if the list of classes is empty.
.TP
list \fIvalues\fR (in)
The list of classes as used for the actual drawing.
.RE
.TP
\fB$xyplot\fR legendshades \fIvalues\fR \fIclasses\fR
Add the contour classes to the legend as coloured rectangles. The text indicates the
values.
.RS
.TP
list \fIvalues\fR (in)
The list of values as used for the actual drawing. This argument is used only
if the list of classes is empty.
.TP
list \fIvalues\fR (in)
The list of classes as used for the actual drawing.
.RE
.TP
\fB$xyplot\fR grid \fIxcrd\fR \fIycrd\fR
Draw the grid cells as lines connecting the (valid) grid points.
.RS
.TP
list \fIxcrd\fR (in)
List of lists, each value is an x-coordinate for a grid cell corner
.TP
list \fIycrd\fR (in)
List of lists, each value is an y-coordinate for a grid cell corner
.RE
.sp
.TP
\fB$xyplot\fR xband \fIymin\fR \fIymax\fR
Draw a light grey band in the plot, ranging over the full x-axis. This
can be used to indicate a "typical" range for the data.
.RS
.TP
float \fIymin\fR (in)
Lower bound for the band
.TP
float \fIymax\fR (in)
Upper bound for the band
.RE
.sp
.TP
\fB$xyplot\fR yband \fIxmin\fR \fIxmax\fR
Draw a light grey band in the plot, ranging over the full y-axis. This
can be used to indicate a "typical" range for the data.
.RS
.TP
float \fIxmin\fR (in)
Lower bound for the band
.TP
float \fIxmax\fR (in)
Upper bound for the band
.RE
.sp
.TP
\fB$xyplot\fR labeldot \fIx\fR \fIy\fR \fItext\fR \fIorient\fR
Draw a label and a symbol in the plot. The label will appear near the
symbol. The label will be drawn in grey, so as not to be too
conspicuous.
.sp
You can configure the appearance of the symbol by using the data series
name "labeldot":
\fI$w dataconfig labeldot -colour red -type symbol -symbol dot\fR
.RS
.TP
float \fIx\fR (in)
................................................................................
Y-coordinate of the symbol to be drawn
.TP
string \fItext\fR (in)
Text for the label
.TP
string \fIorient\fR (in)
Optional orientation (one of w, e, n, s) defining the position of the
label with respect to the symbol. It defaults to w (so the label
appears left of the symbol).
.RE
.PP
.PP
For \fIpolar plots\fR:
.TP
\fB$polarplot\fR plot \fIseries\fR \fIradius\fR \fIangle\fR
Add a data point to the polar plot.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the new point belongs to.
.TP
float \fIradius\fR (in)
Radial coordinate of the new point.
.TP
float \fIangle\fR (in)
Angular coordinate of the new point (in degrees).
.RE
.PP
.PP
For \fIwind rose diagrams\fR:
.TP
\fB$windrose\fR plot \fIdata\fR \fIcolour\fR
Draw the data contained in the \fIdata\fR argument. The data are added to
the existing spokes towards the outer circle.
.RS
.TP
list \fIdata\fR (in)
List of data (the length should correspond to the number of sectors)
.TP
string \fIcolour\fR
Colour in which the new segments will be drawn
.RE
.PP
.PP
For \fI3D plots\fR:
.TP
\fB$plot3d\fR plotfunc \fIfunction\fR
Plot a function defined over two variables \fBx\fR and \fBy\fR.
The resolution is determined by the set grid sizes (see the method
\fBgridsize\fR for more information).
.RS
.TP
string \fIfunction\fR (in)
Name of the procedure that calculates the z-value for the given x and
y coordinates. The procedure has to accept two float arguments (x is
first argument, y is second) and return a floating-point value.
.RE
.sp
.TP
\fB$plot3d\fR plotfuncont \fIfunction\fR \fIcontours\fR
Plot a function defined over two variables \fBx\fR and \fBy\fR using
the contour levels in \fBcontours\fR to colour the surface.
The resolution is determined by the set grid sizes (see the method
\fBgridsize\fR for more information).
.RS
.TP
string \fIfunction\fR (in)
Name of the procedure that calculates the z-value for the given x and
y coordinates. The procedure has to accept two float arguments (x is
first argument, y is second) and return a floating-point value.
.TP
list \fIcontours\fR (in)
List of values in ascending order that represent the contour levels
(the boundaries between the colours in the contour map).
.RE
.sp
.TP
\fB$plot3d\fR gridsize \fInxcells\fR \fInycells\fR
Set the grid size in the two directions. Together they determine how
many polygons will be drawn for a function plot.
.RS
.TP
int \fInxcells\fR (in)
Number of grid cells in x direction. Has to be an integer number
greater than zero.
.TP
int \fInycells\fR (in)
Number of grid cells in y direction. Has to be an integer number
greater than zero.
.RE
.sp
.TP
\fB$plot3d\fR plotdata \fIdata\fR
Plot a matrix of data.
.RS
.TP
list \fIdata\fR (in)
The data to be plotted. The data has to be provided as a nested list
with 2 levels. The outer list contains rows, drawn in y-direction, and
each row is a list whose elements are drawn in x-direction, for the
columns. Example:
.sp
.CS


    set data {
    {1.0 2.0 3.0}
    {4.0 5.0 6.0}
    }

.CE
.RE
.sp
.TP
\fB$plot3d\fR colours \fIfill\fR \fIborder\fR
Configure the colours to use for polygon borders and inner area.
.RS
.TP
color \fIfill\fR (in)
The colour to use for filling the polygons.
.TP
color \fIborder\fR (in)
The colour to use for the border of the polygons.
.RE
.TP
\fB$plot3d\fR ribbon \fIyzpairs\fR
Plot a ribbon based on the pairs of yz-coordinates. The colours for
the ribbon itself and the edge are taken from the colours option.
.RS
.TP
list \fIyzpairs\fR (in)
List of pairs of yz-coordinates
.RE
.PP
.PP
For 3D ribbon plots:
.TP
\fB$plot3d\fR plot \fIyzpairs\fR
Plot a ribbon based on the pairs of yz-coordinates. The colours for
the ribbon itself and the edge are taken from the colours option.
.RS
.TP
list \fIyzpairs\fR (in)
List of pairs of yz-coordinates
.RE
.PP
.PP
For \fIxy plots\fR, \fIstripcharts\fR, \fIhistograms\fR and \fIpolar plots\fR:
.TP
\fB$xyplot\fR dataconfig \fIseries\fR \fB-option\fR \fIvalue\fR ...
Set the value for one or more options regarding the drawing of data of
a specific series.
.RS
.TP
string \fIseries\fR (in)
Name of the data series whose configuration we are changing.
.RE
.sp
The following options are allowed:
.RS
.TP
\fBcolour\fR c
.TP
\fBcolor\fR c
The colour to be used when drawing the data series.
.TP
\fBtype\fR enum
The drawing mode chosen for the series.
This can be one of \fBline\fR, \fBsymbol\fR, or \fBboth\fR.
.TP
\fBsymbol\fR enum
What kind of symbol to draw. The value of this option is ignored when
the drawing mode \fBline\fR was chosen. This can be one of
\fBplus\fR, \fBcross\fR, \fBcircle\fR, \fBup\fR (triangle
pointing up), \fBdown\fR (triangle pointing down), \fBdot\fR
(filled circle), \fBupfilled\fR or \fBdownfilled\fR (filled
triangles).
.TP
\fBradius\fR integer
The size of the radius of the symbol. The total width of the symbol will be
2 times the radius size. The default radius is 4.
.TP
\fBwidth\fR integer
The width of the line (if drawn) or the width of the polygon outline (if -filled).
.TP
\fBfilled\fR enum
Whether to fill the area above or below the data line or not. Can be one
of: \fBno\fR, \fBup\fR or \fBdown\fR (\fBSPECIAL EFFECTS\fR)
.TP
\fBfillcolour\fR colour
Colour to use when filling the area associated with the data line.
.TP
\fBstyle\fR enum
The style to be used for histograms:
.RS
.IP \(bu
\fBfilled\fR: Fill the area under the data points with bars (default)
.IP \(bu
................................................................................
.RE
.RE
.PP
.PP
For \fIpiecharts\fR and \fIspiral pies\fR:
.TP
\fB$pie\fR plot \fIdata\fR
Fill a piechart.
.RS
.TP
list \fIdata\fR (in)
A list of pairs (labels and values). The values determine the relative
size of the circle segments. The labels are drawn beside the circle.
.RE
.TP
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR ...
Set the colours to be used.
.RS
.TP
color \fIcolour1\fR (in)
The first colour.
.TP
color \fIcolour2\fR (in)
The second colour, and so on.
.RE
.TP
\fB$pie\fR explode \fIsegment\fR
Explode a segment (that is: move one segment out of the circle). If the segment is
indicated as "auto", then you can click on a segment. This will be exploded instead of
any previously exploded segment.
.RS
.TP
int \fIsegment\fR
The segment to be exploded or "auto" if you want to do this interactively.
.RE
.PP
.PP
For \fIradial charts\fR:
.TP
\fB$radial\fR plot \fIdata\fR \fIcolour\fR \fIthickness\fR
Draw a new line in the radial chart
.RS
.TP
list \fIdata\fR (in)
A list of data (one for each spoke). The values determine the distance
from the centre of the line connecting the spokes.
.TP
color \fIcolour\fR (in)
The colour for the line.
.TP
int \fIthickness\fR (in)
An optional argument for the thickness of the line.
.RE
.TP
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR ...
Set the colours to be used.
.RS
.TP
color \fIcolour1\fR (in)
The first colour.
.TP
color \fIcolour2\fR (in)
The second colour, and so on.
.RE
.PP
.PP
For \fIvertical barcharts\fR:
.TP
\fB$barchart\fR plot \fIseries\fR \fIydata\fR \fIcolour\fR ?dir? ?brightness?
Add a data series to a barchart.
.RS
.TP
string \fIseries\fR (in)
Name of the series the values belong to.
.TP
list \fIydata\fR (in)
A list of values, one for each x-axis label.
.TP
color \fIcolour\fR (in)
The colour of the bars.
.TP
string \fIdir\fR (in)
If given, "top-down" or "bottom-up", to indicate the direction in which the colour changes.
(If not given, a uniform colour is used).
.TP
string \fIbrightness\fR (in)
If given, "bright" or "dark" (defaulting to "bright"). The colour will change to respectively
white or black, depending on the direction.
.RE
.TP
\fB$barchart\fR config \fB-option\fR \fIvalue\fR ...
Set options for drawing the bars.
.RS
.TP
\fBshowvalues\fR boolean
Whether to show the values or not (above the bars)
.TP
\fBvaluefont\fR newfont
Name of the font to use for the values
................................................................................
Format string to use for formatting the values
.RE
.PP
.PP
For \fIhorizontal barcharts\fR:
.TP
\fB$barchart\fR plot \fIseries\fR \fIxdata\fR \fIcolour\fR ?dir? ?brightness?
Add a data series to a barchart.
.RS
.TP
string \fIseries\fR (in)
Name of the series the values belong to.
.TP
list \fIxdata\fR (in)
A list of values, one for each y-axis label.
.TP
color \fIcolour\fR (in)
The colour of the bars.
.TP
string \fIdir\fR (in)
If given, "left-right" or "right-left", to indicate the direction in which the colour changes.
(If not given, a uniform colour is used).
.TP
string \fIbrightness\fR (in)
If given, "bright" or "dark" (defaulting to "bright"). The colour will change to respectively
white or black, depending on the direction.
.RE
.TP
\fB$barchart\fR config \fB-option\fR \fIvalue\fR ...
Set options for drawing the bars.
.RS
.TP
\fBshowvalues\fR boolean
Whether to show the values or not (to the right of the bars)
.TP
\fBvaluefont\fR newfont
Name of the font to use for the values
................................................................................
Format string to use for formatting the values
.RE
.PP
.PP
For \fI3D barcharts\fR:
.TP
\fB$barchart\fR plot \fIlabel\fR \fIyvalue\fR \fIcolour\fR
Add the next bar to the barchart.
.RS
.TP
string \fIlabel\fR (in)
The label to be shown below the column.
.TP
float \fIyvalue\fR (in)
The value that determines the height of the column
.TP
color \fIcolour\fR (in)
The colour of the column.
.RE
.TP
\fB$barchart\fR config \fB-option\fR \fIvalue\fR ...
Set one or more configuration parameters. The following options are
supported:
.RS
.TP
\fBusebackground\fR boolean
Whether to draw walls to the left and to the back of the columns or not
.TP
\fBuseticklines\fR boolean
................................................................................
Plot the given xy-pairs as a ribbon in the chart
.RS
.TP
list \fIxypairs\fR (in)
The pairs of x/y values to be drawn (the series is drawn as a whole)
.TP
color \fIcolour\fR (in)
The colour of the ribbon.
.RE
.TP
\fB$ribbon\fR area \fIxypairs\fR \fIcolour\fR
Plot the given xy-pairs as a ribbon with a filled area in front. The
effect is that of a box with the data as its upper surface.
.RS
.TP
list \fIxypairs\fR (in)
The pairs of x/y values to be drawn (the series is drawn as a whole)
.TP
color \fIcolour\fR (in)
The colour of the ribbon/area.
.RE
.PP
For \fIboxplots\fR:
.TP
\fB$boxplot\fR plot \fIseries\fR \fIlabel\fR \fIvalues\fR
Add a box-and-whisker to the plot. The dataconfig command can be used to customize
the box-and-whisker (see the box-and-whiskers command for the xyplot for details).
.RS
.TP
string \fIseries\fR (in)
Name of the data series the box belongs to
.TP
string \fIlabel\fR (in)
The label along the x- or y-axis to which the data belong
.TP
list \fIvalues\fR (in)
List of raw values, the extent of the box and the whiskers will be
determined from this list.
.RE
.PP
For \fItimecharts\fR:
.TP
\fB$timechart\fR period \fItext\fR \fItime_begin\fR \fItime_end\fR \fIcolour\fR
Add a time period to the chart.
.RS
.TP
string \fItext\fR (in)
The text describing the period.
.TP
string \fItime_begin\fR (in)
Start time of the period.
.TP
string \fItime_end\fR (in)
Stop time of the period.
.TP
color \fIcolour\fR (in)
The colour of the bar (defaults to black).
.RE
.sp
.TP
\fB$timechart\fR milestone \fItext\fR \fItime\fR \fIcolour\fR
Add a \fImilestone\fR (represented as an point-down triangle) to the
chart.
.RS
.TP
string \fItext\fR (in)
The text describing the milestone.
.TP
string \fItime\fR (in)
Time at which the milestone must be positioned.
.TP
color \fIcolour\fR (in)
The colour of the triangle (defaults to black).
.RE
.sp
.TP
\fB$timechart\fR vertline \fItext\fR \fItime\fR
Add a vertical line (to indicate the start of the month for instance)
to the chart.
.RS
.TP
string \fItext\fR (in)
The text appearing at the top (an abbreviation of the
date/time for instance).
.TP
string \fItime\fR (in)
Time at which the line must be positioned.
.RE
.TP
\fB$timechart\fR hscroll \fIscrollbar\fR
Connect a horizontal scrollbar to the chart. See also the section on
scrolling.
.RS
.TP
widget \fIscrollbar\fR (in)
The horizontal scrollbar that is to be connected to the chart
.RE
.TP
\fB$timechart\fR vscroll \fIscrollbar\fR
Connect a vertical scrollbar to the chart. See also the section on
scrolling.
.RS
.TP
widget \fIscrollbar\fR (in)
The vertical scrollbar that is to be connected to the chart
.RE
.PP
.PP
For \fIGantt charts\fR:
.TP
\fB$ganttchart\fR task \fItext\fR \fItime_begin\fR \fItime_end\fR \fIcompleted\fR
Add a task with its period and level of completion to the chart. Returns
a list of canvas items that can be used for further manipulations, like
connecting two tasks.
.RS
.TP
string \fItext\fR (in)
The text describing the task.
.TP
string \fItime_begin\fR (in)
Start time of the task.
.TP
string \fItime_end\fR (in)
Stop time of the task.
.TP
float \fIcompleted\fR (in)
The percentage of the task that is completed.
.RE
.sp
.TP
\fB$ganttchart\fR milestone \fItext\fR \fItime\fR \fIcolour\fR
Add a \fImilestone\fR (represented as an point-down triangle) to the
chart.
.RS
.TP
string \fItext\fR (in)
The text describing the milestone.
.TP
string \fItime\fR (in)
Time at which the milestone must be positioned.
.TP
color \fIcolour\fR (in)
The colour of the triangle (defaults to black).
.RE
.sp
.TP
\fB$ganttchart\fR vertline \fItext\fR \fItime\fR
Add a vertical line (to indicate the start of the month for instance)
to the chart.
.RS
.TP
string \fItext\fR (in)
The text appearing at the top (an abbreviation of the
date/time for instance).
.TP
string \fItime\fR (in)
Time at which the line must be positioned.
.RE
.sp
.TP
\fB$ganttchart\fR connect \fIfrom\fR \fIto\fR
Add an arrow that connects the \fIfrom\fR task with the \fIto\fR task.
.RS
.TP
list \fIfrom\fR (in)
The list of items returned by the "task" command that represents the
task from which the arrow starts.
.TP
string \fItext\fR (in)
The text summarising the tasks
.TP
list \fIargs\fR (in)
One or more tasks (the lists returned by the "task" command). They are
shifted down to make room for the summary.
.TP
list \fIto\fR (in)
The list of items returned by the "task" command that represents the
task at which the arrow ends.
.RE
.sp
.TP
\fB$ganttchart\fR summary \fItext\fR \fIargs\fR
Add a summary item that spans all the tasks listed. The graphical
representation is a thick bar running from the leftmost task to the
rightmost.
.sp
Use this command before connecting the tasks, as the arrow would not be
shifted down!
.RS
.TP
string \fItext\fR (in)
The text summarising the tasks
.TP
list \fIargs\fR (in)
One or more tasks (the lists returned by the "task" command). They are
shifted down to make room for the summary.
.RE
.sp
.TP
\fB$ganttchart\fR color \fIkeyword\fR \fInewcolor\fR
Set the colour of a part of the Gantt chart. These colours hold for all
items of that type.
.RS
.TP
string \fIkeyword\fR (in)
The keyword indicates which part of the Gantt chart to change:
.RS
.IP \(bu
description - the colour of the descriptive text
................................................................................
.IP \(bu
summary - the colour for the summary text
.IP \(bu
summarybar - the colour for the bar for a summary
.RE
.TP
string \fInewcolor\fR (in)
The new colour for the chosen items.
.RE
.sp
.TP
\fB$ganttchart\fR font \fIkeyword\fR \fInewfont\fR
Set the font of a part of the Gantt chart. These fonts hold for all
items of that type.
.RS
.TP
string \fIkeyword\fR (in)
The keyword indicates which part of the Gantt chart to change:
.RS
.IP \(bu
description - the font used for descriptive text
................................................................................
.IP \(bu
summary - the font used for summaries
.IP \(bu
scale - the font used for the time scale
.RE
.TP
string \fInewfont\fR (in)
The new font for the chosen items.
.RE
.TP
\fB$ganttchart\fR hscroll \fIscrollbar\fR
Connect a horizontal scrollbar to the chart. See also the section on
scrolling.
.RS
.TP
widget \fIscrollbar\fR (in)
The horizontal scrollbar that is to be connected to the chart
.RE
.TP
\fB$ganttchart\fR vscroll \fIscrollbar\fR
Connect a vertical scrollbar to the chart. See also the section on
scrolling.
.RS
.TP
widget \fIscrollbar\fR (in)
The vertical scrollbar that is to be connected to the chart
.RE
.PP
.PP
For \fIisometric plots\fR (to be extended):
.TP
\fB$isoplot\fR plot rectangle \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR \fIcolour\fR
Plot the outlines of a rectangle.
.RS
.TP
float \fIx1\fR (in)
Minimum x coordinate of the rectangle to be drawn.
.TP
float \fIy1\fR (in)
Minimum y coordinate of the rectangle.
.TP
float \fIx2\fR (in)
Maximum x coordinate of the rectangle to be drawn.
.TP
float \fIy2\fR (in)
Maximum y coordinate of the rectangle.
.TP
color \fIcolour\fR (in)
The colour of the rectangle.
.RE
.sp
.TP
\fB$isoplot\fR plot filled-rectangle \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR \fIcolour\fR
Plot a rectangle filled with the given colour.
.RS
.TP
float \fIx1\fR (in)
Minimum x coordinate of the rectangle to be drawn.
.TP
float \fIy1\fR (in)
Minimum y coordinate of the rectangle.
.TP
float \fIx2\fR (in)
Maximum x coordinate of the rectangle to be drawn.
.TP
float \fIy2\fR (in)
Maximum y coordinate of the rectangle.
.TP
color \fIcolour\fR (in)
The colour of the rectangle.
.RE
.sp
.TP
\fB$isoplot\fR plot circle \fIxc\fR \fIyc\fR \fIradius\fR \fIcolour\fR
Plot the outline of a circle.
.RS
.TP
float \fIxc\fR (in)
X coordinate of the circle's centre.
.TP
float \fIyc\fR (in)
Y coordinate of the circle's centre.
.TP
color \fIcolour\fR (in)
The colour of the circle.
.RE
.sp
.TP
\fB$isoplot\fR plot filled-circle \fIxc\fR \fIyc\fR \fIradius\fR \fIcolour\fR
Plot a circle filled with the given colour.
.RS
.TP
float \fIxc\fR (in)
X coordinate of the circle's centre.
.TP
float \fIyc\fR (in)
Y coordinate of the circle's centre.
.TP
color \fIcolour\fR (in)
The colour of the circle.
.RE
.PP
.PP
For \fItables\fR you can use the following subcommands:
.TP
\fB$table\fR row \fIitems\fR
Draw a single row of items. The appearance of the items can be
controlled explicitly via the format command.
.RS
.TP
list \fIitems\fR (in)
List of text items to be drawn, one per column
.RE
.TP
\fB$table\fR separator
Draw a horizontal line to separate two rows
.TP
\fB$table\fR formatcommand \fIprocname\fR
Set the procedure that controls the formatting of items. By default
items are simply drawn as centered text.
.RS
.TP
string \fIprocname\fR (in)
Name of the procedure to be used. Its signature is:
.CS


proc procname {table widget row column value} {...}

.CE
.IP
Use the cellconfigure subcommand to set the attributes per cell.
.RE
.TP
\fB$table\fR cellconfigure \fIargs\fR
Set the attributes for the next cell(s) to be drawn.
.RS
.TP
list \fIargs\fR (in)
Key-value pairs: -background sets the background colour of the cells,
-cell sets the foreground colour, -font sets the text font, -anchor sets
the position of the text within the cell and -justify controls the
layout of multiline text.
.RE
.PP
There are a number of public procedures that may be useful in specific
situations: \fIPro memorie\fR.
.SH "COORDINATE TRANSFORMATIONS"
Besides the commands that deal with the plots and charts directly,
there are a number of commands that can be used to convert world
coordinates to pixels and vice versa.
These include:
.TP
\fB::Plotchart::viewPort\fR \fIw\fR \fIpxmin\fR \fIpymin\fR \fIpxmax\fR \fIpymax\fR
Set the viewport for window \fIw\fR. Should be used in cooperation
with \fB::Plotchart::worldCoordinates\fR.
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question.
.TP
float \fIpxmin\fR (in)
Left-most pixel coordinate.
.TP
float \fIpymin\fR (in)
Top-most pixel coordinate (remember: the vertical pixel coordinate
starts with 0 at the top!).
.TP
float \fIpxmax\fR (in)
Right-most pixel coordinate.
.TP
float \fIpymax\fR (in)
Bottom-most pixel coordinate.
.RE
.sp
.TP
\fB::Plotchart::worldCoordinates\fR \fIw\fR \fIxmin\fR \fIymin\fR \fIxmax\fR \fIymax\fR
Set the extreme world coordinates for window \fIw\fR. The world
coordinates need not be in ascending order (i.e. xmin can be larger
than xmax, so that a reversal of the x-axis is achieved).
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question.
.TP
float \fIxmin\fR (in)
X-coordinate to be mapped to left side of viewport.
.TP
float \fIymin\fR (in)
Y-coordinate to be mapped to bottom of viewport.
.TP
float \fIxmax\fR (in)
X-coordinate to be mapped to right side of viewport.
.TP
float \fIymax\fR (in)
Y-coordinate to be mapped to top side of viewport.
.RE
.sp
.TP
\fB::Plotchart::world3DCoordinates\fR \fIw\fR \fIxmin\fR \fIymin\fR \fIzmin\fR \fIxmax\fR \fIymax\fR \fIzmax\fR
Set the extreme three-dimensional world coordinates for window
\fIw\fR. The world coordinates need not be in ascending order (i.e. xmin
can be larger than xmax, so that a reversal of the x-axis is
achieved).
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question.
.TP
float \fIxmin\fR (in)
X-coordinate to be mapped to front side of the 3D viewport.
.TP
float \fIymin\fR (in)
Y-coordinate to be mapped to left side of the viewport.
.TP
float \fIzmin\fR (in)
Z-coordinate to be mapped to bottom of viewport.
.TP
float \fIxmax\fR (in)
X-coordinate to be mapped to back side of viewport.
.TP
float \fIymax\fR (in)
Y-coordinate to be mapped to right side of viewport.
.TP
float \fIzmax\fR (in)
Z-coordinate to be mapped to top side of viewport.
.RE
.sp
.TP
\fB::Plotchart::coordsToPixel\fR \fIw\fR \fIx\fR \fIy\fR
Return a list of pixel coordinates valid for the given window.
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question.
.TP
float \fIx\fR (in)
X-coordinate to be mapped.
.TP
float \fIy\fR (in)
Y-coordinate to be mapped.
.RE
.sp
.TP
\fB::Plotchart::coords3DToPixel\fR \fIw\fR \fIx\fR \fIy\fR \fIz\fR
Return a list of pixel coordinates valid for the given window.
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question.
.TP
float \fIx\fR (in)
X-coordinate to be mapped.
.TP
float \fIy\fR (in)
Y-coordinate to be mapped.
.TP
float \fIy\fR (in)
Z-coordinate to be mapped.
.RE
.sp
.TP
\fB::Plotchart::polarCoordinates\fR \fIw\fR \fIradmax\fR
Set the extreme polar coordinates for window \fIw\fR. The angle always
runs from 0 to 360 degrees and the radius starts at 0. Hence you only
need to give the maximum radius.
\fINote:\fR If the viewport is not square, this procedure will not
adjust the extremes, so that would result in an elliptical plot. The
creation routine for a polar plot always determines a square viewport.
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question.
.TP
float \fIradmax\fR (in)
Maximum radius.
.RE
.sp
.TP
\fB::Plotchart::polarToPixel\fR \fIw\fR \fIrad\fR \fIphi\fR
Wrapper for a call to \fB::Plotchart::coordsToPixel\fR, which assumes
the world coordinates and viewport are set appropriately. Converts
polar coordinates to pixel coordinates.
\fINote:\fR To be useful it should be accompanied by a matching
\fB::Plotchart::worldCoordinates\fR procedure. This is automatically
taken care of in the creation routine for polar plots.
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question.
.TP
float \fIrad\fR (in)
Radius of the point.
.TP
float \fIphi\fR (in)
Angle to the positive x-axis.
.RE
.sp
.TP
\fB::Plotchart::pixelToCoords\fR \fIw\fR \fIx\fR \fIy\fR
Return a list of world coordinates valid for the given window.
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question.
.TP
float \fIx\fR (in)
X-pixel to be mapped.
.TP
float \fIy\fR (in)
Y-pixel to be mapped.
.RE
.TP
\fB::Plotchart::pixelToIndex\fR \fIw\fR \fIx\fR \fIy\fR
Return the index of the pie segment containing the pixel coordinates
(x,y)
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question,
holding a piechart.
.TP
float \fIx\fR (in)
X-pixel to be mapped.
.TP
float \fIy\fR (in)
Y-pixel to be mapped.
.RE
.PP
.PP
Furthermore there is a routine to determine "pretty" numbers for use
with an axis:
.TP
\fB::Plotchart::determineScale\fR \fIxmin\fR \fIxmax\fR \fIinverted\fR
Determine "pretty" numbers from the given range and return a list
containing the minimum, maximum and stepsize that can be used for a
(linear) axis.
.RS
.TP
float \fIxmin\fR (in)
Rough minimum value for the scaling
.TP
float \fIxmax\fR (in)
Rough maximum value for the scaling.
.TP
boolean \fIinverted\fR (in)
Optional argument: if 1, then the returned list produces an
inverted axis. Defaults to 0 (the axis will be from minimum to maximum)
.RE
.TP
\fB::Plotchart::determineScaleFromList\fR \fIvalues\fR \fIinverted\fR
Determine "pretty" numbers from the given list of values and return a list
containing the minimum, maximum and stepsize that can be used for a
(linear) axis.
.RS
.TP
float \fIvalues\fR (in)
List of values that will be examined. May contain missing values (empty strings)
.TP
boolean \fIinverted\fR (in)
Optional argument: if 1, then the returned list produces an
inverted axis. Defaults to 0 (the axis will be from minimum to maximum)
.RE
.PP
.SH "MISSING VALUES"
Often data that need to be plotted contain gaps - in a series of
measurement data, they can occur because the equipment failed, a sample
was not collected correctly or for many other reasons. The
\fIPlotchart\fR handles these gaps by assuming that one or both
coordinates of such data points are an empty string:
.CS


    #
    # Create the plot with its x- and y-axes
    #
    set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]

    foreach {x y} {0.0 32.0 10.0 {} 25.0 60.0 78.0 11.0 } {
        $s plot series1 $x $y
    }

.CE
The effect varies according to the type of plot:
.IP \(bu
For xy-plots, radial plots and strip charts the missing data point
causes a gap in the line through the points.
.IP \(bu
For barchats, missing values are treated as if a value of zero was
given.
.IP \(bu
For time charts and Gantt charts missing values cause errors - there is
no use for them there.
.PP
.SH "OTHER OUTPUT FORMATS"
Besides output to the canvas on screen, the module is capable, via
\fBcanvas postscript\fR, of producing PostScript files. One may wonder
whether it is possible to extend this set of output formats and the
answer is "yes". This section tries to sum up the aspects of using this
module for another sort of output.
.PP
One way you can create output files in a different format, is by
examining the contents of the canvas after everything has been drawn and
render that contents in the right form. This is probably the easiest
way, as it involves nothing more than the re-creation of all the
elements in the plot that are already there.
.PP
The drawback of that method is that you need to have a display, which is
not always the case if you run a CGI server or something like that.
.PP
An alternative is to emulate the canvas command. For this to work, you
need to know which canvas subcommands are used and what for. Obviously,
the \fIcreate\fR subcommand is used to create the lines, texts and
other items. But also the \fIraise\fR and \fIlower\fR subcommands are
used, because with these the module can influence the drawing order -
important to simulate a clipping rectangle around the axes. (The routine
DrawMask is responsible for this - if the output format supports proper
clipping areas, then a redefinition of this routine might just solve
this).
.PP
Furthermore, the module uses the \fIcget\fR subcommand to find out the
sizes of the canvas. A more mundane aspect of this is that the module
currently assumes that the text is 14 pixels high and that 80 pixels in
width suffice for the axis' labels. No "hook" is provided to customise
this.
.PP
In summary:
.IP \(bu
Emulate the \fIcreate\fR subcommand to create all the items in the
correct format
.IP \(bu
Emulate the \fIcget\fR subcommand for the options -width and -height to
allow the correct calculation of the rectangle's position and size
.IP \(bu
Solve the problem of \fIraising\fR and \fIlowering\fR the items so
that they are properly clipped, for instance by redefining the
routine DrawMask.
.IP \(bu
Take care of the currently fixed text size properties
.PP
.SH "SPECIAL EFFECTS"
As an example of some special effects you can achieve, here is the
code for a plot where the area below the data line varies in colour:
.CS


canvas .c  -background white -width 400 -height 200
pack .c -fill both

set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]

$s background gradient green top-down

$s dataconfig series1 -filled up -fillcolour white

$s plot series1  0.0 20.0
$s plot series1 10.0 20.0
$s plot series1 30.0 50.0
$s plot series1 35.0 45.0
$s plot series1 45.0 25.0
$s plot series1 75.0 55.0
$s plot series1 100.0 55.0

$s plaintext 30.0 60.0 "Peak" south

.CE
The trick is to fill the background with a colour that changes from
green at the top to white at the bottom. Then the area above the data
line is filled with a white polygon. Thus the green shading varies with
the height of the line.
.SH "ROOM FOR IMPROVEMENT"
In this version there are a lot of things that still need to
be implemented:
.IP \(bu
More robust handling of incorrect calls (right now the procedures may
fail when called incorrectly):
.RS
.IP \(bu
The axis drawing routines can not handle inverse axes right now.
.IP \(bu
If the user provides an invalid date/time string, the routines simply
throw an error.
.RE
.PP
.SH RESIZING
\fBPlotchart\fR has not been designed to create plots and charts
that keep track of the data that are put in. This means that if an
application needs to allow the user to resize the window holding the
plot or chart, it must take care to redraw the complete plot.
.PP
The code below is a simple example of how to do that:
.CS


package require Plotchart

grid [canvas .c -background white] -sticky news
grid columnconfigure . 0 -weight 1
grid rowconfigure . 0 -weight 1

bind .c <Configure> {doResize}

proc doPlot {} {
    #
    # Clean up the contents (see also the note below!)
    #
    .c delete all

    #
    # (Re)draw the bar chart
    #
    set p [::Plotchart::createBarchart .c {x y z} {0 100 10} 3]
    $p plot R {10 30 40} red
    $p plot G {30 40 60} green
}

proc doResize {} {
    global redo

    #
    # To avoid redrawing the plot many times during resizing,
    # cancel the callback, until the last one is left.
    #
    if { [info exists redo] } {
        after cancel $redo
    }

    set redo [after 50 doPlot]
}
.CE
\fIPlease note:\fR
The code above will work fine for barcharts and many other types of
plots, but as \fBPlotchart\fR keeps some private information for
xy plots, more is needed in these cases. This actually requires a
command "destroyPlot" to take care of such details. A next version
of \fBPlotchart\fR may have that.
.PP
Alternatively, you can use the \fBxyplot\fR package which is built
on top of Plotchart. This package supports zooming in and zooming out,
as well as resizing the plot as a whole. Here is a small demonstration
program:
.CS


# xyplot_demo.tcl --
#     Demonstration of the xyplot package
#

package require xyplot

set xydata1 {}
set xydata2 {}
set xydata3 {}
set xydata4 {}
for { set i 0 } { $i < 1024 } { incr i } {
    lappend xydata1 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2))}]
    lappend xydata2 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6))}]
    lappend xydata3 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6) + 0.0625 * sin($i/256.0*3.1415*10))}]
    lappend xydata4 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6) + 0.0625 * sin($i/256.0*3.1415*10) + 0.015625 * sin($i/256.0*3.1415*14))}]
}

set xyp [xyplot .xyp -xformat "%5.0f" -yformat "%5.0f" -title "XY plot testing" -background gray90]
pack $xyp -fill both -expand true

set s1 [$xyp add_data sf1 $xydata1 -legend "Serie 1 data" -color red]
set s2 [$xyp add_data sf2 $xydata2 -legend "Serie 2 data" -color green]
set s3 [$xyp add_data sf3 $xydata3 -legend "Serie 3 data" -color blue]
set s4 [$xyp add_data sf4 $xydata4 -legend "Serie 4 data" -color orange]

set xyp2 [xyplot .xyp2 -xticks 8 -yticks 4 -yformat %.2f -xformat %.0f]
pack $xyp2 -fill both -expand true

set s1 [$xyp2 add_data sf1 $xydata1]
set s2 [$xyp2 add_data sf2 $xydata2]
set s3 [$xyp2 add_data sf3 $xydata3]
set s4 [$xyp2 add_data sf4 $xydata4]

.CE
Zooming in is done by selecting a rectangle with the left mouse button
pressed. Zooming out is done by pressing the right mouse button. If you
resize the window, the canvases inside are resized too. If you zoom in,
you can scroll the plot via the scrollbars that are automatically
attached.
.SH "ZOOMING IN"
As the Plotchart package does not keep track of the data itself,
rescaling an existing plot - for instance when zooming in - would have
to be done by redefining the plot and redrawing the data. However, the
canvas widget offers a way out by scaling and moving items, so that
zooming in becomes a bit simpler.
.PP
Whether zooming is indeed useful, depends on the type of plot. Currently
it is defined for XY-plots only. The method is called "rescale" and
simply redraws the axes and scales and moves the data items so that they
conform to the new axes. The drawback is that any symbols are scaled by
the same amount. The rescale method works best for plots that only have
lines, not symbols.
.PP
The method works very simply:
.CS


   $p rescale {newxmin newxmax newxstep} {newymin newymax newystep}

.CE
.SH "CONFIGURATION OPTIONS"
The commands \fBplotconfig\fR and \fBplotstyle\fR can be used to set all
manner of options. The syntax is:
.TP
\fB::Plotchart::plotconfig\fR \fIcharttype\fR \fIcomponent\fR \fIproperty\fR \fIvalue\fR
Set a new value for the property of a component in a particular chart or
plot type or query its current value. Changed properties only have effect for
the consecutive plots, not for the ones already created. Each argument is optional.
.sp
\fINote:\fR The \fBplotstyle\fR command offers a more
flexible way to control the configuration options.
.RS
.TP
string \fIcharttype\fR (in)
The type of chart or plot (see the configuration type that is mentioned
for each create command). If not given or empty, a list of chart types
is returned. If it is given, the properties for that particular type are
used.
.TP
string \fIcomponent\fR (in)
The component of the plot/chart: leftaxis, rightaxis, background, margin
and so on. If not given or empty, a list of components is returned. If
it is given, the properties for that particular component will be set
for that particular type of chart.
.TP
string \fIproperty\fR (in)
The property of the component of the plot/chart: textcolor, thickness of
the axis line, etc. If not given or empty, a list of properties is returned. If
it is given, that particular property for that particular component
will be set for that particular type of chart.
.TP
string \fIvalue\fR (in)
The new value for the property. If empty, the current value is returned.
If the value is "default", the default value will be restored.
.sp
Note, that in some cases an empty value is useful. Use "none" in this
case - it can be useful for colours and for formats.
.RE
.TP
\fB::Plotchart::plotstyle\fR \fIsubcmd\fR \fIstyle\fR \fIargs\fR
Manipulate the \fIstyle\fR in which subsequent plots will be drawn. The
default style is "default", but you can define and load any number of
other styles.
.RS
.TP
string \fIsubcmd\fR (in)
The subcommand to be executed:
.RS
.IP \(bu
\fIconfigure\fR - this subcommand allows you to set the options per chart type.
It takes the same options as the \fBplotconfig\fR command.
.IP \(bu
\fIcurrent\fR - return the current style
.IP \(bu
\fIload\fR - make the given style the active style for subsequent plots and charts
.IP \(bu
\fInames\fR - return the list of currently defined styles
.RE
................................................................................
.PP
Below is a detailed list of the components and properties:
.IP \(bu
Axes come in a wide variety:
.RS
.IP \(bu
leftaxis, rightaxis, topaxis, bottomaxis for the plots with a
rectangular shape.
.IP \(bu
xaxis, yaxis and zaxis are used for the 3D plots
.IP \(bu
axis, this represents the radial and tangential axes of a polar plot
.RE
.IP
All axes have the following properties:
.RS
.IP \(bu
color - the colour of the line and the tickmarks
.IP \(bu
thickness - the width of the line of the axis itself, not the tickmarks
.IP \(bu
ticklength - the length of the tickmarks in pixels. A positive value is
outward, a negative value is inward.
.IP \(bu
font - the font for the labels and the text at the axis
.IP \(bu
format - the format for rendering the (numerical) labels. For the time
axis it is the format for a date and time.
.IP \(bu
textcolor - the colour for the labels and the text.
.IP \(bu
labeloffset - space (in pixels) between the tickmark and the actual label
.IP \(bu
minorticks - number of minor tickmarks between the major tickmarks
.IP \(bu
shownumbers - show the numbers/labels or not.
.IP \(bu
showaxle - show the axis line or not.
.RE
.IP \(bu
The \fImargin\fR is important for the layout. Currently only the
rectangular plots allow the margins to be set: left, right, top and bottom.
The values are in pixels.
.IP \(bu
The \fItext\fR component is meant for any text appearing via the
plaintext subcommand. The properties are: textcolor, font and anchor
(positioning of the text relative to the given coordinates).
.IP \(bu
The \fIbackground\fR has two properties: outercolor, the colour outside
of the actual plot, and innercolor, the colour inside the plot. (Note:
only "outercolor" has now been implemented).
.IP \(bu
The \fImask\fR has one property only: draw. If set to 1, the default, white rectangles
are drawn to mimick the effects of clipping - excess data are made invisible this way.
Otherwise these rectangles are not drawn. This is useful to control
the layout more tightly, for instance with multiple plots in one canvas.
.IP \(bu
The \fItitle\fR component has the same properties as the \fItext\fR component
(but it is independent of that component). It also has a \fIbackground\fR property:
If not set (or set to the empty string) this is the same as the outercolor property
of the \fIbackground\fR component, otherwise it is a separate colour.
.IP \(bu
The \fIlegend\fR has three properties: background, border and position.
See the legend subcommand for the meaning.
.IP \(bu
The \fIbar\fR components is used for all barchart-like plots and has
three properties: \fIbarwidth\fR (relative width of the bars in
relation to the items along the axis), \fIinnermargin\fR (the
relative width of the gaps between bars or groups of bars) and
the \fIoutline\fR colour.
.IP \(bu
The \fIlabels\fR component is used to describe the appearance of the
labels of piecharts and "spiral" piecharts. The properties are:
.RS
.IP \(bu
textcolor - colour of the label text
.IP \(bu
font - font to be used for the label text
.IP \(bu
placement - \fIout\fR of the circle or \fIin\fR the circle
................................................................................
.IP \(bu
sorted - the data are sorted in ascending order first
.IP \(bu
shownumbers - the labels are combined with the numbers according to the
format
.IP \(bu
format - the format to be used (defaults to: "%s (%g)")
if the numbers are to shown. The format command gets the label first,
then the number)
.IP \(bu
formatright - if given, the format to be used for labels and numbers
appearing to the right of the pie. The format command gets the
number first, then the label. (Defaults to "")
.RE
.IP \(bu
The \fIslice\fR component has properties to control the appearance of
the sections in the pie diagram:
.RS
.IP \(bu
outline - the colour of the line around the slices (default: black)
.IP \(bu
outlinewidth - width of the line around the slices (default: 1 pixel)
.IP \(bu
startangle - the angle w.r.t. positive x-axis where the first slice
starts
.IP \(bu
direction - the direction in which to draw the slices (default: +, that
is clockwise)
.RE
.IP \(bu
The table charts use the general components \fItitle\fR and \fImargin\fR
and further more the specific components \fIheader\fR, \fIoddrow\fR,
\fIevenrow\fR, \fIcell\fR and \fIframe\fR:
.RS
.IP \(bu
\fIheader\fR, \fIoddrow\fR and \fIevenrow\fR have the properties:
\fIbackground\fR, \fIfont\fR, \fIcolor\fR, \fIheight\fR and
\fIanchor\fR with obvious meanings.
.IP \(bu
The \fIcell\fR component defines in addition \fIleftspace\fR,
\fIrightspace\fR and \fItopspace\fR for fine-grained control of the spacing
inside the cell. These are not set via the \fIcellconfigure\fR
subcommand however.
.IP \(bu
Finally the \fIframe\fR component uses \fIcolor\fR, \fIouterwidth\fR
(for the width of the line surrounding the whole table) and
\fIinnerwidth\fR (for the width of lines separating columns and rows).
.RE
.PP
See the examples in plotdemos7.tcl for its use.
.SH "SCROLLING FOR TIMECHARTS AND GANTT CHARTS"
For two types of plots automatic scrolling management has been
implemented: timecharts and Gantt charts. The subcommands \fIhscroll\fR
and \fIvscroll\fR associate (existing) scrollbars to the plot, in much
the same way as for text and canvas widgets.
.PP
Once the association is made, the scrollbars are automatically
updated if:
.IP \(bu
You add an item with a period wider than the current one.
.IP \(bu
You add a vertical line for a time beyond the current bounds.
.IP \(bu
You add an extra item beyond the number that was used to create the
chart.
.PP
For instance:
.CS


package require Plotchart

canvas .c -width 400 -height 200
scrollbar .y -orient vertical
scrollbar .x -orient horizontal

grid .c .y -sticky news
grid .x    -sticky news

source plotchart.tcl

set s [::Plotchart::createTimechart .c "1 january 2004"  "31 december 2004" 4]

$s period "Spring" "1 march 2004" "1 june 2004" green
$s period "Summer" "1 june 2004" "1 september 2004" yellow
$s vertline "1 jan" "1 january 2004"
$s vertline "1 apr" "1 april 2004"
$s vertline "1 jul" "1 july 2004"
$s vertline "1 oct" "1 october 2004"
................................................................................
$s milestone "Longest day 2" "21 july 2004"
$s milestone "Longest day 3" "21 july 2004"
$s milestone "Longest day 4" "21 july 2004"
$s milestone "Longest day 5" "21 july 2004"
$s milestone "Longest day 6" "21 july 2004"
$s title "Seasons (northern hemisphere)"

$s vscroll .y
$s hscroll .x

.CE
The original extent of the chart is from 1 january 2004 to 31 december
2004. But because of the addition of vertical lines in 2005 and
more items than was specified at the creation of the chart, both the
horizontal and the vertical scrollbar will be enabled.
.SH "SPECIALISED PLOTS"
Most of the plot and chart types described above have a fairly general use
and you simply prepares the data to be plotted yourself. This section describes
several plot types that are more specialised, in the sense that they have specific
purposes and you pass raw data that are then processed in the plotting routines.
.PP
Currently there are the following types:
.IP \(bu
Target diagrams are used to assess the capacity of numerical models to reproduce measurement
data. They are described in detail in:
.CS


Jason K. Joliff et al.
    Summary diagrams for coupled hydrodynamic-ecosystem model skill assessment
    Journal of Marine Systems 76 (2009) 64-82
    DOI: 10.1016/j.jmarsys.2008.05.014

.CE
.IP \(bu
Performance profiles are used for comparing the performance of numerical methods or
implementations thereof with each other. For more information:
.CS


Desmond Higham and Nicholas Higham
    Matlab Guide
    SIAM, 2005, Philadephia

.CE
.PP
Most of the general methods for XY-plots work for these plots as well, but their
creation and the methods to plot the data are very specific.
.TP
\fB::Plotchart::createTargetDiagram\fR \fIw\fR \fIlimits\fR \fIscale\fR
Create a new target diagram with circles indicating specific limits. The x-axis represents the
unbiased "root-mean-square difference" (typically varying between -1 and 1) and the y-axis
represents the normalised bias.
.sp
Data points closer to the origin represent better results than data points further away.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
list \fIlimits\fR (in)
List of radii for the circles that represent the limits (for instance: 0.5 and 0.7)
.TP
double \fIscale\fR (in)
Scale for the axes - defaults to 1, but if the model results are a poor fit, then
that may be too small a value. Both axes are scaled in the same way.
.RE
.sp
.TP
\fB$target\fR plot \fIseries\fR \fIxvalues\fR \fIyvalues\fR
The plot method takes two series of data of the same length, the first one
representing the model results, the second one represent the measurements
or, more general, the data that need to be reproduced.
.RS
.TP
string \fIseries\fR (in)
Name of the series (it will be plotted as a symbol that is configured via the
\fI$target dataconfig\fR command (see the XY-plot equivalent for an explanation)
.TP
list \fIxvalues\fR (in)
................................................................................
.TP
list \fIyvalues\fR (in)
List of measured values (missing values are represented as empty strings; only if
both the x and the y values are given, is the pair used in the computations)
.RE
.TP
\fB::Plotchart::createPerformanceProfile\fR \fIw\fR \fImax\fR
Create a diagram to show the performance of various numerical methods (or solvers). The idea is
to first run these methods on a set of problems and measure their performance. The smaller the
number the better. Then these methods are compared via a so-called performance profile:
the data are scaled and ordered, such that the best method ends up highest.
.sp
Because of the nature of the plot all data must be given at once.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot.
.TP
float \fImax\fR (in)
Maximum value for the x-axis (the x-axis is the scaled performance of the series).
.RE
.TP
\fB$performance\fR plot \fIseries_and_data_pairs\fR
Plot the data for each given method. The data are identified by the series name and the
appearance is controlled via prior dataconfig subcommand.
.RS
.TP
list \fIseries_and_data_pairs\fR (in)
List of series names and data. All data must be given at once.
.RE
.PP
The command \fIplotmethod\fR can be used to add new methods for a particular
plot or chart type. It is intended to help you develop specialised graphical displays.
.TP
\fB::Plotchart::plotmethod\fR \fIcharttype\fR \fImethodname\fR \fIplotproc\fR
Adds a new method for the given plot or chart type. The method is implemented by the
command or procedure given in the plotproc argument. The procedure will be called with
two extra arguments, the name of the created plot and the canvas widget that contains
(see the example below).
.RS
.TP
string \fIcharttype\fR (in)
The type of plot or chart that the new method should be added to.
.TP
string \fImethodname\fR (in)
Name of the method to be used.
.TP
string \fIplotproc\fR (in)
Name of the command or procedure that implements the method.
.RE
.PP
.PP
Here is a trivial example of how to use this:
.CS


................................................................................
proc doodle {p w x y} {
    $p plaintext $x $y "DOODLE"
}
::Plotchart::plotmethod xyplot doodle doodle

#
# Use it
pack [canvas .c]

set p [::Plotchart::createXYPlot .c {0 100 10} {0 20 5}]

$p doodle 40 10

.CE
.SH "TABLE CHARTS"
To show what you can do with table charts, here is a simple example that
plots a number of random data. The colours depend on the range that the
data belong to. For this the procedure \fIsetColor\fR is used.
.CS


package require Plotchart

pack [canvas .c -bg white -height 300] -fill both -expand yes

::Plotchart::plotconfig table frame outerwidth 3
::Plotchart::plotconfig table frame color red

set t [::Plotchart::createTableChart .c {"Column 1" "Column 2" "Column 3"} 80]


proc setColor {table widget row col value} {
    $table cellconfigure -background white -color black
    if { $value < 2.0 } {
        $table cellconfigure -background red -color white
    }
    if { $value > 6.0 } {
        $table cellconfigure -background green
    }

    return [format "%6.3f" $value]
}

# Command must already exist ...
$t formatcommand setColor

$t title "Demonstration of table charts"
$t separator

for {set i 0} {$i < 9} {incr i} {
    set row {}

    for {set j 0} {$j < 3} {incr j} {
        lappend row [expr {10.0 * rand()}]
    }

    if { $i == 3 } {
        $t separator
    }

    $t row $row
}
.CE
.SH "CONTROL DISPLAYS"
TODO
.SH "ARRANGING MULTIPLE PLOTS IN A CANVAS"
The command \fIplotpack\fR allows you to copy the contents of a plot
into another canvas widget. This canvas widget does not act as a
composite plot, but it can be saved as a PostScript file for instance:
Note: the command simply takes a snapshot of the plots/charts as they
are at that moment.
.TP
\fB::Plotchart::plotpack\fR \fIw\fR \fIdir\fR \fIargs\fR
Copy the contents of the plots/charts into another widget, in a manner
similar to the \fIpack\fR geometry manager.
.RS
.TP
widget \fIw\fR (in)
The name of the canvas widget to copy the plots/charts into
.TP
string \fIdir\fR (in)
The direction of the arrangement - top, left, bottom or right
.TP
list \fIargs\fR (in)
List of plots/charts to be copied.
.RE
.PP
For example:
.CS


    set p1 [createXYPlot ...]
    set p2 [createBarchart ...]

    ... fill the plots ...

    toplevel .t
    pack [canvas .t.c2 -width ...]

    #
    # Copy the two plots above each other in the new canvas
    #
    plotpack .t.c2 top $p1 $p2

.CE
A different method is to use the \fI-box\fR and \fI-axesbox\fR options
when creating the plot. These control the area in the canvas where the
plot or chart will be drawn.
.PP
The \fI-box\fR option takes as its value a list of four numbers:
.IP \(bu
X-coordinate of the upper-left corner of the area that will contain the
plot or chart (simply a canvas coordinate)
.IP \(bu
Y-coordinate of the upper-left corner
.IP \(bu
Width of the area
.IP \(bu
Height of the area
.PP
Specifying the width and height makes it easier to reposition the area
with respect to other plots.
.PP
The \fI-axesbox\fR option is meant to make aligning the axes of a
plot with those of other plots easier. The option takes a list of
six arguments:
.IP \(bu
Identification of the plot with respect to which it should be
positioned (the command returned by the creation command).
.IP \(bu
The anchor position that should be used (n, nw, ...)
.IP \(bu
X-coordinate of the upper-left corner of the area that will contain the
plot or chart. This coordinates is taken relative to the
\fIanchor position\fR
.IP \(bu
Y-coordinate of the upper-left corner
.IP \(bu
Width of the axis area
.IP \(bu
Height of the axis area
.PP
With this option the area the axes occupy is first determined and the
complete area is derived from the margins.
.PP
For example:
.CS


    set p2 [::Plotchart::createXYPlot .c {0 10 1} {-5 5 2.5} -axesbox [list $p1 ne 0 0 200 200]]

.CE
will create a second plot whose left axis coincides with the right axis
of plot "\\$p1" and the top of the axis is at the same heigt as well -
because the axes are positioned at a point 0 pixels to the left and 0
pixels below the north-east corner.
.SH "INTERACTIVE USE"
\fIPlotchart\fR has several features for interactive use (cf. \fBNOTES ON TAGS\fR):
.IP \(bu
The legend can be moved around by pressing mouse button 1 in the legend's box and
keeping it down.
.IP \(bu
You can use the \fIbindplot\fR and \fIbindlast\fR commands to
define actions that are to be taken when the user clicks on an element of the plot or chart.
(see below, see also the sample code in plotdemos12.tcl)
.IP \(bu
\fIPiecharts\fR can show an "exploded" segment that you can select with mouse button 1.
.PP
If you require different forms of interaction, not covered by \fIPlotchart\fR itself,
you can use the tags on the various canvas elements to define other bindings.
.PP
The \fIbindplot\fR and \fIbindlast\fR are defined as follows:
.TP
\fB$anyplot\fR bindplot \fIevent\fR \fIcommand\fR \fIargs\fR
Register a command that will be run whenever the given event occurs in the plot.
.RS
.TP
string \fIevent\fR
The event that you want to bind the command to
.TP
string \fIcommand\fR
Name of the command/procedure that you want to run. The following arguments
are prefixed: the x- and y-coordinates of the point in the plot (the world coordinates!),
so that the procedure has the signature:
.CS


    cmd $xworld $yworld $string1 $string2 $string3

................................................................................
.CE
.IP
assuming the argument "command" is: {cmd A B C}
.RE
.TP
\fB$anyplot\fR bindlast \fIseries\fR \fIevent\fR \fIcommand\fR
Register a command that will be run when the event occurs within the neighbourhood of
the last point added to the given series. (You can use directly after inserting
a data point. All such commands will remain active).
.RS
.TP
string \fIevent\fR
The event that you want to bind the command to
.TP
list \fIcommand\fR
Name of the command/procedure that you want to run. The following arguments
are prefixed: the x- and y-coordinates of the point in the plot (the world coordinates!),
so that the procedure has the signature:
.CS


    cmd $xworld $yworld $string1 $string2 $string3

.CE
.IP
assuming the argument "command" is: {cmd A B C}
.RE
.PP
Here is an example - show the values of the data points in an annotation
(from the sample code in plotdemos12.tcl):
.CS


#
# Procedure for showing an annotation
#
proc showAnnotation {xcoord ycoord plot w} {

    $plot balloon $xcoord $ycoord "Data point: [format "%.3f, %.3f" $xcoord $ycoord]" north

    after 2000 [list removeAnnotation $w]
}

#
# Procedure for erase an annotation
#
................................................................................
    $w delete BalloonText
    $w delete BalloonFrame
}

#
# Create a simple plot and a label
#
pack [canvas .c -bg white] [label .l -textvariable coords]

set p [::Plotchart::createXYPlot .c {0 1000 200} {0 10 1}]

$p dataconfig series1 -type both -symbol cross

foreach x {1 2 5 10 20 50 100 200 500 1000} {
    $p plot series1 $x [expr {log($x)}]

    #
................................................................................
    $p bindlast series1 <Enter> [list showAnnotation $p %W]
}

.CE
.SH "NOTES ON TAGS"
The implementation of \fIPlotchart\fR relies heavily on the canvas's
ability to identify graphical objects by tags and to change the drawing order of
the objects. This section documents the tags that are used.
.PP
(\fINote:\fR the tags are not always used consistently - see the notes appearing with
the various tags. This section describes the current state.)
.PP
\fIGeneral graphical objects:\fR
.IP \(bu
\fImask\fR - Used to manipulate the opaque rectangles that ensure data outside
the viewport are not shown.
.IP \(bu
\fItopmask, horizmask, vertmask\fR - specialised tags, used for scrollable plots.
.IP \(bu
\fItitle\fR - Used for title strings.
.IP \(bu
\fIBalloonText, BalloonFrame\fR - Used to manipulate balloon text.
.IP \(bu
\fIPlainText\fR - Used to manipulate ordinary text without any decoration.
.IP \(bu
\fIbackground\fR - Tag used for gradient and image backgrounds (and for gradient-filled bars).
.IP \(bu
\fIxaxis, yaxis\fR - Tags used for all objects related to horizontal or vertical axes.
(also: both for numerical axes and axes with labels as in barcharts).
Note, however, that the \fItext\fR along the axes has no particular tag.
.IP \(bu
\fIraxis\fR - Tag used for all objects related to a \fIright\fR axis.
.IP \(bu
\fItaxis\fR - Tag used for all objects related to a \fItime\fR axis.
.IP \(bu
\fIaxis3d\fR - Tag used for 3D axes
.IP \(bu
\fIxtickline, ytickline\fR - Tags used for ticklines.
.IP \(bu
\fIlegend, legengb, legendobj\fR - Tags used for the legend. The latter is used to manipulate
the legend as a whole.
.IP \(bu
\fIlegend_series\fR - Tag used to control the appearance of the legend entry ("series" should
be replaced by the series name).
.IP \(bu
\fIobject\fR - used as standard tag for all objects drawn with the \fB::Plotchart::drawobject\fR
procedure. Tags given at object creation time are added to this tag.
.PP
\fIXY-plots (all types of axes):\fR
.IP \(bu
\fIdata\fR - The general tag to identify graphical objects associated with data.
\fIdata_seriesname\fR - The tag specific to a data series ("seriesname" should be replaced).
\fIband\fR - The horizontal or vertical band drawn with the xband otr yband subcommands have this tag
by the actual name).
\fIxtext\fR - The text labelling the xaxis.
\fIytext\fR - The text labelling hte yaxis horizontically.
\fIvtext\fR - The text labelling the yaxis vertically.
.PP
Items such as labelled dots only have the "data" tag.
.PP
\fIPiecharts and spiral pies:\fR
.IP \(bu
\fIsegment_segmentnumber\fR - The tag identifying the segment, the string "segmentnumber" should
be replaced by the actual number. This tag is used to explode the segments.
.PP
\fIBarcharts:\fR
.PP
Barcharts use the same tags as xy-plots (but for gradient-filled bars the data_seriesname is not used).
.PP
\fIHistograms and isometric plots:\fR
.PP
Currently the only tag used is "data".
.PP
\fITime-charts:\fR
.PP
As these plots are scrollable, several tags are used specific to the scrolling:
vertscroll, horizscroll, below, lowest, above, timeline, tline.
Each item also has a tag of the form "item_number",
where "number" is to be replaced by the actual sequence number of the item.
.PP
\fIGantt charts:\fR
.PP
In addition to the tags described for the time-charts, the following tags are used:
description, completed, summary and summarybar.
.PP
\fIRadial charts and polar plots:\fR
.PP
Currently the radial lines indicating the grid have no tags. The graphical objects associated with
data only have the "data" tag.
.PP
\fIWindroses:\fR
.PP
Only the tag \fIdata_number\fR is currently used ("number" should be replaced by the
sequence number of the data, starting at 0.
.PP
\fIContour and isoline plots:\fR
.PP
No tags are used.
.PP
\fI3D plots and 3D ribbon plots:\fR
.PP
No tags are used for the data objects, only for the axes.
.PP
\fICharts decorated with 3D effects:\fR
.PP
The following tags are used to identify various types of graphical objects: platform, background, d, u,
ticklines.
.PP
The text associated with the bars has no tags. The ribbon lines and areas have no tags either.
.PP
\fITables:\fR
.PP
Tags used are: frame, cellbg and celltext
\fIIn addition:\fR
To implement multiple plots and charts in a single canvas, all items
also get as a tag the plot/chart they belong to. This enables Plotchart
to manipulate only those items.
.SH "TODO - SOME PRIVATE NOTES"
I have the following wishlist:
.IP \(bu
Isometric plots - allow new items to be implemented easily.
.IP \(bu
A general 3D viewer - emphasis on geometry, not a ray-tracer.
.IP \(bu
Several improvements for boxplots:
.RS
.IP \(bu
Height of the box scales with the logarithm of the number of points
.IP \(bu
Marker line to indicate a "current" value
................................................................................
Box drawn from quantiles
.RE
.PP
.SH KEYWORDS
3D bars, 3D surfaces, bar charts, charts, coordinate transformations, coordinates, graphical presentation, isometric plots, pie charts, plotting, polar plots, strip charts, tables, time charts, xy-plots
.SH COPYRIGHT
.nf
Copyright (c) 2011 Arjen Markus <arjenmarkus@users.sourceforge.net>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/plotchart/plotchart\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2011 Arjen Markus <arjenmarkus@users\&.sourceforge\&.net>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "Plotchart" n 2\&.0\&.2 tklib "Plotchart"
.BS
.SH NAME
Plotchart \- Simple plotting and charting package
.SH SYNOPSIS
package require \fBTcl  ?8\&.5?\fR
.sp
package require \fBTk  ?8\&.5?\fR
.sp
package require \fBPlotchart  ?2\&.1\&.0?\fR
.sp
\fB::Plotchart::createXYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIargs\fR
.sp
\fB::Plotchart::createStripchart\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
.sp
\fB::Plotchart::createTXPlot\fR \fIw\fR \fItimeaxis\fR \fIxaxis\fR
.sp
................................................................................
.sp
\fB$anyplot\fR xsubtext \fItext\fR
.sp
\fB$anyplot\fR ysubtext \fItext\fR
.sp
\fB$anyplot\fR vsubtext \fItext\fR
.sp
\fB$anyplot\fR xconfig \fB-option\fR \fIvalue\fR \&.\&.\&.
.sp
\fB$anyplot\fR yconfig \fB-option\fR \fIvalue\fR \&.\&.\&.
.sp
\fB$anyplot\fR background \fIpart\fR \fIcolour_or_image\fR \fIdir\fR ?brightness?
.sp
\fB$anyplot\fR xticklines \fIcolour\fR ?dash?
.sp
\fB$anyplot\fR yticklines \fIcolour\fR ?dash?
.sp
\fB$anyplot\fR legend \fIseries\fR \fItext\fR ?spacing?
.sp
\fB$anyplot\fR removefromlegend \fIseries\fR
.sp
\fB$anyplot\fR legendconfig \fB-option\fR \fIvalue\fR \&.\&.\&.
.sp
\fB$anyplot\fR balloon \fIx\fR \fIy\fR \fItext\fR \fIdir\fR
.sp
\fB$anyplot\fR balloonconfig \fIargs\fR
.sp
\fB$anyplot\fR plaintext \fIx\fR \fIy\fR \fItext\fR \fIdir\fR
.sp
................................................................................
.sp
\fB$xyplot\fR interval \fIseries\fR \fIxcrd\fR \fIymin\fR \fIymax\fR ?ycentr?
.sp
\fB$xyplot\fR box-and-whiskers \fIseries\fR \fIxcrd\fR \fIycrd\fR
.sp
\fB$xyplot\fR vector \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIucmp\fR \fIvcmp\fR
.sp
\fB$xyplot\fR vectorconfig \fIseries\fR \fB-option\fR \fIvalue\fR \&.\&.\&.
.sp
\fB$xyplot\fR dot \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIvalue\fR
.sp
\fB$xyplot\fR dotconfig \fIseries\fR \fB-option\fR \fIvalue\fR \&.\&.\&.
.sp
\fB$xyplot\fR contourlines \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
.sp
\fB$xyplot\fR contourlinesfunctionvalues \fIxvec\fR \fIyvec\fR \fIvaluesmat\fR ?classes?
.sp
\fB$xyplot\fR contourfill \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
.sp
................................................................................
.sp
\fB$plot3d\fR colours \fIfill\fR \fIborder\fR
.sp
\fB$plot3d\fR ribbon \fIyzpairs\fR
.sp
\fB$plot3d\fR plot \fIyzpairs\fR
.sp
\fB$xyplot\fR dataconfig \fIseries\fR \fB-option\fR \fIvalue\fR \&.\&.\&.
.sp
\fB$pie\fR plot \fIdata\fR
.sp
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR \&.\&.\&.
.sp
\fB$pie\fR explode \fIsegment\fR
.sp
\fB$radial\fR plot \fIdata\fR \fIcolour\fR \fIthickness\fR
.sp
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR \&.\&.\&.
.sp
\fB$barchart\fR plot \fIseries\fR \fIydata\fR \fIcolour\fR ?dir? ?brightness?
.sp
\fB$barchart\fR config \fB-option\fR \fIvalue\fR \&.\&.\&.
.sp
\fB$barchart\fR plot \fIseries\fR \fIxdata\fR \fIcolour\fR ?dir? ?brightness?
.sp
\fB$barchart\fR config \fB-option\fR \fIvalue\fR \&.\&.\&.
.sp
\fB$barchart\fR plot \fIlabel\fR \fIyvalue\fR \fIcolour\fR
.sp
\fB$barchart\fR config \fB-option\fR \fIvalue\fR \&.\&.\&.
.sp
\fB$ribbon\fR line \fIxypairs\fR \fIcolour\fR
.sp
\fB$ribbon\fR area \fIxypairs\fR \fIcolour\fR
.sp
\fB$boxplot\fR plot \fIseries\fR \fIlabel\fR \fIvalues\fR
.sp
................................................................................
.sp
\fB$anyplot\fR bindlast \fIseries\fR \fIevent\fR \fIcommand\fR
.sp
.BE
.SH DESCRIPTION
.PP
Plotchart is a Tcl-only package that focuses on the easy creation of
xy-plots, barcharts and other common types of graphical presentations\&.
The emphasis is on ease of use, rather than flexibility\&. The procedures
that create a plot use the entire canvas window, making the layout
of the plot completely automatic\&.
.PP
This results in the creation of an xy-plot in, say, ten lines of code:
.PP
.CS


    package require Plotchart

    canvas \&.c -background white -width 400 -height 200
    pack   \&.c -fill both

    #
    # Create the plot with its x- and y-axes
    #
    set s [::Plotchart::createXYPlot \&.c {0\&.0 100\&.0 10\&.0} {0\&.0 100\&.0 20\&.0}]

    foreach {x y} {0\&.0 32\&.0 10\&.0 50\&.0 25\&.0 60\&.0 78\&.0 11\&.0 } {
        $s plot series1 $x $y
    }

    $s title "Data series"

.CE
.PP
A drawback of the package might be that it does not do any data
management\&. So if the canvas that holds the plot is to be resized, the
whole plot must be redrawn\&.
The advantage, though, is that it offers a number of plot and chart
types:
.IP \(bu
XY-plots like the one shown above with any number of data series\&.
.IP \(bu
Stripcharts, a kind of XY-plots where the horizontal axis is adjusted
automatically\&. The result is a kind of sliding window on the data
series\&.
.IP \(bu
Polar plots, where the coordinates are polar instead of cartesian\&.
.IP \(bu
Histograms, for plotting statistical information\&.
.IP \(bu
Isometric plots, where the scale of the coordinates in the two
directions is always the same, i\&.e\&. a circle in world coordinates
appears as a circle on the screen\&.
.sp
You can zoom in and out, as well as pan with these plots (\fINote:\fR
this works best if no axes are drawn, the zooming and panning routines
do not distinguish the axes), using the mouse buttons with the control
key and the arrow keys with the control key\&.
.IP \(bu
Piecharts, with automatic scaling to indicate the proportions\&.
.IP \(bu
Barcharts, with either vertical or horizontal bars, stacked bars or
bars side by side\&.
.IP \(bu
Timecharts, where bars indicate a time period and milestones or other
important moments in time are represented by triangles\&.
.IP \(bu
3D plots (both for displaying surfaces and 3D bars)
.PP
With version 1\&.5 a new command has been introduced: plotconfig, which
can be used to configure the plot options for particular types of plots
and charts (cf\&. \fBCONFIGURATION OPTIONS\fR)
With version 1\&.8\&.3 several new features were introduced, which allow more interactivity
(cf\&. \fBINTERACTIVE USE\fR)
.SH "PLOT CREATION COMMANDS"
You create the plot or chart with one single command and then fill the
plot with data:
.TP
\fB::Plotchart::createXYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIargs\fR
Create a new xy-plot (configuration type: xyplot)\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order\&.
For an inverted axis, where the maximum appears on the left-hand side,
use: maximum, minimum and a \fInegative\fR stepsize\&.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order\&.
For an inverted axis, where the maximum appears at the bottom,
use: maximum, minimum and a \fInegative\fR stepsize\&.
.TP
list \fIargs\fR (in)
Zero or more options that influence the appearance of the plot:
.RS
.IP \(bu
\fI-xlabels {labels}:\fR Custom labels for the x-axis\&. If the labels
are numeric, they are positioned according to the given scale,
otherwise they are positioned with equal distance, based on the number
of labels\&. Note: this only works if the stepsize of the xaxis argument is
the empty string\&.
.IP \(bu
\fI-ylabels {labels}:\fR Similarly, custom labels for the y-axis\&.
.IP \(bu
\fI-box {measures}:\fR See \fBARRANGING MULTIPLE PLOTS IN A CANVAS\fR
.IP \(bu
\fI-axesbox {measures}:\fR See \fBARRANGING MULTIPLE PLOTS IN A CANVAS\fR
.RE
.RE
.sp
.TP
\fB::Plotchart::createStripchart\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new strip chart (configuration type: stripchart)\&. The
only difference to a regular XY plot is
that the x-axis will be automatically adjusted when the x-coordinate
of a new point exceeds the maximum\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order\&.
Note that an inverted x-axis is \fInot\fR supported for this type of plot\&.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order\&.
For an inverted axis, where the maximum appears at the bottom,
use: maximum, minimum and a \fInegative\fR stepsize\&.
.RE
.sp
.TP
\fB::Plotchart::createTXPlot\fR \fIw\fR \fItimeaxis\fR \fIxaxis\fR
Create a new time-x-plot (configuration type: txplot)\&. The horizontal axis represents the date/time
of the data and the vertical axis the values themselves\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fItimeaxis\fR (in)
A 3-element list containing the minimum and maximum date/time to be
shown and the stepsize (\fIin days\fR) for the time-axis, in this order\&.
Note that an inverted time-axis is \fInot\fR supported\&.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the
vertical axis, in this order\&.
For an inverted axis, where the maximum appears at the bottom,
use: maximum, minimum and a \fInegative\fR stepsize\&.
.RE
.sp
.TP
\fB::Plotchart::createXLogYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new xy-plot where the y-axis has a logarithmic scale (configuration type: xlogyplot)\&.
.sp
The data should be given as for a linear scale, as the logarithmic transformation
is taken of internally\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order\&.
For an inverted axis, where the maximum appears on the left-hand side,
use: maximum, minimum and a \fInegative\fR stepsize\&.
.TP
list \fIyaxis\fR (in)
A 2-element list containing minimum and maximum for the y-axis, in this order\&.
Note that an inverted logarithmic axis is \fInot\fR supported\&.
.RE
.sp
.TP
\fB::Plotchart::createLogXYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new xy-plot where the x-axis has a logarithmic scale (configuration type: logxyplot)\&.
.sp
The data should be given as for a linear scale, as the logarithmic transformation
is taken of internally\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIxaxis\fR (in)
A 2-element list containing minimum and maximum for the x-axis, in this order\&.
Note that an inverted logarithmic axis is \fInot\fR supported\&.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order\&.
For an inverted axis, where the maximum appears on the left-hand side,
use: maximum, minimum and a \fInegative\fR stepsize\&.
.RE
.sp
.TP
\fB::Plotchart::createLogXLogYPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new xy-plot where both the x-axis and the y-axis have a logarithmic scale
(configuration type: logxlogyplot)\&.
.sp
The data should be given as for a linear scale, as the logarithmic transformation
is taken of internally\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIxaxis\fR (in)
A 2-element list containing minimum and maximum for the x-axis, in this order\&.
Note that an inverted logarithmic axis is \fInot\fR supported\&.
.TP
list \fIyaxis\fR (in)
A 2-element list containing minimum and maximum for the y-axis, in this order\&.
Note that an inverted logarithmic axis is \fInot\fR supported\&.
.RE
.sp
.TP
\fB::Plotchart::createPolarPlot\fR \fIw\fR \fIradius_data\fR
Create a new polar plot (configuration type: polarplot)\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIradius_data\fR (in)
A 2-element list containing maximum radius and stepsize for the radial
axis, in this order\&.
.RE
.sp
.TP
\fB::Plotchart::createWindrose\fR \fIw\fR \fIradius_data\fR \fIsectors\fR
Create a new windrose diagram\&. The diagram will consist of concentric
circles as defined by the \fIradius_data\fR argument and a number of
sectors (given by the \fIsectors\fR argument)\&. The sectors are drawn in
the "nautical" convention, that is: the first is located at the positive
y-axis, the second is to the right and so on in a clockwise direction\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the diagram
.TP
list \fIradius_data\fR (in)
A 2-element list, the first element is the maximum radius, the second is
the step to be used for the circles\&.
.TP
int \fIsectors\fR
Number of sectors to use (defaults to 16)\&.
.RE
.sp
.TP
\fB::Plotchart::createIsometricPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIstepsize\fR
Create a new isometric plot, where the vertical and the horizontal
coordinates are scaled so that a circle will truly appear as a circle (configuration type: isometric)\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIxaxis\fR (in)
A 2-element list containing minimum, and maximum for the x-axis, in this order\&.
.TP
list \fIyaxis\fR (in)
A 2-element list containing minimum, and maximum for the y-axis, in this order\&.
.TP
float|\fBnoaxes\fR \fIstepsize\fR (in)
Either the stepsize used by both axes or the keyword \fBnoaxes\fR to
signal the plot that it should use the full area of the widget, to not
draw any of the axes\&.
.RE
.sp
.TP
\fB::Plotchart::createHistogram\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR
Create a new histogram (configuration type: histogram)\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order\&.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order\&.
.RE
.sp
.TP
\fB::Plotchart::create3DPlot\fR \fIw\fR \fIxaxis\fR \fIyaxis\fR \fIzaxis\fR
Create a new 3D plot\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order\&.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order\&.
.TP
list \fIzaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the z-axis, in this order\&.
.RE
.sp
.TP
\fB::Plotchart::create3DRibbonPlot\fR \fIw\fR \fIyaxis\fR \fIzaxis\fR
Create a new 3D ribbon plot\&. It is a simplification of the full 3D plot and allows for
the drawing of a ribbon only (the x-axis is dropped)\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order\&.
.TP
list \fIzaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the z-axis, in this order\&.
.RE
.sp
.TP
\fB::Plotchart::createPiechart\fR \fIw\fR
Create a new piechart (configuration type: piechart)\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.RE
.sp
.TP
\fB::Plotchart::createSpiralPie\fR \fIw\fR
Create a new "spiral pie" (configuration type: spiralpie), a variation on the ordinary
piechart\&. The value is used to scale the radius, rather than the angle\&. By default the
data are sorted\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.RE
.sp
.TP
\fB::Plotchart::createRadialchart\fR \fIw\fR \fInames\fR \fIscale\fR \fIstyle\fR
Create a new radial chart (the data are drawn as a line connecting the
spokes of the diagram) (configuration type: radialchart)\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fInames\fR (in)
Names for the spokes\&.
.TP
float \fIscale\fR (in)
Scale value to determine the position of the data along the spokes\&.
.TP
string \fIstyle\fR (in)
Style of the chart (optional)\&. One of:
.RS
.IP \(bu
\fIlines\fR - the default: draw the data as independent polylines\&.
.IP \(bu
\fIcumulative\fR - draw the data as polylines where the data are
accumulated\&.
.IP \(bu
\fIfilled\fR - draw the data as filled polygons where the data are
accumulated
.RE
.RE
.sp
.TP
\fB::Plotchart::createBarchart\fR \fIw\fR \fIxlabels\fR \fIyaxis\fR \fInoseries\fR
Create a new barchart with vertical bars (configuration type: vertbars)\&. The horizontal axis will
display the labels contained in the argument \fIxlabels\fR\&. The number
of series given by \fInoseries\fR determines both the width of the
bars, and the way the series will be drawn\&.
.sp
If the keyword \fBstacked\fR was specified the series will be drawn
stacked on top of each other\&. Otherwise each series that is drawn will
be drawn shifted to the right\&.
.sp
The number of series determines the width of the bars, so that there is
space of that number of bars\&. If you use a floating-point number, like
2\&.2, instead of an integer, like 2, a small gap between the sets of bars
will be drawn - the width depends on the fractional part\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIxlabels\fR (in)
List of labels for the x-axis\&. Its length also determines the number of
bars that will be plotted per series\&.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order\&.
.TP
int|\fBstacked\fR \fInoseries\fR (in)
The number of data series that will be plotted\&. This has to be an
integer number greater than zero (if \fBstacked\fR is not used)\&.
.RE
.sp
.TP
\fB::Plotchart::createHorizontalBarchart\fR \fIw\fR \fIxaxis\fR \fIylabel\fR \fInoseries\fR
Create a new barchart with horizontal bars (configuration type: horizbars)\&. The vertical axis will
display the labels contained in the argument \fIylabels\fR\&. The number
of series given by \fInoseries\fR determines both the width of the
bars, and the way the series will be drawn\&.
.sp
If the keyword \fBstacked\fR was specified the series will be drawn
stacked from left to right\&. Otherwise each series that is drawn will
be drawn shifted upward\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIxaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order\&.
.TP
list \fIylabels\fR (in)
List of labels for the y-axis\&. Its length also determines the number of
bars that will be plotted per series\&.
.TP
int|\fBstacked\fR \fInoseries\fR (in)
The number of data series that will be plotted\&. This has to be an
integer number greater than zero (if \fBstacked\fR is not used)\&.
.RE
.sp
.TP
\fB::Plotchart::create3DBarchart\fR \fIw\fR \fIyaxis\fR \fInobars\fR
Create a new barchart with 3D vertical bars (configuration type: 3dbars)\&. The horizontal axis will
display the labels per bar\&. The number of bars given by \fInobars\fR
determines the position and the width of the bars\&. The colours can be
varied per bar\&. (This type of chart was inspired by the Wiki page on 3D
bars by Richard Suchenwirth\&.)
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order\&.
.TP
int \fInobars\fR (in)
The number of bars that will be plotted\&.
.RE
.sp
.TP
\fB::Plotchart::create3DRibbonChart\fR \fIw\fR \fInames\fR \fIyaxis\fR \fIzaxis\fR
Create a new "ribbon chart" (configuration type: 3dribbon)\&. This is
a chart where the data series are
represented as ribbons in a three-dimensional axis system\&. Along the
x-axis (which is "into" the screen) the names are plotted, each
representing a single series\&. The first plot command draws the furthest
series, the second draws the series in front of that and so on\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
widget \fIw\fR (in)
Names of the series, plotted as labels along the x-axis
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis
(drawn horizontally!), in this order\&.
.TP
list \fIzaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the z-axis
(drawn vertically), in this order\&.
.TP
int \fInobars\fR (in)
The number of bars that will be plotted\&.
.RE
.sp
.TP
\fB::Plotchart::createBoxplot\fR \fIw\fR \fIxdata\fR \fIydata\fR \fIorientation\fR
Create a new boxplot with horizontal or vertical boxes (box-and-whiskers) (configuration type: boxplot)\&. Depending
on the orientation the x- or y-axis is drawn with labels\&. The boxes are drawn based on the raw data
(see the plot subcommand for this type of plot)\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIxdata\fR (in)
This is either a 3-element list containing minimum, maximum and stepsize for the x-axis, in this order
(when orientation is horizontal), or a list of labels for the x-axis (when orientation is vertical)\&. The length
of the label list also determines the number of boxes that can be plotted\&. The labels are also used in the plot
subcommand\&.
.TP
list \fIydata\fR (in)
This is either a 3-element list containing minimum, maximum and stepsize for the y-axis, in this order
(when orientation is vertical), or a list of labels for the y-axis (when orientation is horizontal)\&. The length
of the label list also determines the number of boxes that can be plotted\&. The labels are also used in the plot
subcommand\&.
.TP
string \fIorientation\fR (in)
If given, "horizontal" or "vertical" determines the orientation of the boxes\&. This optional value (default: horizontal)
also determines the interpretation of the xdata and ydata arguments\&.
.RE
.sp
.TP
\fB::Plotchart::createTimechart\fR \fIw\fR \fItime_begin\fR \fItime_end\fR \fIargs\fR
Create a new timechart (configuration type: timechart)\&.
The time axis (= x-axis) goes from \fItime_begin\fR to \fItime_end\fR,
and the vertical spacing is determined by the number of items to plot\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
string \fItime_begin\fR (in)
The start time given in a form that is recognised by the \fBclock scan\fR
command (e\&.g\&. "1 january 2004")\&.
.TP
string \fItime_end\fR (in)
The end time given in a form that is recognised by the \fBclock scan\fR
command (e\&.g\&. "1 january 2004")\&.
.TP
arguments \fIargs\fR (in)
The remaining arguments can be:
.RS
.IP \(bu
The expected/maximum number of items\&. This determines the vertical
spacing\&. (If given, it must be the first argument after "time_end"
.IP \(bu
The keyword -barheight and the number of pixels per bar\&. This is an
alternative method to determine the vertical spacing\&.
.IP \(bu
The keyword -ylabelwidth and the number of pixels to reserve for the
labels at the y-axis\&.
.RE
.RE
.TP
\fB::Plotchart::createGanttchart\fR \fIw\fR \fItime_begin\fR \fItime_end\fR \fIargs\fR
Create a new Gantt chart (configuration type: ganttchart)\&.
The time axis (= x-axis) goes from \fItime_begin\fR to \fItime_end\fR,
and the vertical spacing is determined by the number of items to plot\&.
Via the specific commands you can then add tasks and connections between
the tasks\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
string \fItime_begin\fR (in)
The start time given in a form that is recognised by the \fBclock scan\fR
command (e\&.g\&. "1 january 2004")\&.
.TP
string \fItime_end\fR (in)
The end time given in a form that is recognised by the \fBclock scan\fR
command (e\&.g\&. "1 january 2004")\&.
.TP
arguments \fIargs\fR (in)
The remaining arguments can be:
.RS
.IP \(bu
The expected/maximum number of items\&. This determines the vertical
spacing\&. (If given this way, it must be the first argument after "time_end")
.IP \(bu
The expected/maximum width of the descriptive text (roughly in characters,
for the actual space reserved for the text, it is assumed that a
character is about ten pixels wide)\&. Defaults to 20\&. (If given this way,
it must be the second argument after "time_end")\&.
.IP \(bu
The keyword -barheight and the number of pixels per bar\&. This is an
alternative method to determine the vertical spacing\&.
.IP \(bu
The keyword -ylabelwidth and the number of pixels to reserve for the
labels at the y-axis\&.
.RE
.RE
.TP
\fB::Plotchart::createRightAxis\fR \fIw_or_plot\fR \fIyaxis\fR
Create a plot command that will use a right axis instead of the left
axis (configuration type: inherited from the existing plot)\&. The canvas widget
must already contain an ordinary plot, as the
horizontal axis and other properties are reused\&. Preferably use the
plot command, as with multiple plots in a canvas (also when redefining an existing
plot!), the wrong geometry might be used\&.
.sp
To plot data using the
right axis, use this new command, to plot data using the \fIleft\fR
axis, use the original plot command\&.
.RS
.TP
widget \fIw_or_plot\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot or preferably the
plot command for the plot with the left axis\&.
.TP
list \fIyaxis\fR (in)
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order\&.
.RE
.TP
\fB::Plotchart::createTableChart\fR \fIw\fR \fIcolumns\fR ?widths?
Create a command to draw a table\&. You can use a variety of commands to
draw the actual rows of the table, but the number of columns is fixed\&.
(See \fBTABLE CHARTS\fR for an example)
.RS
.TP
widget \fIw\fR (in)
Name of the canvas widget to hold the table\&.
.TP
list \fIcolumns\fR (in)
The headers of the columns in the table\&. The number of elements
determines the number of columns\&.
.TP
list \fIwidths\fR (in)
If given, either a single value, the width in pixels for all columns or
for each column the width of that column\&. If not given, the table is
spread out over the width of the canvas (minus the margins)\&.
.RE
.sp
.PP
.SH "PLOT METHODS"
Each of the creation commands explained in the last section returns
the name of a new object command that can be used to manipulate the
plot or chart\&. The subcommands available to a chart command depend on
the type of the chart\&.
.PP
General subcommands for all types of charts\&. \\$anyplot is the command
returned by the creation command:
.TP
\fB$anyplot\fR title \fItext\fR \fIposition\fR
Specify the title of the whole chart\&.
.RS
.TP
string \fItext\fR (in)
The text of the title to be drawn\&.
.TP
string \fIposition\fR (in)
The position of the title\&. The default position is "center", but you can
alternatively use "left" or "right"\&. You can use multiple titles with
different positions\&.
.RE
.sp
.TP
\fB$anyplot\fR subtitle \fItext\fR
Specify the subtitle of the whole chart\&.
.RS
.TP
string \fItext\fR (in)
The text of the subtitle to be drawn\&.
.RE
.sp
.TP
\fB$anyplot\fR canvas
Return the name of the canvas (or the alias if you use more than one plot within a
canvas)\&. Use this value for the coordinate transformations\&.
.sp
.TP
\fB$anyplot\fR saveplot \fIfilename\fR \fIargs\fR
Draws the plot into a file, using PostScript\&.
.RS
.TP
string \fIfilename\fR (in)
Contain the path name of the file to write the plot to\&.
.TP
list \fIargs\fR (in)
If the standard PostScript output is used, the option -plotregion can be specifed
to save the whole plot (value: bbox) regardless of what is visible in the window\&.
The default (value: window) is to only plot the visible part of the plot\&.
.sp
Optionally you can specify the option -format "some picture format" to
store the plot in a different file than a PostScript file\&. This,
however, relies on the Img package to do the actual job\&.
.sp
\fINote:\fR
Because the window holding the plot must be fully visible before Img can
successfully grab it, it is raised first\&.
On some systems, for instance Linux with KDE, raising
a window is not done automatically, but instead you need to click on the
window in the task bar\&. Similar things happen on Windows XP\&.
.sp
There seems to be something wrong under some circumstances, so instead
of waiting for the visibility of the window, the procedure simply waits
two seconds\&. It is not ideal, but it seems to work better\&.
.RE
.sp
.TP
\fB$anyplot\fR xtext \fItext\fR
Specify the title of the (horizontal) x-axis, for those plots that have
a straight x-axis\&.
.RS
.TP
string \fItext\fR (in)
The text of the x-axis label to be drawn\&.
.RE
.sp
.TP
\fB$anyplot\fR ytext \fItext\fR
Specify the title of the (horizontal) y-axis, for those plots that have
a straight y-axis\&.
.RS
.TP
string \fItext\fR (in)
The text of the y-axis label to be drawn\&.
.RE
.TP
\fB$anyplot\fR vtext \fItext\fR
Draw a \fIvertical\fR label to the y-axis\&. Note: this requires Tk 8\&.6
or later, for older versions it does nothing\&.
.RS
.TP
string \fItext\fR (in)
Text to drawn to the y-axis
.RE
.sp
.TP
\fB$anyplot\fR xsubtext \fItext\fR
Specify the subtext of the (horizontal) x-axis, for those plots that have
a straight x-axis\&. This text is drawn below the primary text\&.
.sp
Since this involves positioning the primary text and setting margins, you need to
set the option "usesubtext" for the bottom axis via the plotstyle command\&. The relevant
options are: usesubtext, subtextcolor and subtextfont\&.
.RS
.TP
string \fItext\fR (in)
The secondary text of the x-axis label to be drawn\&.
.RE
.sp
.TP
\fB$anyplot\fR ysubtext \fItext\fR
Specify the subtext of the (vertical) y-axis, for those plots that have
a straight y-axis\&. This text is drawn below the primary text, for both
axes on the left and the right\&.
.sp
Since this involves positioning the primary text and setting margins, you need to
set the option "usesubtext" for the left or right axis via the plotstyle command\&. The relevant
options are: usesubtext, subtextcolor and subtextfont\&.
.RS
.TP
string \fItext\fR (in)
The secondary text of the y-axis label to be drawn\&.
.RE
.sp
.TP
\fB$anyplot\fR vsubtext \fItext\fR
Specify the subtext of the (vertical) y-axis, for those plots that have
a straight y-axis\&. This text is drawn to the \fIright\fR of the primary text, for both
axes on the left and the right\&.
.sp
Since this involves positioning the primary text and setting margins, you need to
set the option "usesubtext" for the left or right axis via the plotstyle command\&. The relevant
options are: usevsubtext, vsubtextcolor and vsubtextfont\&. (Note the "v" to distinguish this
option from the text at the top of a vertical axis that is drawn via \fI$anyplot ytext\fR or
\fI$anyplot ysubtext\fR\&.)
.RS
.TP
string \fItext\fR (in)
The secondary (vertical) text of the y-axis label to be drawn\&.
.RE
.sp
.TP
\fB$anyplot\fR xconfig \fB-option\fR \fIvalue\fR \&.\&.\&.
Set one or more configuration parameters for the x-axis\&.
The following options are supported:
.RS
.TP
\fBformat\fR fmt
The format for the numbers along the axis\&.
.TP
\fBticklength\fR length
The length of the tickmarks (in pixels)\&.
.TP
\fBticklines\fR boolean
Whether to draw ticklines (\fBtrue\fR) or not (\fBfalse\fR)\&.
.TP
\fBscale\fR scale_data
New scale data for the axis, i\&.e\&. a 3-element list containing minimum,
maximum and stepsize for the axis, in this order\&.
.sp
\fIBeware:\fR Setting this option will clear all data from the plot\&.
.RE
.sp
.TP
\fB$anyplot\fR yconfig \fB-option\fR \fIvalue\fR \&.\&.\&.
Set one or more configuration parameters for the y-axis\&. This method
accepts the same options and values as the method \fBxconfig\fR\&.
.TP
\fB$anyplot\fR background \fIpart\fR \fIcolour_or_image\fR \fIdir\fR ?brightness?
Set the background of a part of the plot
.RS
.TP
string \fIpart\fR
Which part of the plot: "axes" for the axes area and "plot" for the
inner part\&. The interpretation depends on the type of plot\&. Two further
possibilities are:
.RS
.IP \(bu
\fIimage\fR, in which case a predefined image is loaded
into the background of the plot\&.
.IP \(bu
\fIgradient\fR, in which case the background is coloured in different
shades of the given colour\&. The "dir" argument specifies the direction
in which the colour gets whiter\&.
.RE
.TP
string \fIcolour_or_image\fR
Colour for that part or the name of the image if "part" is "image"
.TP
string \fIdir\fR
The direction of the gradient\&. One of: top-down, bottom-up, left-right
or right-left\&.
.TP
string \fIbrightness\fR
Indicates whether the colour should become brighter (bright) or darker (dark)\&. Defaults to bright
.RE
.sp
.TP
\fB$anyplot\fR xticklines \fIcolour\fR ?dash?
Draw vertical ticklines at each tick location
.RS
.TP
string \fIcolour\fR
Colour of the lines\&. Specifying an empty colour ("") removes them again\&.
Defaults to "black"
.TP
string \fIdash\fR
Optional argument to specify the dash pattern for the lines\&. Defaults to "lines"
Possible values: lines, dots1, dots2, dots3, dots4, dots5\&.
The actual effect depends on the platform\&.
.RE
.sp
.TP
\fB$anyplot\fR yticklines \fIcolour\fR ?dash?
Draw horizontal ticklines at each tick location
.RS
.TP
string \fIcolour\fR
Colour of the lines\&. Specifying an empty colour ("") removes them again
Defaults to "black"
.TP
string \fIdash\fR
Optional argument to specify the dash pattern for the lines\&. Defaults to "lines"
Possible values: lines, dots1, dots2, dots3, dots4, dots5\&.
The actual effect depends on the platform\&.
.RE
.sp
.TP
\fB$anyplot\fR legend \fIseries\fR \fItext\fR ?spacing?
Add an entry to the legend\&. The series determines which graphical
symbol is to be used\&. (As a side effect the legend is actually drawn\&.)
.RS
.TP
string \fIseries\fR
Name of the data series\&. This determines the colour of the line and the
symbol (if any) that will be drawn\&.
.TP
string \fItext\fR
Text to be drawn next to the line/symbol\&.
.TP
integer \fIspacing\fR
Optional argument to specify the vertical spacing between the entries (in pixels)\&.
(Note that this spacing will be reused later\&.)
.RE
.sp
.TP
\fB$anyplot\fR removefromlegend \fIseries\fR
Remove an entry for a series from the legend and redraw it\&.
.RS
.TP
string \fIseries\fR
Name of the data series to be removed\&.
.RE
.sp
.TP
\fB$anyplot\fR legendconfig \fB-option\fR \fIvalue\fR \&.\&.\&.
Set one or more options for the legend\&. The legend is drawn as a
rectangle with text and graphics inside\&.
.RS
.TP
\fBbackground\fR colour
Set the colour of the background (the default colour is white)\&.
Set to the empty string for a transparant legend\&.
.TP
\fBborder\fR colour
Set the colour of the border (the default colour is black)\&. Set to the
empty string if you do not want a border\&.
.TP
\fBcanvas\fR c
Draw the legend in a different canvas widget\&. This gives you the freedom
to position the legend outside the actual plot\&.
.TP
\fBfont\fR font
Set the font used to draw the text next to the symbol\&.
.TP
\fBlegendtype\fR
Override the type of the legend, that is pre-defined for the current type of
plot\&. May be one of: rectangle or line\&.
.TP
\fBposition\fR corner
Set the position of the legend\&. May be one of: top-left, top-right,
bottom-left or bottom-right\&. (Default value is top-right\&.)
.RE
.sp
.TP
\fB$anyplot\fR balloon \fIx\fR \fIy\fR \fItext\fR \fIdir\fR
Add balloon text to the plot (except for 3D plots)\&. The arrow will point
to the given x- and y-coordinates\&. For xy-graphs and such, the
coordinates are directly related to the axes; for vertical barcharts the
x-coordinate is measured as the number of bars minus 1 and similar for
horizontal barcharts\&.
.RS
.TP
float \fIx\fR
X-coordinate of the point that the arrow of the balloon will point to\&.
.TP
float \fIy\fR
Y-coordinate of the point that the arrow of the balloon will point to\&.
.TP
string \fItext\fR
Text to be drawn in the balloon\&.
.TP
string \fIdir\fR
Direction of the arrow, one of: north, north-east, east, south-east,
south, south-west, west or north-west\&.
.RE
.sp
.TP
\fB$anyplot\fR balloonconfig \fIargs\fR
Configure the balloon text for the plot\&. The new settings will be used
for the next balloon text\&.
.RS
.TP
\fBfont\fR fontname
Font to be used for the text
.TP
\fBjustify\fR left|center|right
Way to justify multiline text
................................................................................
Width of the outline of the balloon (in pixels)
.TP
\fBarrowsize\fR value
Length factor for the arrow (in pixels)
.RE
.TP
\fB$anyplot\fR plaintext \fIx\fR \fIy\fR \fItext\fR \fIdir\fR
Add plain text to the plot (except for 3D plots)\&. The text is positioned at
the given x- and y-coordinates\&. For xy-graphs and such, the
coordinates are directly related to the axes; for vertical barcharts the
x-coordinate is measured as the number of bars minus 1 and similar for
horizontal barcharts\&.
.RS
.TP
float \fIx\fR
X-coordinate of the text position
.TP
float \fIy\fR
Y-coordinate of the text position
.TP
string \fItext\fR
Text to be drawn\&.
.TP
string \fIdir\fR
Anchor for the text, one of: north, north-east, east, south-east,
south, south-west, west or north-west\&.
.RE
.sp
.TP
\fB$anyplot\fR plaintextconfig \fIargs\fR
Configure the plain text annotation for the plot\&. The new settings will be used
for the next plain text\&.
.RS
.TP
\fBfont\fR fontname
Font to be used for the text
.TP
\fBjustify\fR left|center|right
Way to justify multiline text
................................................................................
.TP
\fBtextcolour\fR colour
Colour for the text (synonym: textcolor)
.RE
.TP
\fB$anyplot\fR object \fIitemtype\fR \fIseries\fR \fIargs\fR
Draw a canvas item in the plot where the coordinates are scaled using the
coordinate system of the plot\&. In addition to the standard canvas types, it
also supports circles, dots and crosses\&.
.sp
\fINote:\fR Currently implemented for xy-plots, (vertical and horizontal)
barcharts, and piecharts\&.
.sp
\fINote:\fR To add an entry in the legend for the object, you can use the
\fIdataconfig\fR subcommand with a type "rectangle"\&. This will cause a rectangle
to be shown\&.
.RS
.TP
string \fIitemtype\fR (in)
Name of a standard canvas item or "circle", "dot" or "cross"
.TP
string \fIseries\fR (in)
The data series it belongs to, used for setting the default drawing options
................................................................................
.TP
list \fIargs\fR (in)
List of coordinates and drawing options
.RE
.TP
\fB$anyplot\fR deletedata
Remove the lines, symbols and other graphical object associated with the
actual data from the plot\&.
.sp
\fINote:\fR Currently implemented for xy-plots only
.sp
\fINote:\fR The existing options for data series and the legend entry are
kept as they were\&.
.sp
\fINote:\fR Currently there are side effects if the canvas contains more than
one plot\&.
.PP
.PP
\fINote:\fR The commands \fBxconfig\fR and \fByconfig\fR are
currently implemented only for XY-plots
and only the option \fB-format\fR has any effect\&.
.PP
For \fIxy plots\fR, \fIstripcharts\fR, \fIhistograms\fR and
\fItime-x-plots\fR:
.TP
\fB$xyplot\fR plot \fIseries\fR \fIxcrd\fR \fIycrd\fR
Add a data point to the plot\&.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the new point belongs to\&.
.TP
float \fIxcrd\fR (in)
X-coordinate of the new point\&. (For time-x plots this must be valid
date/time that can be read with the \fIclock scan\fR command)\&.
.TP
float \fIycrd\fR (in)
Y-coordinate of the new point\&.
.RE
.PP
.PP
For \fIxy plots\fR there is the additional command \fIplotlist\fR,
which is useful for plotting a large amount of data:
.TP
\fB$xyplot\fR plotlist \fIseries\fR \fIxlist\fR \fIylist\fR \fIevery\fR
Draw a series of data as a whole\&. If symbols are asked for, draw them only
for every Nth data point\&.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the new point belongs to\&.
.TP
float \fIxlist\fR (in)
List of X-coordinates for the data series\&.
.TP
float \fIycrd\fR (in)
List of Y-coordinates for the data series\&.
.TP
int \fIevery\fR (in)
Optional argument stating how often a symbol (if any) should be drawn\&.
If left out, use a simple heuristic: N = sqrt(number of data points)\&.
.RE
.PP
.PP
\fINote on histograms:\fR
.PP
For histograms the x-coordinate that is given is interpreted to be
the x-coordinate of the \fIright\fR side of the bar (or line segment)\&. The first
bar starts at the y-axis on the left\&. To completely fill the range
of the x-axis, you should draw a bar at the maximum x-coordinate\&.
.PP
For histograms you can also use the \fBplotcumulative\fR command:
.TP
\fB$histogram\fR plotcumulative \fIseries\fR \fIxcrd\fR \fIycrd\fR
.PP
The arguments mean exactly the same as for the \fBplot\fR command, but
the data are accumulated to the previous values\&.
.PP
For \fIxy plots\fR:
.TP
\fB$xyplot\fR trend \fIseries\fR \fIxcrd\fR \fIycrd\fR
Draw or update a trend line using the data given sofar\&.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the trend line belongs to\&.
.TP
float \fIxcrd\fR (in)
X-coordinate of the new data point
.TP
float \fIycrd\fR (in)
Y-coordinate of the new data point
.RE
.TP
\fB$xyplot\fR rchart \fIseries\fR \fIxcrd\fR \fIycrd\fR
Draw data in the same way as the plot method, but with two lines added
that indicate the expected range (+/- 3*standard deviation) of the data\&.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the data point belongs to\&.
.TP
float \fIxcrd\fR (in)
X-coordinate of the new data point
.TP
float \fIycrd\fR (in)
Y-coordinate of the new data point
.RE
.TP
\fB$xyplot\fR interval \fIseries\fR \fIxcrd\fR \fIymin\fR \fIymax\fR ?ycentr?
Add a vertical error interval to the plot\&. The interval is drawn from
ymin to ymax\&. If the ycentr argument is given, a symbol is drawn at that
position\&.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the interval belongs to\&.
.TP
float \fIxcrd\fR (in)
X-coordinate of the interval
.TP
float \fIymin\fR (in)
Minimum y-coordinate of the interval\&.
.TP
float \fIymax\fR (in)
Maximum y-coordinate of the interval\&.
.TP
float \fIycentr\fR (in)
Y-coordinate to draw the symbol at (optional)
.RE
.TP
\fB$xyplot\fR box-and-whiskers \fIseries\fR \fIxcrd\fR \fIycrd\fR
Draw a box and whiskers in the plot\&. If the argument \fIxcrd\fR is a
list of
several values and the argument \fIycrd\fR is a single value, a
horizontal
box is drawn with the quartiles determined from the list of values
contained in \fIxcrd\fR\&.
.sp
If, instead, the argument \fIycrd\fR contains a list of several values
and the argument \fIxcrd\fR a single value, then a vertical box is
drawn and the quartiles are determined from \fIycrd\fR\&. (There must be
exactly one list of several values\&. Otherwise an error is reported\&.)
.sp
The option -boxwidth to the dataconfig command determines the width (or
height) of the box (default: 10 pixels)\&.
.sp
The option -whiskers to the dataconfig command determines whether the
whiskers are drawn to the extreme values (value: extremes), to 1\&.5
times the interquartile range (value: IQR or iqr), or not at all (value: none)\&.
If the value is 'IQR' (uppercase), then
also extreme values will be shown (from 1\&.5 to 3 times the IQR as dots,
above 3 times IQR as stars)\&. If the value is 'iqr' (lowercase) no extreme
values will be shown (default value: IQR)\&.
.sp
The option -whiskerwidth to the dataconfig command determines the thickness of the line
that draws the whiskers (default: 1 pixel)\&.
.sp
The option -mediancolour to the dataconfig command determines the
colour of the line used to draw the median within the box (default: same as -colour)\&.
.sp
The option -medianwidth to the dataconfig command determines the thickness of the line
that draws the median within the box (default: 1 pixel)\&.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the box-and-whiskers belongs to\&.
.TP
float \fIxcrd\fR (in)
X-coordinate of the box or a list of values\&.
.TP
float \fIymin\fR (in)
Y-coordinate of the box or a list of values\&.
.RE
.sp
The box ends at the 1st and 3rd quartile, while the whiskers by default
are plotted to span 1\&.5 IQR (interquartile range) from the 1st and 3rd quartile\&.
.TP
\fB$xyplot\fR vector \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIucmp\fR \fIvcmp\fR
Draw a vector in the plot\&. The vector can be given as either cartesian
coordinates or as length/angle, where the angle is in degrees and is
interpreted according to the mathematical convention or the nautical\&.
(See the vectorconfig subcommand)
.RS
.TP
string \fIseries\fR (in)
Name of the series the vector belongs to\&. Determines the appearance and
interpretation\&.
.TP
float \fIxcrd\fR (in)
X-coordinate of the point where the arrow appears
.TP
float \fIycrd\fR (in)
Y-coordinate of the point where the arrow appears
.TP
................................................................................
float \fIucmp\fR (in)
X-component or the length of the vector
.TP
float \fIycentr\fR (in)
Y-component or the angle of the vector
.RE
.TP
\fB$xyplot\fR vectorconfig \fIseries\fR \fB-option\fR \fIvalue\fR \&.\&.\&.
]
Set the vector drawing options for a particular series
.RS
.TP
string \fIseries\fR (in)
Name of the series the vector belongs to\&.
.RE
.IP
The options can be one of the following:
.RS
.TP
\fBcolour\fR
The colour of the arrow (default: black; synonym: color)
.TP
\fBscale\fR value
The scale factor used to convert the length of the
arrow into a number of pixels (default: 1\&.0)
.TP
\fBcentred\fR onoff
Logical value indicating that the xy-coordinates
are to be used as the start of the arrow or as the centre (default: 0;
synonym: centered)
.TP
\fBtype\fR keyword
Interpretation of the vector components\&. Can be "cartesian"
(default), in which case the x- and y-components are expected, "polar"
(the angle 0 coincides with the positive x-axis, 90 coincides with the
positive y-axis) or "nautical" (0 is "north" and 90 is "east")\&.
.RE
.sp
.TP
\fB$xyplot\fR dot \fIseries\fR \fIxcrd\fR \fIycrd\fR \fIvalue\fR
Draw a dot in the plot\&. The size and colour is determined by the value
and by the options set for the series it belongs to\&.
(See the dotconfig subcommand)
.RS
.TP
string \fIseries\fR (in)
Name of the series the dot belongs to\&. Determines size and colour
.TP
float \fIxcrd\fR (in)
X-coordinate of the point where the arrow appears
.TP
float \fIycrd\fR (in)
Y-coordinate of the point where the arrow appears
.TP
float \fIvalue\fR (in)
Value determining size and colour
.RE
.TP
\fB$xyplot\fR dotconfig \fIseries\fR \fB-option\fR \fIvalue\fR \&.\&.\&.
]
Set the dot drawing options for a particular series
.RS
.TP
string \fIseries\fR (in)
Name of the series the dot belongs to\&.
.RE
.IP
The options can be one of the following:
.RS
.TP
\fBcolour\fR
The colour of the dot if no scaling is used or the value exceeds the
last limit of the classes\&.
.TP
\fBscale\fR value
The scale factor used to convert the value into the radius of the dot
in pixels (default: 1\&.0)
.TP
\fBradius\fR value
The default radius of the dots, used if there is no scaling by value
(in pixels; default: 3)
.TP
\fBscalebyvalue\fR onoff
Determines whether the dots all have the same size or a size depending
on the given value (default: on)\&.
.TP
\fBoutline\fR onoff
Draw a black circle around the dot or not (default: on)
.TP
\fBclasses\fR list
Set the limits and the corresponding colours\&. For instance:
.CS


    $xyplot series1 -classes {0 blue 1 green} -colour red

.CE
.IP
will cause a blue dot to be drawn for values smaller than 0, a green dot
for values larger/equal 0 but lower than 1 and a red dot for values
larger/equal 1\&.
.TP
\fB3deffect\fR onoff
Show a highlight in the dots, to mimick a 3D effect (default: off)
.sp
If there is no list of classes for the particular series, the dots are
scaled by the value\&.
.sp
You can combine the colouring by value and the scaling by value by
setting a list of classes and setting the \fIscalebyvalue\fR option on\&.
.RE
.sp
.TP
\fB$xyplot\fR contourlines \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
Draw contour lines for the values given on the grid\&. The grid is defined
by the xcrd and ycrd arguments\&. The xcrd argument (resp\&. ycrd)
is expected to be a matrix, implemented as a list of lists which gives the
x-coordinates (resp\&. y-coordinates) of the grid cell corners\&.
The function values are given at these corners\&.
The number of rows in xvec (resp\&. yvec) is ny and each row contains nx values
so that the total number of values in xvec (resp\&. yvec) is nx * ny\&.
The classes determine which contour lines are drawn\&. If a value on one of
the corners is missing, the contour lines in that cell will not be
drawn\&.
.sp
Entries in the legend are drawn via the \fIlegendisolines\fR subcommand\&.
.RS
.TP
list \fIxcrd\fR (in)
List of lists, each value is an x-coordinate for a grid cell corner
.TP
list \fIycrd\fR (in)
List of lists, each value is an y-coordinate for a grid cell corner
.TP
list \fIvalues\fR (in)
List of lists, each value is the value at a grid cell corner
.TP
list \fIclasses\fR (in)
List of class values or a list of lists of two elements (each inner list
the class value and the colour to be used)\&. If empty or missing, the
classes are determined automatically\&.
.sp
\fINote:\fR The class values must enclose the whole range of values\&.
\fINote:\fR The xcrd argument is generally made of nypoints identical rows, while
each row of ycrd is made with one single value\&.
.sp
.RE
.TP
\fB$xyplot\fR contourlinesfunctionvalues \fIxvec\fR \fIyvec\fR \fIvaluesmat\fR ?classes?
Draw contour lines for the values given on the grid\&. The grid is defined
by the xvec and yvec arguments\&. Here, xvec (resp\&. yvec) is a list of x-coordinates
(resp\&. y-coordinates)\&. The number of values in xvec (resp\&. yvec) is the number of points in
the x-coordinate (resp\&. y-coordinate)\&.
The function values are given at these corners\&. The
classes determine which contour lines are drawn\&. If a value on one of
the corners is missing, the contour lines in that cell will not be
drawn\&.
.sp
Entries in the legend are drawn via the \fIlegendisolines\fR subcommand\&.
.RS
.TP
list \fIxcrd\fR (in)
List of x-coordinates in increasing order\&.
.TP
list \fIycrd\fR (in)
List y-coordinates in increasing order\&.
.TP
list \fIvaluesmat\fR (in)
List of lists, each value is the value at a grid cell corner\&.
The total number of values is valuesmat is nx * ny\&.
.TP
list \fIclasses\fR (in)
List of class values or a list of lists of two elements (each inner list
the class value and the colour to be used)\&. If empty or missing, the
classes are determined automatically\&.
.sp
\fINote:\fR The class values must enclose the whole range of values\&.
.sp
.RE
.TP
\fB$xyplot\fR contourfill \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
Draw filled contours for the values given on the grid\&. (The use of this
method is identical to the "contourlines" method)\&.
.sp
Entries in the legend are drawn via the \fIlegendshades\fR subcommand\&.
.TP
\fB$xyplot\fR contourbox \fIxcrd\fR \fIycrd\fR \fIvalues\fR ?classes?
Draw the cells as filled quadrangles\&. The colour is determined from
the average of the values on all four corners\&.
.sp
Entries in the legend are drawn via the \fIlegendshades\fR subcommand\&.
.TP
\fB$xyplot\fR colorMap \fIcolours\fR
Set the colours to be used with the contour methods\&. The argument is
either a predefined colourmap (grey/gray, jet, hot or cool)
or a list of colours\&. When selecting the colours for actually drawing the
contours, the given colours will be interpolated (based on the HLS scheme)\&.
.RS
.TP
list \fIcolours\fR (in)
List of colour names or colour values or one of the predefined maps:
.RS
.IP \(bu
grey or gray: gray colours from dark to light
................................................................................
hot: colours from yellow via red to darkred
.IP \(bu
cool: colours from cyan via blue to magenta
.RE
.RE
.TP
\fB$xyplot\fR legendisolines \fIvalues\fR \fIclasses\fR
Add the contour classes to the legend as coloured lines\&. The text indicates the
values\&.
.RS
.TP
list \fIvalues\fR (in)
The list of values as used for the actual drawing\&. This argument is used only
if the list of classes is empty\&.
.TP
list \fIvalues\fR (in)
The list of classes as used for the actual drawing\&.
.RE
.TP
\fB$xyplot\fR legendshades \fIvalues\fR \fIclasses\fR
Add the contour classes to the legend as coloured rectangles\&. The text indicates the
values\&.
.RS
.TP
list \fIvalues\fR (in)
The list of values as used for the actual drawing\&. This argument is used only
if the list of classes is empty\&.
.TP
list \fIvalues\fR (in)
The list of classes as used for the actual drawing\&.
.RE
.TP
\fB$xyplot\fR grid \fIxcrd\fR \fIycrd\fR
Draw the grid cells as lines connecting the (valid) grid points\&.
.RS
.TP
list \fIxcrd\fR (in)
List of lists, each value is an x-coordinate for a grid cell corner
.TP
list \fIycrd\fR (in)
List of lists, each value is an y-coordinate for a grid cell corner
.RE
.sp
.TP
\fB$xyplot\fR xband \fIymin\fR \fIymax\fR
Draw a light grey band in the plot, ranging over the full x-axis\&. This
can be used to indicate a "typical" range for the data\&.
.RS
.TP
float \fIymin\fR (in)
Lower bound for the band
.TP
float \fIymax\fR (in)
Upper bound for the band
.RE
.sp
.TP
\fB$xyplot\fR yband \fIxmin\fR \fIxmax\fR
Draw a light grey band in the plot, ranging over the full y-axis\&. This
can be used to indicate a "typical" range for the data\&.
.RS
.TP
float \fIxmin\fR (in)
Lower bound for the band
.TP
float \fIxmax\fR (in)
Upper bound for the band
.RE
.sp
.TP
\fB$xyplot\fR labeldot \fIx\fR \fIy\fR \fItext\fR \fIorient\fR
Draw a label and a symbol in the plot\&. The label will appear near the
symbol\&. The label will be drawn in grey, so as not to be too
conspicuous\&.
.sp
You can configure the appearance of the symbol by using the data series
name "labeldot":
\fI$w dataconfig labeldot -colour red -type symbol -symbol dot\fR
.RS
.TP
float \fIx\fR (in)
................................................................................
Y-coordinate of the symbol to be drawn
.TP
string \fItext\fR (in)
Text for the label
.TP
string \fIorient\fR (in)
Optional orientation (one of w, e, n, s) defining the position of the
label with respect to the symbol\&. It defaults to w (so the label
appears left of the symbol)\&.
.RE
.PP
.PP
For \fIpolar plots\fR:
.TP
\fB$polarplot\fR plot \fIseries\fR \fIradius\fR \fIangle\fR
Add a data point to the polar plot\&.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the new point belongs to\&.
.TP
float \fIradius\fR (in)
Radial coordinate of the new point\&.
.TP
float \fIangle\fR (in)
Angular coordinate of the new point (in degrees)\&.
.RE
.PP
.PP
For \fIwind rose diagrams\fR:
.TP
\fB$windrose\fR plot \fIdata\fR \fIcolour\fR
Draw the data contained in the \fIdata\fR argument\&. The data are added to
the existing spokes towards the outer circle\&.
.RS
.TP
list \fIdata\fR (in)
List of data (the length should correspond to the number of sectors)
.TP
string \fIcolour\fR
Colour in which the new segments will be drawn
.RE
.PP
.PP
For \fI3D plots\fR:
.TP
\fB$plot3d\fR plotfunc \fIfunction\fR
Plot a function defined over two variables \fBx\fR and \fBy\fR\&.
The resolution is determined by the set grid sizes (see the method
\fBgridsize\fR for more information)\&.
.RS
.TP
string \fIfunction\fR (in)
Name of the procedure that calculates the z-value for the given x and
y coordinates\&. The procedure has to accept two float arguments (x is
first argument, y is second) and return a floating-point value\&.
.RE
.sp
.TP
\fB$plot3d\fR plotfuncont \fIfunction\fR \fIcontours\fR
Plot a function defined over two variables \fBx\fR and \fBy\fR using
the contour levels in \fBcontours\fR to colour the surface\&.
The resolution is determined by the set grid sizes (see the method
\fBgridsize\fR for more information)\&.
.RS
.TP
string \fIfunction\fR (in)
Name of the procedure that calculates the z-value for the given x and
y coordinates\&. The procedure has to accept two float arguments (x is
first argument, y is second) and return a floating-point value\&.
.TP
list \fIcontours\fR (in)
List of values in ascending order that represent the contour levels
(the boundaries between the colours in the contour map)\&.
.RE
.sp
.TP
\fB$plot3d\fR gridsize \fInxcells\fR \fInycells\fR
Set the grid size in the two directions\&. Together they determine how
many polygons will be drawn for a function plot\&.
.RS
.TP
int \fInxcells\fR (in)
Number of grid cells in x direction\&. Has to be an integer number
greater than zero\&.
.TP
int \fInycells\fR (in)
Number of grid cells in y direction\&. Has to be an integer number
greater than zero\&.
.RE
.sp
.TP
\fB$plot3d\fR plotdata \fIdata\fR
Plot a matrix of data\&.
.RS
.TP
list \fIdata\fR (in)
The data to be plotted\&. The data has to be provided as a nested list
with 2 levels\&. The outer list contains rows, drawn in y-direction, and
each row is a list whose elements are drawn in x-direction, for the
columns\&. Example:
.sp
.CS


    set data {
    {1\&.0 2\&.0 3\&.0}
    {4\&.0 5\&.0 6\&.0}
    }

.CE
.RE
.sp
.TP
\fB$plot3d\fR colours \fIfill\fR \fIborder\fR
Configure the colours to use for polygon borders and inner area\&.
.RS
.TP
color \fIfill\fR (in)
The colour to use for filling the polygons\&.
.TP
color \fIborder\fR (in)
The colour to use for the border of the polygons\&.
.RE
.TP
\fB$plot3d\fR ribbon \fIyzpairs\fR
Plot a ribbon based on the pairs of yz-coordinates\&. The colours for
the ribbon itself and the edge are taken from the colours option\&.
.RS
.TP
list \fIyzpairs\fR (in)
List of pairs of yz-coordinates
.RE
.PP
.PP
For 3D ribbon plots:
.TP
\fB$plot3d\fR plot \fIyzpairs\fR
Plot a ribbon based on the pairs of yz-coordinates\&. The colours for
the ribbon itself and the edge are taken from the colours option\&.
.RS
.TP
list \fIyzpairs\fR (in)
List of pairs of yz-coordinates
.RE
.PP
.PP
For \fIxy plots\fR, \fIstripcharts\fR, \fIhistograms\fR and \fIpolar plots\fR:
.TP
\fB$xyplot\fR dataconfig \fIseries\fR \fB-option\fR \fIvalue\fR \&.\&.\&.
Set the value for one or more options regarding the drawing of data of
a specific series\&.
.RS
.TP
string \fIseries\fR (in)
Name of the data series whose configuration we are changing\&.
.RE
.sp
The following options are allowed:
.RS
.TP
\fBcolour\fR c
.TP
\fBcolor\fR c
The colour to be used when drawing the data series\&.
.TP
\fBtype\fR enum
The drawing mode chosen for the series\&.
This can be one of \fBline\fR, \fBsymbol\fR, or \fBboth\fR\&.
.TP
\fBsymbol\fR enum
What kind of symbol to draw\&. The value of this option is ignored when
the drawing mode \fBline\fR was chosen\&. This can be one of
\fBplus\fR, \fBcross\fR, \fBcircle\fR, \fBup\fR (triangle
pointing up), \fBdown\fR (triangle pointing down), \fBdot\fR
(filled circle), \fBupfilled\fR or \fBdownfilled\fR (filled
triangles)\&.
.TP
\fBradius\fR integer
The size of the radius of the symbol\&. The total width of the symbol will be
2 times the radius size\&. The default radius is 4\&.
.TP
\fBwidth\fR integer
The width of the line (if drawn) or the width of the polygon outline (if -filled)\&.
.TP
\fBfilled\fR enum
Whether to fill the area above or below the data line or not\&. Can be one
of: \fBno\fR, \fBup\fR or \fBdown\fR (\fBSPECIAL EFFECTS\fR)
.TP
\fBfillcolour\fR colour
Colour to use when filling the area associated with the data line\&.
.TP
\fBstyle\fR enum
The style to be used for histograms:
.RS
.IP \(bu
\fBfilled\fR: Fill the area under the data points with bars (default)
.IP \(bu
................................................................................
.RE
.RE
.PP
.PP
For \fIpiecharts\fR and \fIspiral pies\fR:
.TP
\fB$pie\fR plot \fIdata\fR
Fill a piechart\&.
.RS
.TP
list \fIdata\fR (in)
A list of pairs (labels and values)\&. The values determine the relative
size of the circle segments\&. The labels are drawn beside the circle\&.
.RE
.TP
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR \&.\&.\&.
Set the colours to be used\&.
.RS
.TP
color \fIcolour1\fR (in)
The first colour\&.
.TP
color \fIcolour2\fR (in)
The second colour, and so on\&.
.RE
.TP
\fB$pie\fR explode \fIsegment\fR
Explode a segment (that is: move one segment out of the circle)\&. If the segment is
indicated as "auto", then you can click on a segment\&. This will be exploded instead of
any previously exploded segment\&.
.RS
.TP
int \fIsegment\fR
The segment to be exploded or "auto" if you want to do this interactively\&.
.RE
.PP
.PP
For \fIradial charts\fR:
.TP
\fB$radial\fR plot \fIdata\fR \fIcolour\fR \fIthickness\fR
Draw a new line in the radial chart
.RS
.TP
list \fIdata\fR (in)
A list of data (one for each spoke)\&. The values determine the distance
from the centre of the line connecting the spokes\&.
.TP
color \fIcolour\fR (in)
The colour for the line\&.
.TP
int \fIthickness\fR (in)
An optional argument for the thickness of the line\&.
.RE
.TP
\fB$pie\fR colours \fIcolour1\fR \fIcolour2\fR \&.\&.\&.
Set the colours to be used\&.
.RS
.TP
color \fIcolour1\fR (in)
The first colour\&.
.TP
color \fIcolour2\fR (in)
The second colour, and so on\&.
.RE
.PP
.PP
For \fIvertical barcharts\fR:
.TP
\fB$barchart\fR plot \fIseries\fR \fIydata\fR \fIcolour\fR ?dir? ?brightness?
Add a data series to a barchart\&.
.RS
.TP
string \fIseries\fR (in)
Name of the series the values belong to\&.
.TP
list \fIydata\fR (in)
A list of values, one for each x-axis label\&.
.TP
color \fIcolour\fR (in)
The colour of the bars\&.
.TP
string \fIdir\fR (in)
If given, "top-down" or "bottom-up", to indicate the direction in which the colour changes\&.
(If not given, a uniform colour is used)\&.
.TP
string \fIbrightness\fR (in)
If given, "bright" or "dark" (defaulting to "bright")\&. The colour will change to respectively
white or black, depending on the direction\&.
.RE
.TP
\fB$barchart\fR config \fB-option\fR \fIvalue\fR \&.\&.\&.
Set options for drawing the bars\&.
.RS
.TP
\fBshowvalues\fR boolean
Whether to show the values or not (above the bars)
.TP
\fBvaluefont\fR newfont
Name of the font to use for the values
................................................................................
Format string to use for formatting the values
.RE
.PP
.PP
For \fIhorizontal barcharts\fR:
.TP
\fB$barchart\fR plot \fIseries\fR \fIxdata\fR \fIcolour\fR ?dir? ?brightness?
Add a data series to a barchart\&.
.RS
.TP
string \fIseries\fR (in)
Name of the series the values belong to\&.
.TP
list \fIxdata\fR (in)
A list of values, one for each y-axis label\&.
.TP
color \fIcolour\fR (in)
The colour of the bars\&.
.TP
string \fIdir\fR (in)
If given, "left-right" or "right-left", to indicate the direction in which the colour changes\&.
(If not given, a uniform colour is used)\&.
.TP
string \fIbrightness\fR (in)
If given, "bright" or "dark" (defaulting to "bright")\&. The colour will change to respectively
white or black, depending on the direction\&.
.RE
.TP
\fB$barchart\fR config \fB-option\fR \fIvalue\fR \&.\&.\&.
Set options for drawing the bars\&.
.RS
.TP
\fBshowvalues\fR boolean
Whether to show the values or not (to the right of the bars)
.TP
\fBvaluefont\fR newfont
Name of the font to use for the values
................................................................................
Format string to use for formatting the values
.RE
.PP
.PP
For \fI3D barcharts\fR:
.TP
\fB$barchart\fR plot \fIlabel\fR \fIyvalue\fR \fIcolour\fR
Add the next bar to the barchart\&.
.RS
.TP
string \fIlabel\fR (in)
The label to be shown below the column\&.
.TP
float \fIyvalue\fR (in)
The value that determines the height of the column
.TP
color \fIcolour\fR (in)
The colour of the column\&.
.RE
.TP
\fB$barchart\fR config \fB-option\fR \fIvalue\fR \&.\&.\&.
Set one or more configuration parameters\&. The following options are
supported:
.RS
.TP
\fBusebackground\fR boolean
Whether to draw walls to the left and to the back of the columns or not
.TP
\fBuseticklines\fR boolean
................................................................................
Plot the given xy-pairs as a ribbon in the chart
.RS
.TP
list \fIxypairs\fR (in)
The pairs of x/y values to be drawn (the series is drawn as a whole)
.TP
color \fIcolour\fR (in)
The colour of the ribbon\&.
.RE
.TP
\fB$ribbon\fR area \fIxypairs\fR \fIcolour\fR
Plot the given xy-pairs as a ribbon with a filled area in front\&. The
effect is that of a box with the data as its upper surface\&.
.RS
.TP
list \fIxypairs\fR (in)
The pairs of x/y values to be drawn (the series is drawn as a whole)
.TP
color \fIcolour\fR (in)
The colour of the ribbon/area\&.
.RE
.PP
For \fIboxplots\fR:
.TP
\fB$boxplot\fR plot \fIseries\fR \fIlabel\fR \fIvalues\fR
Add a box-and-whisker to the plot\&. The dataconfig command can be used to customize
the box-and-whisker (see the box-and-whiskers command for the xyplot for details)\&.
.RS
.TP
string \fIseries\fR (in)
Name of the data series the box belongs to
.TP
string \fIlabel\fR (in)
The label along the x- or y-axis to which the data belong
.TP
list \fIvalues\fR (in)
List of raw values, the extent of the box and the whiskers will be
determined from this list\&.
.RE
.PP
For \fItimecharts\fR:
.TP
\fB$timechart\fR period \fItext\fR \fItime_begin\fR \fItime_end\fR \fIcolour\fR
Add a time period to the chart\&.
.RS
.TP
string \fItext\fR (in)
The text describing the period\&.
.TP
string \fItime_begin\fR (in)
Start time of the period\&.
.TP
string \fItime_end\fR (in)
Stop time of the period\&.
.TP
color \fIcolour\fR (in)
The colour of the bar (defaults to black)\&.
.RE
.sp
.TP
\fB$timechart\fR milestone \fItext\fR \fItime\fR \fIcolour\fR
Add a \fImilestone\fR (represented as an point-down triangle) to the
chart\&.
.RS
.TP
string \fItext\fR (in)
The text describing the milestone\&.
.TP
string \fItime\fR (in)
Time at which the milestone must be positioned\&.
.TP
color \fIcolour\fR (in)
The colour of the triangle (defaults to black)\&.
.RE
.sp
.TP
\fB$timechart\fR vertline \fItext\fR \fItime\fR
Add a vertical line (to indicate the start of the month for instance)
to the chart\&.
.RS
.TP
string \fItext\fR (in)
The text appearing at the top (an abbreviation of the
date/time for instance)\&.
.TP
string \fItime\fR (in)
Time at which the line must be positioned\&.
.RE
.TP
\fB$timechart\fR hscroll \fIscrollbar\fR
Connect a horizontal scrollbar to the chart\&. See also the section on
scrolling\&.
.RS
.TP
widget \fIscrollbar\fR (in)
The horizontal scrollbar that is to be connected to the chart
.RE
.TP
\fB$timechart\fR vscroll \fIscrollbar\fR
Connect a vertical scrollbar to the chart\&. See also the section on
scrolling\&.
.RS
.TP
widget \fIscrollbar\fR (in)
The vertical scrollbar that is to be connected to the chart
.RE
.PP
.PP
For \fIGantt charts\fR:
.TP
\fB$ganttchart\fR task \fItext\fR \fItime_begin\fR \fItime_end\fR \fIcompleted\fR
Add a task with its period and level of completion to the chart\&. Returns
a list of canvas items that can be used for further manipulations, like
connecting two tasks\&.
.RS
.TP
string \fItext\fR (in)
The text describing the task\&.
.TP
string \fItime_begin\fR (in)
Start time of the task\&.
.TP
string \fItime_end\fR (in)
Stop time of the task\&.
.TP
float \fIcompleted\fR (in)
The percentage of the task that is completed\&.
.RE
.sp
.TP
\fB$ganttchart\fR milestone \fItext\fR \fItime\fR \fIcolour\fR
Add a \fImilestone\fR (represented as an point-down triangle) to the
chart\&.
.RS
.TP
string \fItext\fR (in)
The text describing the milestone\&.
.TP
string \fItime\fR (in)
Time at which the milestone must be positioned\&.
.TP
color \fIcolour\fR (in)
The colour of the triangle (defaults to black)\&.
.RE
.sp
.TP
\fB$ganttchart\fR vertline \fItext\fR \fItime\fR
Add a vertical line (to indicate the start of the month for instance)
to the chart\&.
.RS
.TP
string \fItext\fR (in)
The text appearing at the top (an abbreviation of the
date/time for instance)\&.
.TP
string \fItime\fR (in)
Time at which the line must be positioned\&.
.RE
.sp
.TP
\fB$ganttchart\fR connect \fIfrom\fR \fIto\fR
Add an arrow that connects the \fIfrom\fR task with the \fIto\fR task\&.
.RS
.TP
list \fIfrom\fR (in)
The list of items returned by the "task" command that represents the
task from which the arrow starts\&.
.TP
string \fItext\fR (in)
The text summarising the tasks
.TP
list \fIargs\fR (in)
One or more tasks (the lists returned by the "task" command)\&. They are
shifted down to make room for the summary\&.
.TP
list \fIto\fR (in)
The list of items returned by the "task" command that represents the
task at which the arrow ends\&.
.RE
.sp
.TP
\fB$ganttchart\fR summary \fItext\fR \fIargs\fR
Add a summary item that spans all the tasks listed\&. The graphical
representation is a thick bar running from the leftmost task to the
rightmost\&.
.sp
Use this command before connecting the tasks, as the arrow would not be
shifted down!
.RS
.TP
string \fItext\fR (in)
The text summarising the tasks
.TP
list \fIargs\fR (in)
One or more tasks (the lists returned by the "task" command)\&. They are
shifted down to make room for the summary\&.
.RE
.sp
.TP
\fB$ganttchart\fR color \fIkeyword\fR \fInewcolor\fR
Set the colour of a part of the Gantt chart\&. These colours hold for all
items of that type\&.
.RS
.TP
string \fIkeyword\fR (in)
The keyword indicates which part of the Gantt chart to change:
.RS
.IP \(bu
description - the colour of the descriptive text
................................................................................
.IP \(bu
summary - the colour for the summary text
.IP \(bu
summarybar - the colour for the bar for a summary
.RE
.TP
string \fInewcolor\fR (in)
The new colour for the chosen items\&.
.RE
.sp
.TP
\fB$ganttchart\fR font \fIkeyword\fR \fInewfont\fR
Set the font of a part of the Gantt chart\&. These fonts hold for all
items of that type\&.
.RS
.TP
string \fIkeyword\fR (in)
The keyword indicates which part of the Gantt chart to change:
.RS
.IP \(bu
description - the font used for descriptive text
................................................................................
.IP \(bu
summary - the font used for summaries
.IP \(bu
scale - the font used for the time scale
.RE
.TP
string \fInewfont\fR (in)
The new font for the chosen items\&.
.RE
.TP
\fB$ganttchart\fR hscroll \fIscrollbar\fR
Connect a horizontal scrollbar to the chart\&. See also the section on
scrolling\&.
.RS
.TP
widget \fIscrollbar\fR (in)
The horizontal scrollbar that is to be connected to the chart
.RE
.TP
\fB$ganttchart\fR vscroll \fIscrollbar\fR
Connect a vertical scrollbar to the chart\&. See also the section on
scrolling\&.
.RS
.TP
widget \fIscrollbar\fR (in)
The vertical scrollbar that is to be connected to the chart
.RE
.PP
.PP
For \fIisometric plots\fR (to be extended):
.TP
\fB$isoplot\fR plot rectangle \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR \fIcolour\fR
Plot the outlines of a rectangle\&.
.RS
.TP
float \fIx1\fR (in)
Minimum x coordinate of the rectangle to be drawn\&.
.TP
float \fIy1\fR (in)
Minimum y coordinate of the rectangle\&.
.TP
float \fIx2\fR (in)
Maximum x coordinate of the rectangle to be drawn\&.
.TP
float \fIy2\fR (in)
Maximum y coordinate of the rectangle\&.
.TP
color \fIcolour\fR (in)
The colour of the rectangle\&.
.RE
.sp
.TP
\fB$isoplot\fR plot filled-rectangle \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR \fIcolour\fR
Plot a rectangle filled with the given colour\&.
.RS
.TP
float \fIx1\fR (in)
Minimum x coordinate of the rectangle to be drawn\&.
.TP
float \fIy1\fR (in)
Minimum y coordinate of the rectangle\&.
.TP
float \fIx2\fR (in)
Maximum x coordinate of the rectangle to be drawn\&.
.TP
float \fIy2\fR (in)
Maximum y coordinate of the rectangle\&.
.TP
color \fIcolour\fR (in)
The colour of the rectangle\&.
.RE
.sp
.TP
\fB$isoplot\fR plot circle \fIxc\fR \fIyc\fR \fIradius\fR \fIcolour\fR
Plot the outline of a circle\&.
.RS
.TP
float \fIxc\fR (in)
X coordinate of the circle's centre\&.
.TP
float \fIyc\fR (in)
Y coordinate of the circle's centre\&.
.TP
color \fIcolour\fR (in)
The colour of the circle\&.
.RE
.sp
.TP
\fB$isoplot\fR plot filled-circle \fIxc\fR \fIyc\fR \fIradius\fR \fIcolour\fR
Plot a circle filled with the given colour\&.
.RS
.TP
float \fIxc\fR (in)
X coordinate of the circle's centre\&.
.TP
float \fIyc\fR (in)
Y coordinate of the circle's centre\&.
.TP
color \fIcolour\fR (in)
The colour of the circle\&.
.RE
.PP
.PP
For \fItables\fR you can use the following subcommands:
.TP
\fB$table\fR row \fIitems\fR
Draw a single row of items\&. The appearance of the items can be
controlled explicitly via the format command\&.
.RS
.TP
list \fIitems\fR (in)
List of text items to be drawn, one per column
.RE
.TP
\fB$table\fR separator
Draw a horizontal line to separate two rows
.TP
\fB$table\fR formatcommand \fIprocname\fR
Set the procedure that controls the formatting of items\&. By default
items are simply drawn as centered text\&.
.RS
.TP
string \fIprocname\fR (in)
Name of the procedure to be used\&. Its signature is:
.CS


proc procname {table widget row column value} {\&.\&.\&.}

.CE
.IP
Use the cellconfigure subcommand to set the attributes per cell\&.
.RE
.TP
\fB$table\fR cellconfigure \fIargs\fR
Set the attributes for the next cell(s) to be drawn\&.
.RS
.TP
list \fIargs\fR (in)
Key-value pairs: -background sets the background colour of the cells,
-cell sets the foreground colour, -font sets the text font, -anchor sets
the position of the text within the cell and -justify controls the
layout of multiline text\&.
.RE
.PP
There are a number of public procedures that may be useful in specific
situations: \fIPro memorie\fR\&.
.SH "COORDINATE TRANSFORMATIONS"
Besides the commands that deal with the plots and charts directly,
there are a number of commands that can be used to convert world
coordinates to pixels and vice versa\&.
These include:
.TP
\fB::Plotchart::viewPort\fR \fIw\fR \fIpxmin\fR \fIpymin\fR \fIpxmax\fR \fIpymax\fR
Set the viewport for window \fIw\fR\&. Should be used in cooperation
with \fB::Plotchart::worldCoordinates\fR\&.
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question\&.
.TP
float \fIpxmin\fR (in)
Left-most pixel coordinate\&.
.TP
float \fIpymin\fR (in)
Top-most pixel coordinate (remember: the vertical pixel coordinate
starts with 0 at the top!)\&.
.TP
float \fIpxmax\fR (in)
Right-most pixel coordinate\&.
.TP
float \fIpymax\fR (in)
Bottom-most pixel coordinate\&.
.RE
.sp
.TP
\fB::Plotchart::worldCoordinates\fR \fIw\fR \fIxmin\fR \fIymin\fR \fIxmax\fR \fIymax\fR
Set the extreme world coordinates for window \fIw\fR\&. The world
coordinates need not be in ascending order (i\&.e\&. xmin can be larger
than xmax, so that a reversal of the x-axis is achieved)\&.
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question\&.
.TP
float \fIxmin\fR (in)
X-coordinate to be mapped to left side of viewport\&.
.TP
float \fIymin\fR (in)
Y-coordinate to be mapped to bottom of viewport\&.
.TP
float \fIxmax\fR (in)
X-coordinate to be mapped to right side of viewport\&.
.TP
float \fIymax\fR (in)
Y-coordinate to be mapped to top side of viewport\&.
.RE
.sp
.TP
\fB::Plotchart::world3DCoordinates\fR \fIw\fR \fIxmin\fR \fIymin\fR \fIzmin\fR \fIxmax\fR \fIymax\fR \fIzmax\fR
Set the extreme three-dimensional world coordinates for window
\fIw\fR\&. The world coordinates need not be in ascending order (i\&.e\&. xmin
can be larger than xmax, so that a reversal of the x-axis is
achieved)\&.
.RS
.TP
widget \fIw\fR (in)
Name of the window (canvas widget) in question\&.
.TP
float \fIxmin\fR (in)
X-coordinate to be mapped to front side of the 3D viewport\&.
.TP
float \fIymin\fR (in)
Y-coordinate to be mapped to left side of the viewport\&.
.TP
float \fIzmin\fR (in)
Z-coordinate to be mapped to bottom of viewport\&.
.TP
float \fIxmax\fR (in)
X-coordinate to be mapped to back side of viewport\&.
.TP
float \fIymax\fR (in)
Y-coordinate to be mapped to right side of viewport\&.
.TP
float \fIzmax\fR (in)
Z-coordinate to be mapped to top side of viewport\&.
.RE
.sp
.TP
\fB::Plotchart::coordsToPixel\fR \fIw\fR \fIx\fR \fIy\fR
Return a list of pixel coordinates valid for the given window\&.
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question\&.
.TP
float \fIx\fR (in)
X-coordinate to be mapped\&.
.TP
float \fIy\fR (in)
Y-coordinate to be mapped\&.
.RE
.sp
.TP
\fB::Plotchart::coords3DToPixel\fR \fIw\fR \fIx\fR \fIy\fR \fIz\fR
Return a list of pixel coordinates valid for the given window\&.
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question\&.
.TP
float \fIx\fR (in)
X-coordinate to be mapped\&.
.TP
float \fIy\fR (in)
Y-coordinate to be mapped\&.
.TP
float \fIy\fR (in)
Z-coordinate to be mapped\&.
.RE
.sp
.TP
\fB::Plotchart::polarCoordinates\fR \fIw\fR \fIradmax\fR
Set the extreme polar coordinates for window \fIw\fR\&. The angle always
runs from 0 to 360 degrees and the radius starts at 0\&. Hence you only
need to give the maximum radius\&.
\fINote:\fR If the viewport is not square, this procedure will not
adjust the extremes, so that would result in an elliptical plot\&. The
creation routine for a polar plot always determines a square viewport\&.
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question\&.
.TP
float \fIradmax\fR (in)
Maximum radius\&.
.RE
.sp
.TP
\fB::Plotchart::polarToPixel\fR \fIw\fR \fIrad\fR \fIphi\fR
Wrapper for a call to \fB::Plotchart::coordsToPixel\fR, which assumes
the world coordinates and viewport are set appropriately\&. Converts
polar coordinates to pixel coordinates\&.
\fINote:\fR To be useful it should be accompanied by a matching
\fB::Plotchart::worldCoordinates\fR procedure\&. This is automatically
taken care of in the creation routine for polar plots\&.
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question\&.
.TP
float \fIrad\fR (in)
Radius of the point\&.
.TP
float \fIphi\fR (in)
Angle to the positive x-axis\&.
.RE
.sp
.TP
\fB::Plotchart::pixelToCoords\fR \fIw\fR \fIx\fR \fIy\fR
Return a list of world coordinates valid for the given window\&.
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question\&.
.TP
float \fIx\fR (in)
X-pixel to be mapped\&.
.TP
float \fIy\fR (in)
Y-pixel to be mapped\&.
.RE
.TP
\fB::Plotchart::pixelToIndex\fR \fIw\fR \fIx\fR \fIy\fR
Return the index of the pie segment containing the pixel coordinates
(x,y)
.RS
.TP
widget \fIw\fR (in)
Name of the canvas alias (as returned by [\\$anyplot canvas]) in question,
holding a piechart\&.
.TP
float \fIx\fR (in)
X-pixel to be mapped\&.
.TP
float \fIy\fR (in)
Y-pixel to be mapped\&.
.RE
.PP
.PP
Furthermore there is a routine to determine "pretty" numbers for use
with an axis:
.TP
\fB::Plotchart::determineScale\fR \fIxmin\fR \fIxmax\fR \fIinverted\fR
Determine "pretty" numbers from the given range and return a list
containing the minimum, maximum and stepsize that can be used for a
(linear) axis\&.
.RS
.TP
float \fIxmin\fR (in)
Rough minimum value for the scaling
.TP
float \fIxmax\fR (in)
Rough maximum value for the scaling\&.
.TP
boolean \fIinverted\fR (in)
Optional argument: if 1, then the returned list produces an
inverted axis\&. Defaults to 0 (the axis will be from minimum to maximum)
.RE
.TP
\fB::Plotchart::determineScaleFromList\fR \fIvalues\fR \fIinverted\fR
Determine "pretty" numbers from the given list of values and return a list
containing the minimum, maximum and stepsize that can be used for a
(linear) axis\&.
.RS
.TP
float \fIvalues\fR (in)
List of values that will be examined\&. May contain missing values (empty strings)
.TP
boolean \fIinverted\fR (in)
Optional argument: if 1, then the returned list produces an
inverted axis\&. Defaults to 0 (the axis will be from minimum to maximum)
.RE
.PP
.SH "MISSING VALUES"
Often data that need to be plotted contain gaps - in a series of
measurement data, they can occur because the equipment failed, a sample
was not collected correctly or for many other reasons\&. The
\fIPlotchart\fR handles these gaps by assuming that one or both
coordinates of such data points are an empty string:
.CS


    #
    # Create the plot with its x- and y-axes
    #
    set s [::Plotchart::createXYPlot \&.c {0\&.0 100\&.0 10\&.0} {0\&.0 100\&.0 20\&.0}]

    foreach {x y} {0\&.0 32\&.0 10\&.0 {} 25\&.0 60\&.0 78\&.0 11\&.0 } {
        $s plot series1 $x $y
    }

.CE
The effect varies according to the type of plot:
.IP \(bu
For xy-plots, radial plots and strip charts the missing data point
causes a gap in the line through the points\&.
.IP \(bu
For barchats, missing values are treated as if a value of zero was
given\&.
.IP \(bu
For time charts and Gantt charts missing values cause errors - there is
no use for them there\&.
.PP
.SH "OTHER OUTPUT FORMATS"
Besides output to the canvas on screen, the module is capable, via
\fBcanvas postscript\fR, of producing PostScript files\&. One may wonder
whether it is possible to extend this set of output formats and the
answer is "yes"\&. This section tries to sum up the aspects of using this
module for another sort of output\&.
.PP
One way you can create output files in a different format, is by
examining the contents of the canvas after everything has been drawn and
render that contents in the right form\&. This is probably the easiest
way, as it involves nothing more than the re-creation of all the
elements in the plot that are already there\&.
.PP
The drawback of that method is that you need to have a display, which is
not always the case if you run a CGI server or something like that\&.
.PP
An alternative is to emulate the canvas command\&. For this to work, you
need to know which canvas subcommands are used and what for\&. Obviously,
the \fIcreate\fR subcommand is used to create the lines, texts and
other items\&. But also the \fIraise\fR and \fIlower\fR subcommands are
used, because with these the module can influence the drawing order -
important to simulate a clipping rectangle around the axes\&. (The routine
DrawMask is responsible for this - if the output format supports proper
clipping areas, then a redefinition of this routine might just solve
this)\&.
.PP
Furthermore, the module uses the \fIcget\fR subcommand to find out the
sizes of the canvas\&. A more mundane aspect of this is that the module
currently assumes that the text is 14 pixels high and that 80 pixels in
width suffice for the axis' labels\&. No "hook" is provided to customise
this\&.
.PP
In summary:
.IP \(bu
Emulate the \fIcreate\fR subcommand to create all the items in the
correct format
.IP \(bu
Emulate the \fIcget\fR subcommand for the options -width and -height to
allow the correct calculation of the rectangle's position and size
.IP \(bu
Solve the problem of \fIraising\fR and \fIlowering\fR the items so
that they are properly clipped, for instance by redefining the
routine DrawMask\&.
.IP \(bu
Take care of the currently fixed text size properties
.PP
.SH "SPECIAL EFFECTS"
As an example of some special effects you can achieve, here is the
code for a plot where the area below the data line varies in colour:
.CS


canvas \&.c  -background white -width 400 -height 200
pack \&.c -fill both

set s [::Plotchart::createXYPlot \&.c {0\&.0 100\&.0 10\&.0} {0\&.0 100\&.0 20\&.0}]

$s background gradient green top-down

$s dataconfig series1 -filled up -fillcolour white

$s plot series1  0\&.0 20\&.0
$s plot series1 10\&.0 20\&.0
$s plot series1 30\&.0 50\&.0
$s plot series1 35\&.0 45\&.0
$s plot series1 45\&.0 25\&.0
$s plot series1 75\&.0 55\&.0
$s plot series1 100\&.0 55\&.0

$s plaintext 30\&.0 60\&.0 "Peak" south

.CE
The trick is to fill the background with a colour that changes from
green at the top to white at the bottom\&. Then the area above the data
line is filled with a white polygon\&. Thus the green shading varies with
the height of the line\&.
.SH "ROOM FOR IMPROVEMENT"
In this version there are a lot of things that still need to
be implemented:
.IP \(bu
More robust handling of incorrect calls (right now the procedures may
fail when called incorrectly):
.RS
.IP \(bu
The axis drawing routines can not handle inverse axes right now\&.
.IP \(bu
If the user provides an invalid date/time string, the routines simply
throw an error\&.
.RE
.PP
.SH RESIZING
\fBPlotchart\fR has not been designed to create plots and charts
that keep track of the data that are put in\&. This means that if an
application needs to allow the user to resize the window holding the
plot or chart, it must take care to redraw the complete plot\&.
.PP
The code below is a simple example of how to do that:
.CS


package require Plotchart

grid [canvas \&.c -background white] -sticky news
grid columnconfigure \&. 0 -weight 1
grid rowconfigure \&. 0 -weight 1

bind \&.c <Configure> {doResize}

proc doPlot {} {
    #
    # Clean up the contents (see also the note below!)
    #
    \&.c delete all

    #
    # (Re)draw the bar chart
    #
    set p [::Plotchart::createBarchart \&.c {x y z} {0 100 10} 3]
    $p plot R {10 30 40} red
    $p plot G {30 40 60} green
}

proc doResize {} {
    global redo

    #
    # To avoid redrawing the plot many times during resizing,
    # cancel the callback, until the last one is left\&.
    #
    if { [info exists redo] } {
        after cancel $redo
    }

    set redo [after 50 doPlot]
}
.CE
\fIPlease note:\fR
The code above will work fine for barcharts and many other types of
plots, but as \fBPlotchart\fR keeps some private information for
xy plots, more is needed in these cases\&. This actually requires a
command "destroyPlot" to take care of such details\&. A next version
of \fBPlotchart\fR may have that\&.
.PP
Alternatively, you can use the \fBxyplot\fR package which is built
on top of Plotchart\&. This package supports zooming in and zooming out,
as well as resizing the plot as a whole\&. Here is a small demonstration
program:
.CS


# xyplot_demo\&.tcl --
#     Demonstration of the xyplot package
#

package require xyplot

set xydata1 {}
set xydata2 {}
set xydata3 {}
set xydata4 {}
for { set i 0 } { $i < 1024 } { incr i } {
    lappend xydata1 [expr {$i-1000}] [expr {$i * sin($i/4096\&.0*3\&.1415*2) * (sin($i/256\&.0*3\&.1415*2))}]
    lappend xydata2 [expr {$i-1000}] [expr {$i * sin($i/4096\&.0*3\&.1415*2) * (sin($i/256\&.0*3\&.1415*2) + 0\&.25 * sin($i/256\&.0*3\&.1415*6))}]
    lappend xydata3 [expr {$i-1000}] [expr {$i * sin($i/4096\&.0*3\&.1415*2) * (sin($i/256\&.0*3\&.1415*2) + 0\&.25 * sin($i/256\&.0*3\&.1415*6) + 0\&.0625 * sin($i/256\&.0*3\&.1415*10))}]
    lappend xydata4 [expr {$i-1000}] [expr {$i * sin($i/4096\&.0*3\&.1415*2) * (sin($i/256\&.0*3\&.1415*2) + 0\&.25 * sin($i/256\&.0*3\&.1415*6) + 0\&.0625 * sin($i/256\&.0*3\&.1415*10) + 0\&.015625 * sin($i/256\&.0*3\&.1415*14))}]
}

set xyp [xyplot \&.xyp -xformat "%5\&.0f" -yformat "%5\&.0f" -title "XY plot testing" -background gray90]
pack $xyp -fill both -expand true

set s1 [$xyp add_data sf1 $xydata1 -legend "Serie 1 data" -color red]
set s2 [$xyp add_data sf2 $xydata2 -legend "Serie 2 data" -color green]
set s3 [$xyp add_data sf3 $xydata3 -legend "Serie 3 data" -color blue]
set s4 [$xyp add_data sf4 $xydata4 -legend "Serie 4 data" -color orange]

set xyp2 [xyplot \&.xyp2 -xticks 8 -yticks 4 -yformat %\&.2f -xformat %\&.0f]
pack $xyp2 -fill both -expand true

set s1 [$xyp2 add_data sf1 $xydata1]
set s2 [$xyp2 add_data sf2 $xydata2]
set s3 [$xyp2 add_data sf3 $xydata3]
set s4 [$xyp2 add_data sf4 $xydata4]

.CE
Zooming in is done by selecting a rectangle with the left mouse button
pressed\&. Zooming out is done by pressing the right mouse button\&. If you
resize the window, the canvases inside are resized too\&. If you zoom in,
you can scroll the plot via the scrollbars that are automatically
attached\&.
.SH "ZOOMING IN"
As the Plotchart package does not keep track of the data itself,
rescaling an existing plot - for instance when zooming in - would have
to be done by redefining the plot and redrawing the data\&. However, the
canvas widget offers a way out by scaling and moving items, so that
zooming in becomes a bit simpler\&.
.PP
Whether zooming is indeed useful, depends on the type of plot\&. Currently
it is defined for XY-plots only\&. The method is called "rescale" and
simply redraws the axes and scales and moves the data items so that they
conform to the new axes\&. The drawback is that any symbols are scaled by
the same amount\&. The rescale method works best for plots that only have
lines, not symbols\&.
.PP
The method works very simply:
.CS


   $p rescale {newxmin newxmax newxstep} {newymin newymax newystep}

.CE
.SH "CONFIGURATION OPTIONS"
The commands \fBplotconfig\fR and \fBplotstyle\fR can be used to set all
manner of options\&. The syntax is:
.TP
\fB::Plotchart::plotconfig\fR \fIcharttype\fR \fIcomponent\fR \fIproperty\fR \fIvalue\fR
Set a new value for the property of a component in a particular chart or
plot type or query its current value\&. Changed properties only have effect for
the consecutive plots, not for the ones already created\&. Each argument is optional\&.
.sp
\fINote:\fR The \fBplotstyle\fR command offers a more
flexible way to control the configuration options\&.
.RS
.TP
string \fIcharttype\fR (in)
The type of chart or plot (see the configuration type that is mentioned
for each create command)\&. If not given or empty, a list of chart types
is returned\&. If it is given, the properties for that particular type are
used\&.
.TP
string \fIcomponent\fR (in)
The component of the plot/chart: leftaxis, rightaxis, background, margin
and so on\&. If not given or empty, a list of components is returned\&. If
it is given, the properties for that particular component will be set
for that particular type of chart\&.
.TP
string \fIproperty\fR (in)
The property of the component of the plot/chart: textcolor, thickness of
the axis line, etc\&. If not given or empty, a list of properties is returned\&. If
it is given, that particular property for that particular component
will be set for that particular type of chart\&.
.TP
string \fIvalue\fR (in)
The new value for the property\&. If empty, the current value is returned\&.
If the value is "default", the default value will be restored\&.
.sp
Note, that in some cases an empty value is useful\&. Use "none" in this
case - it can be useful for colours and for formats\&.
.RE
.TP
\fB::Plotchart::plotstyle\fR \fIsubcmd\fR \fIstyle\fR \fIargs\fR
Manipulate the \fIstyle\fR in which subsequent plots will be drawn\&. The
default style is "default", but you can define and load any number of
other styles\&.
.RS
.TP
string \fIsubcmd\fR (in)
The subcommand to be executed:
.RS
.IP \(bu
\fIconfigure\fR - this subcommand allows you to set the options per chart type\&.
It takes the same options as the \fBplotconfig\fR command\&.
.IP \(bu
\fIcurrent\fR - return the current style
.IP \(bu
\fIload\fR - make the given style the active style for subsequent plots and charts
.IP \(bu
\fInames\fR - return the list of currently defined styles
.RE
................................................................................
.PP
Below is a detailed list of the components and properties:
.IP \(bu
Axes come in a wide variety:
.RS
.IP \(bu
leftaxis, rightaxis, topaxis, bottomaxis for the plots with a
rectangular shape\&.
.IP \(bu
xaxis, yaxis and zaxis are used for the 3D plots
.IP \(bu
axis, this represents the radial and tangential axes of a polar plot
.RE
.IP
All axes have the following properties:
.RS
.IP \(bu
color - the colour of the line and the tickmarks
.IP \(bu
thickness - the width of the line of the axis itself, not the tickmarks
.IP \(bu
ticklength - the length of the tickmarks in pixels\&. A positive value is
outward, a negative value is inward\&.
.IP \(bu
font - the font for the labels and the text at the axis
.IP \(bu
format - the format for rendering the (numerical) labels\&. For the time
axis it is the format for a date and time\&.
.IP \(bu
textcolor - the colour for the labels and the text\&.
.IP \(bu
labeloffset - space (in pixels) between the tickmark and the actual label
.IP \(bu
minorticks - number of minor tickmarks between the major tickmarks
.IP \(bu
shownumbers - show the numbers/labels or not\&.
.IP \(bu
showaxle - show the axis line or not\&.
.RE
.IP \(bu
The \fImargin\fR is important for the layout\&. Currently only the
rectangular plots allow the margins to be set: left, right, top and bottom\&.
The values are in pixels\&.
.IP \(bu
The \fItext\fR component is meant for any text appearing via the
plaintext subcommand\&. The properties are: textcolor, font and anchor
(positioning of the text relative to the given coordinates)\&.
.IP \(bu
The \fIbackground\fR has two properties: outercolor, the colour outside
of the actual plot, and innercolor, the colour inside the plot\&. (Note:
only "outercolor" has now been implemented)\&.
.IP \(bu
The \fImask\fR has one property only: draw\&. If set to 1, the default, white rectangles
are drawn to mimick the effects of clipping - excess data are made invisible this way\&.
Otherwise these rectangles are not drawn\&. This is useful to control
the layout more tightly, for instance with multiple plots in one canvas\&.
.IP \(bu
The \fItitle\fR component has the same properties as the \fItext\fR component
(but it is independent of that component)\&. It also has a \fIbackground\fR property:
If not set (or set to the empty string) this is the same as the outercolor property
of the \fIbackground\fR component, otherwise it is a separate colour\&.
.IP \(bu
The \fIlegend\fR has three properties: background, border and position\&.
See the legend subcommand for the meaning\&.
.IP \(bu
The \fIbar\fR components is used for all barchart-like plots and has
three properties: \fIbarwidth\fR (relative width of the bars in
relation to the items along the axis), \fIinnermargin\fR (the
relative width of the gaps between bars or groups of bars) and
the \fIoutline\fR colour\&.
.IP \(bu
The \fIlabels\fR component is used to describe the appearance of the
labels of piecharts and "spiral" piecharts\&. The properties are:
.RS
.IP \(bu
textcolor - colour of the label text
.IP \(bu
font - font to be used for the label text
.IP \(bu
placement - \fIout\fR of the circle or \fIin\fR the circle
................................................................................
.IP \(bu
sorted - the data are sorted in ascending order first
.IP \(bu
shownumbers - the labels are combined with the numbers according to the
format
.IP \(bu
format - the format to be used (defaults to: "%s (%g)")
if the numbers are to shown\&. The format command gets the label first,
then the number)
.IP \(bu
formatright - if given, the format to be used for labels and numbers
appearing to the right of the pie\&. The format command gets the
number first, then the label\&. (Defaults to "")
.RE
.IP \(bu
The \fIslice\fR component has properties to control the appearance of
the sections in the pie diagram:
.RS
.IP \(bu
outline - the colour of the line around the slices (default: black)
.IP \(bu
outlinewidth - width of the line around the slices (default: 1 pixel)
.IP \(bu
startangle - the angle w\&.r\&.t\&. positive x-axis where the first slice
starts
.IP \(bu
direction - the direction in which to draw the slices (default: +, that
is clockwise)
.RE
.IP \(bu
The table charts use the general components \fItitle\fR and \fImargin\fR
and further more the specific components \fIheader\fR, \fIoddrow\fR,
\fIevenrow\fR, \fIcell\fR and \fIframe\fR:
.RS
.IP \(bu
\fIheader\fR, \fIoddrow\fR and \fIevenrow\fR have the properties:
\fIbackground\fR, \fIfont\fR, \fIcolor\fR, \fIheight\fR and
\fIanchor\fR with obvious meanings\&.
.IP \(bu
The \fIcell\fR component defines in addition \fIleftspace\fR,
\fIrightspace\fR and \fItopspace\fR for fine-grained control of the spacing
inside the cell\&. These are not set via the \fIcellconfigure\fR
subcommand however\&.
.IP \(bu
Finally the \fIframe\fR component uses \fIcolor\fR, \fIouterwidth\fR
(for the width of the line surrounding the whole table) and
\fIinnerwidth\fR (for the width of lines separating columns and rows)\&.
.RE
.PP
See the examples in plotdemos7\&.tcl for its use\&.
.SH "SCROLLING FOR TIMECHARTS AND GANTT CHARTS"
For two types of plots automatic scrolling management has been
implemented: timecharts and Gantt charts\&. The subcommands \fIhscroll\fR
and \fIvscroll\fR associate (existing) scrollbars to the plot, in much
the same way as for text and canvas widgets\&.
.PP
Once the association is made, the scrollbars are automatically
updated if:
.IP \(bu
You add an item with a period wider than the current one\&.
.IP \(bu
You add a vertical line for a time beyond the current bounds\&.
.IP \(bu
You add an extra item beyond the number that was used to create the
chart\&.
.PP
For instance:
.CS


package require Plotchart

canvas \&.c -width 400 -height 200
scrollbar \&.y -orient vertical
scrollbar \&.x -orient horizontal

grid \&.c \&.y -sticky news
grid \&.x    -sticky news

source plotchart\&.tcl

set s [::Plotchart::createTimechart \&.c "1 january 2004"  "31 december 2004" 4]

$s period "Spring" "1 march 2004" "1 june 2004" green
$s period "Summer" "1 june 2004" "1 september 2004" yellow
$s vertline "1 jan" "1 january 2004"
$s vertline "1 apr" "1 april 2004"
$s vertline "1 jul" "1 july 2004"
$s vertline "1 oct" "1 october 2004"
................................................................................
$s milestone "Longest day 2" "21 july 2004"
$s milestone "Longest day 3" "21 july 2004"
$s milestone "Longest day 4" "21 july 2004"
$s milestone "Longest day 5" "21 july 2004"
$s milestone "Longest day 6" "21 july 2004"
$s title "Seasons (northern hemisphere)"

$s vscroll \&.y
$s hscroll \&.x

.CE
The original extent of the chart is from 1 january 2004 to 31 december
2004\&. But because of the addition of vertical lines in 2005 and
more items than was specified at the creation of the chart, both the
horizontal and the vertical scrollbar will be enabled\&.
.SH "SPECIALISED PLOTS"
Most of the plot and chart types described above have a fairly general use
and you simply prepares the data to be plotted yourself\&. This section describes
several plot types that are more specialised, in the sense that they have specific
purposes and you pass raw data that are then processed in the plotting routines\&.
.PP
Currently there are the following types:
.IP \(bu
Target diagrams are used to assess the capacity of numerical models to reproduce measurement
data\&. They are described in detail in:
.CS


Jason K\&. Joliff et al\&.
    Summary diagrams for coupled hydrodynamic-ecosystem model skill assessment
    Journal of Marine Systems 76 (2009) 64-82
    DOI: 10\&.1016/j\&.jmarsys\&.2008\&.05\&.014

.CE
.IP \(bu
Performance profiles are used for comparing the performance of numerical methods or
implementations thereof with each other\&. For more information:
.CS


Desmond Higham and Nicholas Higham
    Matlab Guide
    SIAM, 2005, Philadephia

.CE
.PP
Most of the general methods for XY-plots work for these plots as well, but their
creation and the methods to plot the data are very specific\&.
.TP
\fB::Plotchart::createTargetDiagram\fR \fIw\fR \fIlimits\fR \fIscale\fR
Create a new target diagram with circles indicating specific limits\&. The x-axis represents the
unbiased "root-mean-square difference" (typically varying between -1 and 1) and the y-axis
represents the normalised bias\&.
.sp
Data points closer to the origin represent better results than data points further away\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
list \fIlimits\fR (in)
List of radii for the circles that represent the limits (for instance: 0\&.5 and 0\&.7)
.TP
double \fIscale\fR (in)
Scale for the axes - defaults to 1, but if the model results are a poor fit, then
that may be too small a value\&. Both axes are scaled in the same way\&.
.RE
.sp
.TP
\fB$target\fR plot \fIseries\fR \fIxvalues\fR \fIyvalues\fR
The plot method takes two series of data of the same length, the first one
representing the model results, the second one represent the measurements
or, more general, the data that need to be reproduced\&.
.RS
.TP
string \fIseries\fR (in)
Name of the series (it will be plotted as a symbol that is configured via the
\fI$target dataconfig\fR command (see the XY-plot equivalent for an explanation)
.TP
list \fIxvalues\fR (in)
................................................................................
.TP
list \fIyvalues\fR (in)
List of measured values (missing values are represented as empty strings; only if
both the x and the y values are given, is the pair used in the computations)
.RE
.TP
\fB::Plotchart::createPerformanceProfile\fR \fIw\fR \fImax\fR
Create a diagram to show the performance of various numerical methods (or solvers)\&. The idea is
to first run these methods on a set of problems and measure their performance\&. The smaller the
number the better\&. Then these methods are compared via a so-called performance profile:
the data are scaled and ordered, such that the best method ends up highest\&.
.sp
Because of the nature of the plot all data must be given at once\&.
.RS
.TP
widget \fIw\fR (in)
Name of the \fIexisting\fR canvas widget to hold the plot\&.
.TP
float \fImax\fR (in)
Maximum value for the x-axis (the x-axis is the scaled performance of the series)\&.
.RE
.TP
\fB$performance\fR plot \fIseries_and_data_pairs\fR
Plot the data for each given method\&. The data are identified by the series name and the
appearance is controlled via prior dataconfig subcommand\&.
.RS
.TP
list \fIseries_and_data_pairs\fR (in)
List of series names and data\&. All data must be given at once\&.
.RE
.PP
The command \fIplotmethod\fR can be used to add new methods for a particular
plot or chart type\&. It is intended to help you develop specialised graphical displays\&.
.TP
\fB::Plotchart::plotmethod\fR \fIcharttype\fR \fImethodname\fR \fIplotproc\fR
Adds a new method for the given plot or chart type\&. The method is implemented by the
command or procedure given in the plotproc argument\&. The procedure will be called with
two extra arguments, the name of the created plot and the canvas widget that contains
(see the example below)\&.
.RS
.TP
string \fIcharttype\fR (in)
The type of plot or chart that the new method should be added to\&.
.TP
string \fImethodname\fR (in)
Name of the method to be used\&.
.TP
string \fIplotproc\fR (in)
Name of the command or procedure that implements the method\&.
.RE
.PP
.PP
Here is a trivial example of how to use this:
.CS


................................................................................
proc doodle {p w x y} {
    $p plaintext $x $y "DOODLE"
}
::Plotchart::plotmethod xyplot doodle doodle

#
# Use it
pack [canvas \&.c]

set p [::Plotchart::createXYPlot \&.c {0 100 10} {0 20 5}]

$p doodle 40 10

.CE
.SH "TABLE CHARTS"
To show what you can do with table charts, here is a simple example that
plots a number of random data\&. The colours depend on the range that the
data belong to\&. For this the procedure \fIsetColor\fR is used\&.
.CS


package require Plotchart

pack [canvas \&.c -bg white -height 300] -fill both -expand yes

::Plotchart::plotconfig table frame outerwidth 3
::Plotchart::plotconfig table frame color red

set t [::Plotchart::createTableChart \&.c {"Column 1" "Column 2" "Column 3"} 80]


proc setColor {table widget row col value} {
    $table cellconfigure -background white -color black
    if { $value < 2\&.0 } {
        $table cellconfigure -background red -color white
    }
    if { $value > 6\&.0 } {
        $table cellconfigure -background green
    }

    return [format "%6\&.3f" $value]
}

# Command must already exist \&.\&.\&.
$t formatcommand setColor

$t title "Demonstration of table charts"
$t separator

for {set i 0} {$i < 9} {incr i} {
    set row {}

    for {set j 0} {$j < 3} {incr j} {
        lappend row [expr {10\&.0 * rand()}]
    }

    if { $i == 3 } {
        $t separator
    }

    $t row $row
}
.CE
.SH "CONTROL DISPLAYS"
TODO
.SH "ARRANGING MULTIPLE PLOTS IN A CANVAS"
The command \fIplotpack\fR allows you to copy the contents of a plot
into another canvas widget\&. This canvas widget does not act as a
composite plot, but it can be saved as a PostScript file for instance:
Note: the command simply takes a snapshot of the plots/charts as they
are at that moment\&.
.TP
\fB::Plotchart::plotpack\fR \fIw\fR \fIdir\fR \fIargs\fR
Copy the contents of the plots/charts into another widget, in a manner
similar to the \fIpack\fR geometry manager\&.
.RS
.TP
widget \fIw\fR (in)
The name of the canvas widget to copy the plots/charts into
.TP
string \fIdir\fR (in)
The direction of the arrangement - top, left, bottom or right
.TP
list \fIargs\fR (in)
List of plots/charts to be copied\&.
.RE
.PP
For example:
.CS


    set p1 [createXYPlot \&.\&.\&.]
    set p2 [createBarchart \&.\&.\&.]

    \&.\&.\&. fill the plots \&.\&.\&.

    toplevel \&.t
    pack [canvas \&.t\&.c2 -width \&.\&.\&.]

    #
    # Copy the two plots above each other in the new canvas
    #
    plotpack \&.t\&.c2 top $p1 $p2

.CE
A different method is to use the \fI-box\fR and \fI-axesbox\fR options
when creating the plot\&. These control the area in the canvas where the
plot or chart will be drawn\&.
.PP
The \fI-box\fR option takes as its value a list of four numbers:
.IP \(bu
X-coordinate of the upper-left corner of the area that will contain the
plot or chart (simply a canvas coordinate)
.IP \(bu
Y-coordinate of the upper-left corner
.IP \(bu
Width of the area
.IP \(bu
Height of the area
.PP
Specifying the width and height makes it easier to reposition the area
with respect to other plots\&.
.PP
The \fI-axesbox\fR option is meant to make aligning the axes of a
plot with those of other plots easier\&. The option takes a list of
six arguments:
.IP \(bu
Identification of the plot with respect to which it should be
positioned (the command returned by the creation command)\&.
.IP \(bu
The anchor position that should be used (n, nw, \&.\&.\&.)
.IP \(bu
X-coordinate of the upper-left corner of the area that will contain the
plot or chart\&. This coordinates is taken relative to the
\fIanchor position\fR
.IP \(bu
Y-coordinate of the upper-left corner
.IP \(bu
Width of the axis area
.IP \(bu
Height of the axis area
.PP
With this option the area the axes occupy is first determined and the
complete area is derived from the margins\&.
.PP
For example:
.CS


    set p2 [::Plotchart::createXYPlot \&.c {0 10 1} {-5 5 2\&.5} -axesbox [list $p1 ne 0 0 200 200]]

.CE
will create a second plot whose left axis coincides with the right axis
of plot "\\$p1" and the top of the axis is at the same heigt as well -
because the axes are positioned at a point 0 pixels to the left and 0
pixels below the north-east corner\&.
.SH "INTERACTIVE USE"
\fIPlotchart\fR has several features for interactive use (cf\&. \fBNOTES ON TAGS\fR):
.IP \(bu
The legend can be moved around by pressing mouse button 1 in the legend's box and
keeping it down\&.
.IP \(bu
You can use the \fIbindplot\fR and \fIbindlast\fR commands to
define actions that are to be taken when the user clicks on an element of the plot or chart\&.
(see below, see also the sample code in plotdemos12\&.tcl)
.IP \(bu
\fIPiecharts\fR can show an "exploded" segment that you can select with mouse button 1\&.
.PP
If you require different forms of interaction, not covered by \fIPlotchart\fR itself,
you can use the tags on the various canvas elements to define other bindings\&.
.PP
The \fIbindplot\fR and \fIbindlast\fR are defined as follows:
.TP
\fB$anyplot\fR bindplot \fIevent\fR \fIcommand\fR \fIargs\fR
Register a command that will be run whenever the given event occurs in the plot\&.
.RS
.TP
string \fIevent\fR
The event that you want to bind the command to
.TP
string \fIcommand\fR
Name of the command/procedure that you want to run\&. The following arguments
are prefixed: the x- and y-coordinates of the point in the plot (the world coordinates!),
so that the procedure has the signature:
.CS


    cmd $xworld $yworld $string1 $string2 $string3

................................................................................
.CE
.IP
assuming the argument "command" is: {cmd A B C}
.RE
.TP
\fB$anyplot\fR bindlast \fIseries\fR \fIevent\fR \fIcommand\fR
Register a command that will be run when the event occurs within the neighbourhood of
the last point added to the given series\&. (You can use directly after inserting
a data point\&. All such commands will remain active)\&.
.RS
.TP
string \fIevent\fR
The event that you want to bind the command to
.TP
list \fIcommand\fR
Name of the command/procedure that you want to run\&. The following arguments
are prefixed: the x- and y-coordinates of the point in the plot (the world coordinates!),
so that the procedure has the signature:
.CS


    cmd $xworld $yworld $string1 $string2 $string3

.CE
.IP
assuming the argument "command" is: {cmd A B C}
.RE
.PP
Here is an example - show the values of the data points in an annotation
(from the sample code in plotdemos12\&.tcl):
.CS


#
# Procedure for showing an annotation
#
proc showAnnotation {xcoord ycoord plot w} {

    $plot balloon $xcoord $ycoord "Data point: [format "%\&.3f, %\&.3f" $xcoord $ycoord]" north

    after 2000 [list removeAnnotation $w]
}

#
# Procedure for erase an annotation
#
................................................................................
    $w delete BalloonText
    $w delete BalloonFrame
}

#
# Create a simple plot and a label
#
pack [canvas \&.c -bg white] [label \&.l -textvariable coords]

set p [::Plotchart::createXYPlot \&.c {0 1000 200} {0 10 1}]

$p dataconfig series1 -type both -symbol cross

foreach x {1 2 5 10 20 50 100 200 500 1000} {
    $p plot series1 $x [expr {log($x)}]

    #
................................................................................
    $p bindlast series1 <Enter> [list showAnnotation $p %W]
}

.CE
.SH "NOTES ON TAGS"
The implementation of \fIPlotchart\fR relies heavily on the canvas's
ability to identify graphical objects by tags and to change the drawing order of
the objects\&. This section documents the tags that are used\&.
.PP
(\fINote:\fR the tags are not always used consistently - see the notes appearing with
the various tags\&. This section describes the current state\&.)
.PP
\fIGeneral graphical objects:\fR
.IP \(bu
\fImask\fR - Used to manipulate the opaque rectangles that ensure data outside
the viewport are not shown\&.
.IP \(bu
\fItopmask, horizmask, vertmask\fR - specialised tags, used for scrollable plots\&.
.IP \(bu
\fItitle\fR - Used for title strings\&.
.IP \(bu
\fIBalloonText, BalloonFrame\fR - Used to manipulate balloon text\&.
.IP \(bu
\fIPlainText\fR - Used to manipulate ordinary text without any decoration\&.
.IP \(bu
\fIbackground\fR - Tag used for gradient and image backgrounds (and for gradient-filled bars)\&.
.IP \(bu
\fIxaxis, yaxis\fR - Tags used for all objects related to horizontal or vertical axes\&.
(also: both for numerical axes and axes with labels as in barcharts)\&.
Note, however, that the \fItext\fR along the axes has no particular tag\&.
.IP \(bu
\fIraxis\fR - Tag used for all objects related to a \fIright\fR axis\&.
.IP \(bu
\fItaxis\fR - Tag used for all objects related to a \fItime\fR axis\&.
.IP \(bu
\fIaxis3d\fR - Tag used for 3D axes
.IP \(bu
\fIxtickline, ytickline\fR - Tags used for ticklines\&.
.IP \(bu
\fIlegend, legengb, legendobj\fR - Tags used for the legend\&. The latter is used to manipulate
the legend as a whole\&.
.IP \(bu
\fIlegend_series\fR - Tag used to control the appearance of the legend entry ("series" should
be replaced by the series name)\&.
.IP \(bu
\fIobject\fR - used as standard tag for all objects drawn with the \fB::Plotchart::drawobject\fR
procedure\&. Tags given at object creation time are added to this tag\&.
.PP
\fIXY-plots (all types of axes):\fR
.IP \(bu
\fIdata\fR - The general tag to identify graphical objects associated with data\&.
\fIdata_seriesname\fR - The tag specific to a data series ("seriesname" should be replaced)\&.
\fIband\fR - The horizontal or vertical band drawn with the xband otr yband subcommands have this tag
by the actual name)\&.
\fIxtext\fR - The text labelling the xaxis\&.
\fIytext\fR - The text labelling hte yaxis horizontically\&.
\fIvtext\fR - The text labelling the yaxis vertically\&.
.PP
Items such as labelled dots only have the "data" tag\&.
.PP
\fIPiecharts and spiral pies:\fR
.IP \(bu
\fIsegment_segmentnumber\fR - The tag identifying the segment, the string "segmentnumber" should
be replaced by the actual number\&. This tag is used to explode the segments\&.
.PP
\fIBarcharts:\fR
.PP
Barcharts use the same tags as xy-plots (but for gradient-filled bars the data_seriesname is not used)\&.
.PP
\fIHistograms and isometric plots:\fR
.PP
Currently the only tag used is "data"\&.
.PP
\fITime-charts:\fR
.PP
As these plots are scrollable, several tags are used specific to the scrolling:
vertscroll, horizscroll, below, lowest, above, timeline, tline\&.
Each item also has a tag of the form "item_number",
where "number" is to be replaced by the actual sequence number of the item\&.
.PP
\fIGantt charts:\fR
.PP
In addition to the tags described for the time-charts, the following tags are used:
description, completed, summary and summarybar\&.
.PP
\fIRadial charts and polar plots:\fR
.PP
Currently the radial lines indicating the grid have no tags\&. The graphical objects associated with
data only have the "data" tag\&.
.PP
\fIWindroses:\fR
.PP
Only the tag \fIdata_number\fR is currently used ("number" should be replaced by the
sequence number of the data, starting at 0\&.
.PP
\fIContour and isoline plots:\fR
.PP
No tags are used\&.
.PP
\fI3D plots and 3D ribbon plots:\fR
.PP
No tags are used for the data objects, only for the axes\&.
.PP
\fICharts decorated with 3D effects:\fR
.PP
The following tags are used to identify various types of graphical objects: platform, background, d, u,
ticklines\&.
.PP
The text associated with the bars has no tags\&. The ribbon lines and areas have no tags either\&.
.PP
\fITables:\fR
.PP
Tags used are: frame, cellbg and celltext
\fIIn addition:\fR
To implement multiple plots and charts in a single canvas, all items
also get as a tag the plot/chart they belong to\&. This enables Plotchart
to manipulate only those items\&.
.SH "TODO - SOME PRIVATE NOTES"
I have the following wishlist:
.IP \(bu
Isometric plots - allow new items to be implemented easily\&.
.IP \(bu
A general 3D viewer - emphasis on geometry, not a ray-tracer\&.
.IP \(bu
Several improvements for boxplots:
.RS
.IP \(bu
Height of the box scales with the logarithm of the number of points
.IP \(bu
Marker line to indicate a "current" value
................................................................................
Box drawn from quantiles
.RE
.PP
.SH KEYWORDS
3D bars, 3D surfaces, bar charts, charts, coordinate transformations, coordinates, graphical presentation, isometric plots, pie charts, plotting, polar plots, strip charts, tables, time charts, xy-plots
.SH COPYRIGHT
.nf
Copyright (c) 2011 Arjen Markus <arjenmarkus@users\&.sourceforge\&.net>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/swaplist/swaplist.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "swaplist" n 0.1 tklib "A dialog which allows a user to move options between two lists"
.BS
.SH NAME
swaplist \- A dialog which allows a user to move options between two lists
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBTk  8.4\fR
.sp
package require \fBswaplist  ?0.1?\fR
.sp
\fB::swaplist::swaplist\fR \fIpathName\fR \fIvariable\fR \fIcompleteList\fR \fIselectedList\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides a dialog which consists of 2 listboxes, along with buttons to move items
between them and reorder the right list.
.PP
.TP
\fB::swaplist::swaplist\fR \fIpathName\fR \fIvariable\fR \fIcompleteList\fR \fIselectedList\fR ?options?
Creates a dialog which presents the user with a pair of listboxes. Items are selected by using the buttons to move
them to the right list. The contents of the right list are put in the \fIvariable\fR upon closure of the dialog.
The command returns a boolean indicating if the user pressed OK or not. If -geometry is not specified, the
dialog is centered in its parent toplevel unless its parent is . in which case the dialog is centered in the screen.
.sp
Options:
.RS
.TP
\fB-embed\fR
if this flag is supplied, the procedure will create a swaplist widget named \fIpathName\fR, with the \fIvariable\fR set as the
listvariable for the right side listbox. This flag will also cause the -title and -geometry flags to be ignored.
.TP
\fB-reorder\fR
boolean specifying if buttons allowing the user to change the order of the right listbox should appear or not. defaults to true
.TP
\fB-title\fR
sets the title of the dialog window. defaults to "Configuration"
.TP
\fB-llabel\fR
sets the heading above the left list. defaults to "Available:"
.TP
\fB-rlabel\fR
sets the heading above the right list. defaults to "Selected:"
.TP
\fB-lbuttontext\fR
sets the text on the "move left" button. defaults to "<<"
.TP
\fB-rbuttontext\fR
sets the text on the "move right" button. defaults to ">>"
.TP
\fB-ubuttontext\fR
sets the text on the "move up" button. defaults to "Move Up"
.TP
\fB-dbuttontext\fR
sets the text on the "move down" button. defaults to "Move Down"
.TP
\fB-geometry\fR
sets the geometry of the dialog window.
.RE
.PP
.SH EXAMPLE
.CS


package require swaplist
namespace import swaplist::*

if {[swaplist .slist opts "1 2 3 4 5 6 7 8 9" "1 3 5"]} {
    puts "user chose numbers: $ops"
}


.CE
.SH KEYWORDS
dialog, disjointlistbox, listbox
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/swaplist/swaplist\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "swaplist" n 0\&.1 tklib "A dialog which allows a user to move options between two lists"
.BS
.SH NAME
swaplist \- A dialog which allows a user to move options between two lists
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBTk  8\&.4\fR
.sp
package require \fBswaplist  ?0\&.1?\fR
.sp
\fB::swaplist::swaplist\fR \fIpathName\fR \fIvariable\fR \fIcompleteList\fR \fIselectedList\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides a dialog which consists of 2 listboxes, along with buttons to move items
between them and reorder the right list\&.
.PP
.TP
\fB::swaplist::swaplist\fR \fIpathName\fR \fIvariable\fR \fIcompleteList\fR \fIselectedList\fR ?options?
Creates a dialog which presents the user with a pair of listboxes\&. Items are selected by using the buttons to move
them to the right list\&. The contents of the right list are put in the \fIvariable\fR upon closure of the dialog\&.
The command returns a boolean indicating if the user pressed OK or not\&. If -geometry is not specified, the
dialog is centered in its parent toplevel unless its parent is \&. in which case the dialog is centered in the screen\&.
.sp
Options:
.RS
.TP
\fB-embed\fR
if this flag is supplied, the procedure will create a swaplist widget named \fIpathName\fR, with the \fIvariable\fR set as the
listvariable for the right side listbox\&. This flag will also cause the -title and -geometry flags to be ignored\&.
.TP
\fB-reorder\fR
boolean specifying if buttons allowing the user to change the order of the right listbox should appear or not\&. defaults to true
.TP
\fB-title\fR
sets the title of the dialog window\&. defaults to "Configuration"
.TP
\fB-llabel\fR
sets the heading above the left list\&. defaults to "Available:"
.TP
\fB-rlabel\fR
sets the heading above the right list\&. defaults to "Selected:"
.TP
\fB-lbuttontext\fR
sets the text on the "move left" button\&. defaults to "<<"
.TP
\fB-rbuttontext\fR
sets the text on the "move right" button\&. defaults to ">>"
.TP
\fB-ubuttontext\fR
sets the text on the "move up" button\&. defaults to "Move Up"
.TP
\fB-dbuttontext\fR
sets the text on the "move down" button\&. defaults to "Move Down"
.TP
\fB-geometry\fR
sets the geometry of the dialog window\&.
.RE
.PP
.SH EXAMPLE
.CS


package require swaplist
namespace import swaplist::*

if {[swaplist \&.slist opts "1 2 3 4 5 6 7 8 9" "1 3 5"]} {
    puts "user chose numbers: $ops"
}


.CE
.SH KEYWORDS
dialog, disjointlistbox, listbox
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/tkpiechart/canvaslabel.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvasLabel" n 6.6 tklib "canvasLabel class"
.BS
.SH NAME
canvasLabel \- tkpiechart canvas label class
.SH SYNOPSIS
package require \fBstooop  4.1\fR
.sp
package require \fBswitched  2.2\fR
.sp
package require \fBtkpiechart  6.6\fR
.sp
\fBstooop::new\fR \fBcanvasLabel\fR \fIcanvas\fR ?options?
.sp
\fBswitched::configure\fR \fIcanvasLabelObject\fR ?options?
.sp
\fBswitched::cget\fR \fIcanvasLabelObject\fR \fIoption\fR
.sp
\fBstooop::delete\fR \fIcanvasLabelObject\fR
.sp
.BE
.SH DESCRIPTION
The canvasLabel class brings some Tk label widget functionality to the canvas text item, such as a background and a border.
.PP
The canvasLabel is built with a bullet rectangle on the left side of the text. The relief changes according to the select state, with a traditionally sunken relief when selected.
.PP
The label has a specific tag, which can be used to retrieve the coordinates of the object or move it, thanks to the canvas facilities.
.TP
\fBstooop::new\fR \fBcanvasLabel\fR \fIcanvas\fR ?options?
Creates a canvasLabel object in the specified Tk canvas. The canvasLabel object identifier is returned (referred to as \fIcanvasLabelObject\fR in this document).
.TP
\fBswitched::configure\fR \fIcanvasLabelObject\fR ?options?
Configures a canvasLabel object or returns all the options with their current values if no options are passed as parameters.
.TP
\fBswitched::cget\fR \fIcanvasLabelObject\fR \fIoption\fR
Returns an option value for the specified canvasLabel object.
.TP
\fBstooop::delete\fR \fIcanvasLabelObject\fR
Deletes the specified canvasLabel object.
.PP
.SH OPTIONS
.TP
\fB-anchor\fR value
Specifies the anchor position of the rectangle and the text, relative to the positioning point. The behavior is similar to the \fB-anchor\fR option of the \fBcanvas\fR \fItext\fR item, except that the rectangle is taken into account. The default is \fIcenter\fR.
.TP
\fB-background\fR color
Specifies the background color of the bullet rectangle, as in the \fB-fill\fR option of the \fBcanvas\fR \fIrectangle\fR item. The default is transparent (empty string).
.TP
\fB-bordercolor\fR color
Specifies the border color of the rectangle, as in the \fB-outline\fR option of the \fBcanvas\fR \fIrectangle\fR item. The default is black.
.TP
\fB-borderwidth\fR value
Specifies the border width of the rectangle, as in the \fB-width\fR option of the \fBcanvas\fR \fIrectangle\fR item. By default, the width is 1 pixel, which is the minimum width.
.TP
\fB-bulletwidth\fR value
Specifies the width of the rectangle placed to the left of the text. Defaults to \fI10\fR.
.TP
\fB-font\fR value
Specifies the font of the text, as in the \fB-font\fR option of the \fBcanvas\fR \fItext\fR item. The default is system dependent.
.TP
\fB-foreground\fR color
Specifies the color of the text, as in the \fB-fill\fR option of the \fBcanvas\fR \fItext\fR item. The default is black.
.TP
\fB-justify\fR value
Specifies how to justify the text, as in the \fB-justify\fR option of the \fBcanvas\fR \fItext\fR item. The default is \fIleft\fR.
.TP
\fB-minimumwidth\fR value
The total label width will not go below the specified value, but may be larger if the label text requires it.
.TP
\fB-padding\fR value
Specifies how much space to leave between the text and the closest rectangle edge. Units are identical to those specified in the \fBcanvas\fR \fICOORDINATES\fR manual section.
.TP
\fB-scale\fR list
List of 2 floating point numbers used to set the scaling factor in the x and y axis. Scaling is applied immediately and defaults to 1.
.TP
\fB-select\fR boolean
Sets the label state.
.TP
\fB-selectrelief\fR value
Either \fIflat\fR, \fIraised\fR or \fIsunken\fR. Specifies the 3D effect desired for the text area when the label is selected.
.TP
\fB-stipple\fR bitmap
Specifies the stipple pattern filling the rectangle, as in the \fB-stipple\fR option of the \fBcanvas\fR \fIrectangle\fR item. There is no bitmap by default.
.TP
\fB-text\fR text
Specifies the string to be displayed in the text area, as in the \fB-text\fR option of the \fBcanvas\fR \fItext\fR item. The default is an empty string.
.TP
\fB-textbackground\fR color
Specifies the color of the text area background.
.TP
\fB-width\fR value
Specifies a maximum line length for the text, as in the \fB-width\fR option of the \fBcanvas\fR \fItext\fR item. The default is \fI0\fR.
.PP
.SH TAGS
The labeler has the following specific tag (see the \fBcanvas\fR manual page \fIITEM IDS AND TAGS\fR section for more information):
.IP \(bu
canvasLabel(canvasLabelObject)
.PP
.SH "SEE ALSO"
pie, pieBoxLabeler, piePeripheralLabeler
.SH KEYWORDS
canvas, labeler, pie, slice
.SH COPYRIGHT
.nf
Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/tkpiechart/canvaslabel\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free\&.fr>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "canvasLabel" n 6\&.6 tklib "canvasLabel class"
.BS
.SH NAME
canvasLabel \- tkpiechart canvas label class
.SH SYNOPSIS
package require \fBstooop  4\&.1\fR
.sp
package require \fBswitched  2\&.2\fR
.sp
package require \fBtkpiechart  6\&.6\fR
.sp
\fBstooop::new\fR \fBcanvasLabel\fR \fIcanvas\fR ?options?
.sp
\fBswitched::configure\fR \fIcanvasLabelObject\fR ?options?
.sp
\fBswitched::cget\fR \fIcanvasLabelObject\fR \fIoption\fR
.sp
\fBstooop::delete\fR \fIcanvasLabelObject\fR
.sp
.BE
.SH DESCRIPTION
The canvasLabel class brings some Tk label widget functionality to the canvas text item, such as a background and a border\&.
.PP
The canvasLabel is built with a bullet rectangle on the left side of the text\&. The relief changes according to the select state, with a traditionally sunken relief when selected\&.
.PP
The label has a specific tag, which can be used to retrieve the coordinates of the object or move it, thanks to the canvas facilities\&.
.TP
\fBstooop::new\fR \fBcanvasLabel\fR \fIcanvas\fR ?options?
Creates a canvasLabel object in the specified Tk canvas\&. The canvasLabel object identifier is returned (referred to as \fIcanvasLabelObject\fR in this document)\&.
.TP
\fBswitched::configure\fR \fIcanvasLabelObject\fR ?options?
Configures a canvasLabel object or returns all the options with their current values if no options are passed as parameters\&.
.TP
\fBswitched::cget\fR \fIcanvasLabelObject\fR \fIoption\fR
Returns an option value for the specified canvasLabel object\&.
.TP
\fBstooop::delete\fR \fIcanvasLabelObject\fR
Deletes the specified canvasLabel object\&.
.PP
.SH OPTIONS
.TP
\fB-anchor\fR value
Specifies the anchor position of the rectangle and the text, relative to the positioning point\&. The behavior is similar to the \fB-anchor\fR option of the \fBcanvas\fR \fItext\fR item, except that the rectangle is taken into account\&. The default is \fIcenter\fR\&.
.TP
\fB-background\fR color
Specifies the background color of the bullet rectangle, as in the \fB-fill\fR option of the \fBcanvas\fR \fIrectangle\fR item\&. The default is transparent (empty string)\&.
.TP
\fB-bordercolor\fR color
Specifies the border color of the rectangle, as in the \fB-outline\fR option of the \fBcanvas\fR \fIrectangle\fR item\&. The default is black\&.
.TP
\fB-borderwidth\fR value
Specifies the border width of the rectangle, as in the \fB-width\fR option of the \fBcanvas\fR \fIrectangle\fR item\&. By default, the width is 1 pixel, which is the minimum width\&.
.TP
\fB-bulletwidth\fR value
Specifies the width of the rectangle placed to the left of the text\&. Defaults to \fI10\fR\&.
.TP
\fB-font\fR value
Specifies the font of the text, as in the \fB-font\fR option of the \fBcanvas\fR \fItext\fR item\&. The default is system dependent\&.
.TP
\fB-foreground\fR color
Specifies the color of the text, as in the \fB-fill\fR option of the \fBcanvas\fR \fItext\fR item\&. The default is black\&.
.TP
\fB-justify\fR value
Specifies how to justify the text, as in the \fB-justify\fR option of the \fBcanvas\fR \fItext\fR item\&. The default is \fIleft\fR\&.
.TP
\fB-minimumwidth\fR value
The total label width will not go below the specified value, but may be larger if the label text requires it\&.
.TP
\fB-padding\fR value
Specifies how much space to leave between the text and the closest rectangle edge\&. Units are identical to those specified in the \fBcanvas\fR \fICOORDINATES\fR manual section\&.
.TP
\fB-scale\fR list
List of 2 floating point numbers used to set the scaling factor in the x and y axis\&. Scaling is applied immediately and defaults to 1\&.
.TP
\fB-select\fR boolean
Sets the label state\&.
.TP
\fB-selectrelief\fR value
Either \fIflat\fR, \fIraised\fR or \fIsunken\fR\&. Specifies the 3D effect desired for the text area when the label is selected\&.
.TP
\fB-stipple\fR bitmap
Specifies the stipple pattern filling the rectangle, as in the \fB-stipple\fR option of the \fBcanvas\fR \fIrectangle\fR item\&. There is no bitmap by default\&.
.TP
\fB-text\fR text
Specifies the string to be displayed in the text area, as in the \fB-text\fR option of the \fBcanvas\fR \fItext\fR item\&. The default is an empty string\&.
.TP
\fB-textbackground\fR color
Specifies the color of the text area background\&.
.TP
\fB-width\fR value
Specifies a maximum line length for the text, as in the \fB-width\fR option of the \fBcanvas\fR \fItext\fR item\&. The default is \fI0\fR\&.
.PP
.SH TAGS
The labeler has the following specific tag (see the \fBcanvas\fR manual page \fIITEM IDS AND TAGS\fR section for more information):
.IP \(bu
canvasLabel(canvasLabelObject)
.PP
.SH "SEE ALSO"
pie, pieBoxLabeler, piePeripheralLabeler
.SH KEYWORDS
canvas, labeler, pie, slice
.SH COPYRIGHT
.nf
Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free\&.fr>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/tkpiechart/pie.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "pie" n 6.6 tklib "tkpiechart pie class"
.BS
.SH NAME
pie \- 2D or 3D pie chart object in a canvas
.SH SYNOPSIS
package require \fBstooop  4.1\fR
.sp
package require \fBswitched  2.2\fR
.sp
package require \fBtkpiechart  6.6\fR
.sp
\fBstooop::new\fR \fBpie\fR \fIcanvas\fR \fIx\fR \fIy\fR ?options?
.sp
\fBswitched::configure\fR \fIpieObject\fR ?options?
.sp
\fBswitched::cget\fR \fIpieObject\fR \fIoption\fR
.sp
................................................................................
.sp
pie::labelSlice \fIpieObject\fR \fIsliceObject\fR \fIstring\fR
.sp
pie::selectedSlices \fIpieObject\fR
.sp
.BE
.SH DESCRIPTION
A pie object is used to visualize a set of values, usually as shares of a total. Each value is represented by a colored slice, which may have a 2 dimensional or 3 dimensional look. Each slice is associated with a label displaying the data name, and a numerical field showing the percentage taken by the slice. The labels are placed by the chosen labeler object (\fB-labeler\fR option). Each label color matches its related slice.
.PP
A pie chart is made of Tk canvas items, found in \fBpieBoxLabeler\fR, \fBpiePeripheralLabeler\fR and \fBcanvasLabel\fR objects, that compose the pie object. The pie constructor creates the pie itself and its background slice within the parent canvas. Once the pie object exists, slices can be created and resized. At the time the pie is created, the parent Tk \fBcanvas\fR widget must exist.
.PP
Slice colors are automatically generated, using a default color list for all pies, unless another list is used (using the \fB-colors\fR option). When a 3D look is used, the slice edge is darker than its top while using the same color tone.
.TP
\fBstooop::new\fR \fBpie\fR \fIcanvas\fR \fIx\fR \fIy\fR ?options?
Creates a pie object in the specified Tk canvas. The upper left corner of the pie is placed at the specified coordinates in the canvas. The pie object identifier is returned (referred to as \fIpieObject\fR in this document).
.TP
\fBswitched::configure\fR \fIpieObject\fR ?options?
Configures a pie object or returns all the options with their current values if no options are passed as parameters.
.TP
\fBswitched::cget\fR \fIpieObject\fR \fIoption\fR
Returns an option value for the specified pie object.
.TP
\fBstooop::delete\fR \fIpieObject\fR
Deletes the specified pie object.
.PP
.SH OVERVIEW
The pie class is part of the tkpiechart extension that allows the programmer to create and dynamically update 2D or 3D pie charts in a Tcl/Tk application. The tkpiechart package is written in Tcl only, using object oriented techniques thanks to the stooop package, included in tcllib.
.SH OPTIONS
.TP
\fB-autoupdate\fR boolean
Boolean value specifying whether all the slices and their labels are redrawn when a slice size is changed. On by default. Turn it off and invoke \fBpie::update\fR if you change many slices at once and want to improve performance.
.TP
\fB-background\fR color
Slices may or may not fill up the 100% of the pie. The unoccupied part of the pie is a slice that takes 100% of the pie. It is by default transparent with a black border. The color of this background slice may be set by the user using color names as in the \fB-background\fR standard option (see the Tk \fBoptions\fR manual page for more details). When the pie has a 3D look, the background of a slice edge is darker than the top and uses the same color tone.
.TP
\fB-colors\fR list
Specifies a list of colors for slices. In this case, the slice colors will successively be drawn from the list in the list order, cycling through if there are more slices than colors in the list. Colors are specified in the same format as the \fB-background\fR option.
.TP
\fB-height\fR value
Specifies the total height for the pie, including the room taken by the labeler labels. The pie slices are resized when labels are added or deleted (when adding or deleting slices) so that the total height remains constant. This value may be specified in any of the forms described in the \fBcanvas\fR \fICOORDINATES\fR manual section.
.TP
\fB-labeler\fR object
Specifies a placer object for the slice labels, so that, for example, slice values may be placed next to them. If not specified, the \fIpieBoxLabeler\fR (see corresponding manual) is used, the other option being the \fIpiePeripheralLabeler\fR class. Each labeler has a specific behavior which may be set via its options. The labeler object is automatically deleted when the pie object is itself deleted. The labeler cannot be changed once the pie is created.
.TP
\fB-selectable\fR boolean
Boolean value specifying whether slices are selectable or not. Acceptable values are those defined by the Tcl language itself for boolean values. If selectable, slices can be selected with the first mouse button, by clicking on either the slice or its label. Selection can be extended by using the classical \fIcontrol\fR or \fIshift\fR clicks. The list of currently selected slices can be retrieved at any time using the \fBselectedSlices\fR pie class member procedure.
.TP
\fB-title\fR text
Title text to be placed above the pie.
.TP
\fB-titlefont\fR value
Font for the title text.
.TP
\fB-titleoffset\fR value
Distance between the bottom of the title text and the top of the pie slices. This value may be specified in any of the forms described in the sizes section below.
.TP
\fB-thickness\fR value
The thickness is set to 0 by default, giving the pie a simple 2D shape, much faster to display. A positive thickness value will give the pie a 3D look with matched darker colors for the slices edges. These values may be specified in any of the forms described in the \fISIZES\fR section below.
.TP
\fB-width\fR value
Specifies the total width for the pie, including the room taken by the labeler labels. The pie slices are resized when labels are added or deleted (when adding or deleting slices) so that the total width remains constant. This value may be specified in any of the forms described in the \fBcanvas\fR \fICOORDINATES\fR manual section.
.PP
.SH "MEMBER PROCEDURES"
.TP
pie::newSlice \fIpieObject\fR ?labelText?
Creates a slice. A unique object identifier is returned (referred to as \fIsliceObject\fR in this document). The slice color is automatically allocated and the slice label placed using the specified labeler (using the \fB-labeler\fR option). The slice itself is placed after (clockwise) the existing slices. The slice object identifier will be used for sizing and resizing the slice.
.sp
If the label text is not specified, it will be set to \fI"slice n"\fR, \fIn\fR being the number of the slice in the order of creation (first slice is number 1).
.TP
pie::deleteSlice \fIpieObject\fR \fIsliceObject\fR
Deletes a slice. The following slices (clockwise) if any are then moved to compensate for the empty space left by the deleted slice.
.TP
pie::sizeSlice \fIpieObject\fR \fIsliceObject\fR \fIunitShare\fR ?displayedValue?
Sizes or resizes a slice. The slice is then automatically recalculated so it occupies the proper share of the whole pie. The \fIunitShare\fR parameter is a floating point number expressed in share (between 0 and 1) of the whole pie. The following slices (clockwise) are moved to accommodate the new slice size. The slice size value next to the slice label is also updated with the new share value or \fIdisplayedValue\fR if specified.
.TP
pie::labelSlice \fIpieObject\fR \fIsliceObject\fR \fIstring\fR
Updates a slice label. Can be invoked at any time.
.TP
pie::selectedSlices \fIpieObject\fR
Returns a list of currently selected slice objects.
.PP
.SH TAGS
The whole pie, the pie graphics (all slices), and each slice have the following specific tags:
.IP \(bu
\fBpie(pieObject)\fR
.IP \(bu
\fBpieSlices(pieObject)\fR
.IP \(bu
\fBslice(sliceObject)\fR
.PP
For example, the whole pie can be moved using the \fBcanvas\fR \fBmove\fR command on the pie tag, or bindings on slices can be set using the slice tags (see the \fBcanvas\fR manual page \fIITEM IDS AND TAGS\fR section for more information).
.SH SIZES
All sizes related to pies are stored as floating point numbers. The coordinates and sizes are specified in screen units, which are floating point numbers optionally followed by one of several letters as specified in the \fBcanvas\fR \fICOORDINATES\fR manual section.
.SH LIMITATIONS
If the number of slices is too big, identical colors will be used for some of the slices. You may set your own colors in this case.
.SH "SEE ALSO"
canvasLabel, pieBoxLabeler, piePeripheralLabeler
.SH KEYWORDS
canvas, labeler, pie, slice
.SH COPYRIGHT
.nf
Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/tkpiechart/pie\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free\&.fr>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "pie" n 6\&.6 tklib "tkpiechart pie class"
.BS
.SH NAME
pie \- 2D or 3D pie chart object in a canvas
.SH SYNOPSIS
package require \fBstooop  4\&.1\fR
.sp
package require \fBswitched  2\&.2\fR
.sp
package require \fBtkpiechart  6\&.6\fR
.sp
\fBstooop::new\fR \fBpie\fR \fIcanvas\fR \fIx\fR \fIy\fR ?options?
.sp
\fBswitched::configure\fR \fIpieObject\fR ?options?
.sp
\fBswitched::cget\fR \fIpieObject\fR \fIoption\fR
.sp
................................................................................
.sp
pie::labelSlice \fIpieObject\fR \fIsliceObject\fR \fIstring\fR
.sp
pie::selectedSlices \fIpieObject\fR
.sp
.BE
.SH DESCRIPTION
A pie object is used to visualize a set of values, usually as shares of a total\&. Each value is represented by a colored slice, which may have a 2 dimensional or 3 dimensional look\&. Each slice is associated with a label displaying the data name, and a numerical field showing the percentage taken by the slice\&. The labels are placed by the chosen labeler object (\fB-labeler\fR option)\&. Each label color matches its related slice\&.
.PP
A pie chart is made of Tk canvas items, found in \fBpieBoxLabeler\fR, \fBpiePeripheralLabeler\fR and \fBcanvasLabel\fR objects, that compose the pie object\&. The pie constructor creates the pie itself and its background slice within the parent canvas\&. Once the pie object exists, slices can be created and resized\&. At the time the pie is created, the parent Tk \fBcanvas\fR widget must exist\&.
.PP
Slice colors are automatically generated, using a default color list for all pies, unless another list is used (using the \fB-colors\fR option)\&. When a 3D look is used, the slice edge is darker than its top while using the same color tone\&.
.TP
\fBstooop::new\fR \fBpie\fR \fIcanvas\fR \fIx\fR \fIy\fR ?options?
Creates a pie object in the specified Tk canvas\&. The upper left corner of the pie is placed at the specified coordinates in the canvas\&. The pie object identifier is returned (referred to as \fIpieObject\fR in this document)\&.
.TP
\fBswitched::configure\fR \fIpieObject\fR ?options?
Configures a pie object or returns all the options with their current values if no options are passed as parameters\&.
.TP
\fBswitched::cget\fR \fIpieObject\fR \fIoption\fR
Returns an option value for the specified pie object\&.
.TP
\fBstooop::delete\fR \fIpieObject\fR
Deletes the specified pie object\&.
.PP
.SH OVERVIEW
The pie class is part of the tkpiechart extension that allows the programmer to create and dynamically update 2D or 3D pie charts in a Tcl/Tk application\&. The tkpiechart package is written in Tcl only, using object oriented techniques thanks to the stooop package, included in tcllib\&.
.SH OPTIONS
.TP
\fB-autoupdate\fR boolean
Boolean value specifying whether all the slices and their labels are redrawn when a slice size is changed\&. On by default\&. Turn it off and invoke \fBpie::update\fR if you change many slices at once and want to improve performance\&.
.TP
\fB-background\fR color
Slices may or may not fill up the 100% of the pie\&. The unoccupied part of the pie is a slice that takes 100% of the pie\&. It is by default transparent with a black border\&. The color of this background slice may be set by the user using color names as in the \fB-background\fR standard option (see the Tk \fBoptions\fR manual page for more details)\&. When the pie has a 3D look, the background of a slice edge is darker than the top and uses the same color tone\&.
.TP
\fB-colors\fR list
Specifies a list of colors for slices\&. In this case, the slice colors will successively be drawn from the list in the list order, cycling through if there are more slices than colors in the list\&. Colors are specified in the same format as the \fB-background\fR option\&.
.TP
\fB-height\fR value
Specifies the total height for the pie, including the room taken by the labeler labels\&. The pie slices are resized when labels are added or deleted (when adding or deleting slices) so that the total height remains constant\&. This value may be specified in any of the forms described in the \fBcanvas\fR \fICOORDINATES\fR manual section\&.
.TP
\fB-labeler\fR object
Specifies a placer object for the slice labels, so that, for example, slice values may be placed next to them\&. If not specified, the \fIpieBoxLabeler\fR (see corresponding manual) is used, the other option being the \fIpiePeripheralLabeler\fR class\&. Each labeler has a specific behavior which may be set via its options\&. The labeler object is automatically deleted when the pie object is itself deleted\&. The labeler cannot be changed once the pie is created\&.
.TP
\fB-selectable\fR boolean
Boolean value specifying whether slices are selectable or not\&. Acceptable values are those defined by the Tcl language itself for boolean values\&. If selectable, slices can be selected with the first mouse button, by clicking on either the slice or its label\&. Selection can be extended by using the classical \fIcontrol\fR or \fIshift\fR clicks\&. The list of currently selected slices can be retrieved at any time using the \fBselectedSlices\fR pie class member procedure\&.
.TP
\fB-title\fR text
Title text to be placed above the pie\&.
.TP
\fB-titlefont\fR value
Font for the title text\&.
.TP
\fB-titleoffset\fR value
Distance between the bottom of the title text and the top of the pie slices\&. This value may be specified in any of the forms described in the sizes section below\&.
.TP
\fB-thickness\fR value
The thickness is set to 0 by default, giving the pie a simple 2D shape, much faster to display\&. A positive thickness value will give the pie a 3D look with matched darker colors for the slices edges\&. These values may be specified in any of the forms described in the \fISIZES\fR section below\&.
.TP
\fB-width\fR value
Specifies the total width for the pie, including the room taken by the labeler labels\&. The pie slices are resized when labels are added or deleted (when adding or deleting slices) so that the total width remains constant\&. This value may be specified in any of the forms described in the \fBcanvas\fR \fICOORDINATES\fR manual section\&.
.PP
.SH "MEMBER PROCEDURES"
.TP
pie::newSlice \fIpieObject\fR ?labelText?
Creates a slice\&. A unique object identifier is returned (referred to as \fIsliceObject\fR in this document)\&. The slice color is automatically allocated and the slice label placed using the specified labeler (using the \fB-labeler\fR option)\&. The slice itself is placed after (clockwise) the existing slices\&. The slice object identifier will be used for sizing and resizing the slice\&.
.sp
If the label text is not specified, it will be set to \fI"slice n"\fR, \fIn\fR being the number of the slice in the order of creation (first slice is number 1)\&.
.TP
pie::deleteSlice \fIpieObject\fR \fIsliceObject\fR
Deletes a slice\&. The following slices (clockwise) if any are then moved to compensate for the empty space left by the deleted slice\&.
.TP
pie::sizeSlice \fIpieObject\fR \fIsliceObject\fR \fIunitShare\fR ?displayedValue?
Sizes or resizes a slice\&. The slice is then automatically recalculated so it occupies the proper share of the whole pie\&. The \fIunitShare\fR parameter is a floating point number expressed in share (between 0 and 1) of the whole pie\&. The following slices (clockwise) are moved to accommodate the new slice size\&. The slice size value next to the slice label is also updated with the new share value or \fIdisplayedValue\fR if specified\&.
.TP
pie::labelSlice \fIpieObject\fR \fIsliceObject\fR \fIstring\fR
Updates a slice label\&. Can be invoked at any time\&.
.TP
pie::selectedSlices \fIpieObject\fR
Returns a list of currently selected slice objects\&.
.PP
.SH TAGS
The whole pie, the pie graphics (all slices), and each slice have the following specific tags:
.IP \(bu
\fBpie(pieObject)\fR
.IP \(bu
\fBpieSlices(pieObject)\fR
.IP \(bu
\fBslice(sliceObject)\fR
.PP
For example, the whole pie can be moved using the \fBcanvas\fR \fBmove\fR command on the pie tag, or bindings on slices can be set using the slice tags (see the \fBcanvas\fR manual page \fIITEM IDS AND TAGS\fR section for more information)\&.
.SH SIZES
All sizes related to pies are stored as floating point numbers\&. The coordinates and sizes are specified in screen units, which are floating point numbers optionally followed by one of several letters as specified in the \fBcanvas\fR \fICOORDINATES\fR manual section\&.
.SH LIMITATIONS
If the number of slices is too big, identical colors will be used for some of the slices\&. You may set your own colors in this case\&.
.SH "SEE ALSO"
canvasLabel, pieBoxLabeler, piePeripheralLabeler
.SH KEYWORDS
canvas, labeler, pie, slice
.SH COPYRIGHT
.nf
Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free\&.fr>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/tkpiechart/pieboxlabeler.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "pieBoxLabeler" n 6.6 tklib "pieBoxLabeler class"
.BS
.SH NAME
pieBoxLabeler \- tkpiechart pie box style labeler class
.SH SYNOPSIS
\fBstooop::new\fR \fBpieBoxLabeler\fR \fIcanvas\fR ?options?
.sp
\fBswitched::configure\fR \fIpieBoxLabelerObject\fR ?options?
.sp
\fBswitched::cget\fR \fIpieBoxLabelerObject\fR \fIoption\fR
.sp
.BE
.SH DESCRIPTION
The pie box style labeler object is used as a slice label placer for a \fBpie\fR object and is passed to the pie constructor via its \fB-labeler\fR option (see the \fBpie\fR class manual).
.PP
The labels are arranged in 2 columns below the pie graphics. Each label text is placed to the right of a rectangle, the background color of which matches its corresponding slice. The slice share value is placed to the right of the label text, separated by a semicolon. Each label is actually a canvasLabel object (see the \fBcanvasLabel\fR class manual for further information).
.PP
There is no need to delete a \fBpieBoxLabeler\fR object as it is automatically handled by the pie class.
.TP
\fBstooop::new\fR \fBpieBoxLabeler\fR \fIcanvas\fR ?options?
Creates a pieBoxLabeler object in the specified Tk canvas. The pieBoxLabeler object identifier is returned (referred to as \fIpieBoxLabelerObject\fR in this document).
.TP
\fBswitched::configure\fR \fIpieBoxLabelerObject\fR ?options?
Configures a pieBoxLabeler object or returns all the options with their current values if no options are passed as parameters.
.TP
\fBswitched::cget\fR \fIpieBoxLabelerObject\fR \fIoption\fR
Returns an option value for the specified pieBoxLabeler object.
.PP
.SH OPTIONS
.TP
\fB-font\fR value
Specifies a font for the slice labels. If not specified, the default font is system dependent.
.TP
\fB-justify\fR value
Specifies how to justify labels within their own column. Must be one of \fIleft\fR, \fIcenter\fR or \fIright\fR. Defaults to \fIleft\fR. For example, if justification is \fIright\fR, all column labels right edges are aligned.
.TP
\fB-offset\fR value
Specifies the distance between the pie graphics and the closest slice label. This value may be specified in any of the forms described in the \fBcanvas\fR \fICOORDINATES\fR manual section.
.PP
.SH TAGS
The labeler has the following specific tag (see the \fBcanvas\fR manual page \fIITEM IDS AND TAGS\fR section for more information):
.IP \(bu
pieBoxLabeler(pieBoxLabelerObject)
.PP
.SH "SEE ALSO"
canvasLabel, pie, piePeripheralLabeler
.SH KEYWORDS
canvas, labeler, pie, slice
.SH COPYRIGHT
.nf
Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/tkpiechart/pieboxlabeler\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free\&.fr>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "pieBoxLabeler" n 6\&.6 tklib "pieBoxLabeler class"
.BS
.SH NAME
pieBoxLabeler \- tkpiechart pie box style labeler class
.SH SYNOPSIS
\fBstooop::new\fR \fBpieBoxLabeler\fR \fIcanvas\fR ?options?
.sp
\fBswitched::configure\fR \fIpieBoxLabelerObject\fR ?options?
.sp
\fBswitched::cget\fR \fIpieBoxLabelerObject\fR \fIoption\fR
.sp
.BE
.SH DESCRIPTION
The pie box style labeler object is used as a slice label placer for a \fBpie\fR object and is passed to the pie constructor via its \fB-labeler\fR option (see the \fBpie\fR class manual)\&.
.PP
The labels are arranged in 2 columns below the pie graphics\&. Each label text is placed to the right of a rectangle, the background color of which matches its corresponding slice\&. The slice share value is placed to the right of the label text, separated by a semicolon\&. Each label is actually a canvasLabel object (see the \fBcanvasLabel\fR class manual for further information)\&.
.PP
There is no need to delete a \fBpieBoxLabeler\fR object as it is automatically handled by the pie class\&.
.TP
\fBstooop::new\fR \fBpieBoxLabeler\fR \fIcanvas\fR ?options?
Creates a pieBoxLabeler object in the specified Tk canvas\&. The pieBoxLabeler object identifier is returned (referred to as \fIpieBoxLabelerObject\fR in this document)\&.
.TP
\fBswitched::configure\fR \fIpieBoxLabelerObject\fR ?options?
Configures a pieBoxLabeler object or returns all the options with their current values if no options are passed as parameters\&.
.TP
\fBswitched::cget\fR \fIpieBoxLabelerObject\fR \fIoption\fR
Returns an option value for the specified pieBoxLabeler object\&.
.PP
.SH OPTIONS
.TP
\fB-font\fR value
Specifies a font for the slice labels\&. If not specified, the default font is system dependent\&.
.TP
\fB-justify\fR value
Specifies how to justify labels within their own column\&. Must be one of \fIleft\fR, \fIcenter\fR or \fIright\fR\&. Defaults to \fIleft\fR\&. For example, if justification is \fIright\fR, all column labels right edges are aligned\&.
.TP
\fB-offset\fR value
Specifies the distance between the pie graphics and the closest slice label\&. This value may be specified in any of the forms described in the \fBcanvas\fR \fICOORDINATES\fR manual section\&.
.PP
.SH TAGS
The labeler has the following specific tag (see the \fBcanvas\fR manual page \fIITEM IDS AND TAGS\fR section for more information):
.IP \(bu
pieBoxLabeler(pieBoxLabelerObject)
.PP
.SH "SEE ALSO"
canvasLabel, pie, piePeripheralLabeler
.SH KEYWORDS
canvas, labeler, pie, slice
.SH COPYRIGHT
.nf
Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free\&.fr>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/tkpiechart/pieperipherallabeler.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "piePeripheralLabeler" n 6.6 tklib "piePeripheralLabeler class"
.BS
.SH NAME
piePeripheralLabeler \- tkpiechart pie peripheral style labeler class
.SH SYNOPSIS
\fBstooop::new\fR \fBpiePeripheralLabeler\fR \fIcanvas\fR ?options?
.sp
\fBswitched::configure\fR \fIpiePeripheralLabelerObject\fR ?options?
.sp
\fBswitched::cget\fR \fIpiePeripheralLabelerObject\fR \fIoption\fR
.sp
.BE
.SH DESCRIPTION
The pie peripheral style labeler object is used as a slice label placer for a \fBpie\fR object and is passed to the pie constructor via its \fB-labeler\fR option (see the \fBpie\fR class manual).
.PP
The slice description text labels are arranged in 2 columns below the pie graphics, whereas the slice values are placed next to the slice and actually follow the slice as the pie is updated. Each description label text is placed to the right of a rectangle, the background color of which matches its corresponding slice. Each description label is actually a canvasLabel object.
.PP
There is no need to delete a \fBpiePeripheralLabeler\fR object as it is automatically handled by the pie class.
.TP
\fBstooop::new\fR \fBpiePeripheralLabeler\fR \fIcanvas\fR ?options?
Creates a piePeripheralLabeler object in the specified Tk canvas. The piePeripheralLabeler object identifier is returned (refered to as \fIpiePeripheralLabelerObject\fR in this document).
.TP
\fBswitched::configure\fR \fIpiePeripheralLabelerObject\fR ?options?
Configures a piePeripheralLabeler object or returns all the options with their current values if no options are passed as parameters.
.TP
\fBswitched::cget\fR \fIpiePeripheralLabelerObject\fR \fIoption\fR
Returns an option value for the specified piePeripheralLabeler object.
.PP
.SH OPTIONS
.TP
\fB-font\fR value
Specifies a font for the slice labels. If not specified, the default font is system dependent.
.TP
\fB-justify\fR value
Specifies how to justify labels within their own column. Must be one of \fIleft\fR, \fIcenter\fR or \fIright\fR. Defaults to \fIleft\fR. For example, if justification is \fIright\fR, all column labels right edges are aligned.
.TP
\fB-offset\fR value
Specifies the distance between the pie graphics and the closest slice label. This value may be specified in any of the forms described in the \fBcanvas\fR \fICOORDINATES\fR manual section.
.TP
\fB-smallfont\fR
Specifies a font for the slice values. It is usually a small font in order to avoid values overlapping when 2 slices are very close to each other. If not specified, the description label font (\fB-font\fR option) is used.
.TP
\fB-widestvaluetext\fR
Specifies a string of maximum width for slice values (placed around the pie next to the slices), so that enough room is allocated for these value labels when the pie width and height are set. It defaults to 00.0. For example, it could be set to "00.00 %".
.PP
.SH TAGS
The labeler has the following specific tag (see the \fBcanvas\fR manual page \fIITEM IDS AND TAGS\fR section for more information):
.IP \(bu
piePeripheralLabeler(piePeripheralLabelerObject)
.PP
.SH "SEE ALSO"
canvasLabel, pie, pieBoxLabeler
.SH KEYWORDS
canvas, labeler, pie, slice
.SH COPYRIGHT
.nf
Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/tkpiechart/pieperipherallabeler\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free\&.fr>
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "piePeripheralLabeler" n 6\&.6 tklib "piePeripheralLabeler class"
.BS
.SH NAME
piePeripheralLabeler \- tkpiechart pie peripheral style labeler class
.SH SYNOPSIS
\fBstooop::new\fR \fBpiePeripheralLabeler\fR \fIcanvas\fR ?options?
.sp
\fBswitched::configure\fR \fIpiePeripheralLabelerObject\fR ?options?
.sp
\fBswitched::cget\fR \fIpiePeripheralLabelerObject\fR \fIoption\fR
.sp
.BE
.SH DESCRIPTION
The pie peripheral style labeler object is used as a slice label placer for a \fBpie\fR object and is passed to the pie constructor via its \fB-labeler\fR option (see the \fBpie\fR class manual)\&.
.PP
The slice description text labels are arranged in 2 columns below the pie graphics, whereas the slice values are placed next to the slice and actually follow the slice as the pie is updated\&. Each description label text is placed to the right of a rectangle, the background color of which matches its corresponding slice\&. Each description label is actually a canvasLabel object\&.
.PP
There is no need to delete a \fBpiePeripheralLabeler\fR object as it is automatically handled by the pie class\&.
.TP
\fBstooop::new\fR \fBpiePeripheralLabeler\fR \fIcanvas\fR ?options?
Creates a piePeripheralLabeler object in the specified Tk canvas\&. The piePeripheralLabeler object identifier is returned (refered to as \fIpiePeripheralLabelerObject\fR in this document)\&.
.TP
\fBswitched::configure\fR \fIpiePeripheralLabelerObject\fR ?options?
Configures a piePeripheralLabeler object or returns all the options with their current values if no options are passed as parameters\&.
.TP
\fBswitched::cget\fR \fIpiePeripheralLabelerObject\fR \fIoption\fR
Returns an option value for the specified piePeripheralLabeler object\&.
.PP
.SH OPTIONS
.TP
\fB-font\fR value
Specifies a font for the slice labels\&. If not specified, the default font is system dependent\&.
.TP
\fB-justify\fR value
Specifies how to justify labels within their own column\&. Must be one of \fIleft\fR, \fIcenter\fR or \fIright\fR\&. Defaults to \fIleft\fR\&. For example, if justification is \fIright\fR, all column labels right edges are aligned\&.
.TP
\fB-offset\fR value
Specifies the distance between the pie graphics and the closest slice label\&. This value may be specified in any of the forms described in the \fBcanvas\fR \fICOORDINATES\fR manual section\&.
.TP
\fB-smallfont\fR
Specifies a font for the slice values\&. It is usually a small font in order to avoid values overlapping when 2 slices are very close to each other\&. If not specified, the description label font (\fB-font\fR option) is used\&.
.TP
\fB-widestvaluetext\fR
Specifies a string of maximum width for slice values (placed around the pie next to the slices), so that enough room is allocated for these value labels when the pie width and height are set\&. It defaults to 00\&.0\&. For example, it could be set to "00\&.00 %"\&.
.PP
.SH TAGS
The labeler has the following specific tag (see the \fBcanvas\fR manual page \fIITEM IDS AND TAGS\fR section for more information):
.IP \(bu
piePeripheralLabeler(piePeripheralLabelerObject)
.PP
.SH "SEE ALSO"
canvasLabel, pie, pieBoxLabeler
.SH KEYWORDS
canvas, labeler, pie, slice
.SH COPYRIGHT
.nf
Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free\&.fr>

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/tooltip/tooltip.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 1996-2008, Jeffrey Hobbs
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "tooltip" n 1.4.4 tklib "Tooltip management"
.BS
.SH NAME
tooltip \- Tooltip management
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBmsgcat  1.3\fR
.sp
package require \fBtooltip  ?1.4.4?\fR
.sp
\fB::tooltip::tooltip\fR \fIcommand\fR ?\fIoptions\fR?
.sp
\fB::tooltip::tooltip\fR \fIpathName\fR ?\fIoption arg\fR? \fImessage\fR
.sp
.BE
.SH DESCRIPTION
.PP
This package provides tooltips, small text messages that can be displayed
when the mouse hovers over a widget, menu item, canvas item, listbox item
or text widget tag.
.SH COMMANDS
.TP
\fB::tooltip::tooltip\fR \fIcommand\fR ?\fIoptions\fR?
Manage the tooltip package using the following subcommands.
.RS
.TP
\fBclear\fR \fIindex\fR
Prevents the specified widgets from showing tooltips. \fIpattern\fR
is a glob pattern and defaults to matching all widgets.
.TP
\fBdelay\fR ?\fImillisecs\fR?
Query or set the hover delay. This is the interval that the pointer must remain
over the widget before the tooltip is displayed. The delay is specified in
milliseconds and must be greater than 50ms.
With no argument the current delay is returned.
.TP
\fBfade\fR ?\fIboolean\fR?
Enable or disable fading of the tooltip.  The is enabled by default on Win32
and Aqua.  The tooltip will fade away on Leave events instead disappearing.
.TP
\fBdisable\fR
.TP
\fBoff\fR
Disable all tooltips
.TP
\fBenable\fR
.TP
\fBon\fR
Enables tooltips for defined widgets.
.RE
.sp
.TP
\fB::tooltip::tooltip\fR \fIpathName\fR ?\fIoption arg\fR? \fImessage\fR
This command arranges for widget \fIpathName\fR to display a tooltip with
message \fImessage\fR.  The tooltip uses a late-binding msgcat call on the
passed in message to allow for on-the-fly language changes in an application.
If the widget specified is a menu, canvas or text widget then additional options
are used to tie the tooltip to specific menu entries, canvas items or text
tags.
.RS
.TP
\fB-index\fR \fIindex\fR
This option is used to set a tooltip on a menu item. The index may be
either the entry index or the entry label. The widget must be a menu
widget but the entries do not have to exists when the tooltip is set.
.TP
\fB-items\fR \fIname\fR
This option is used to set a tooltip for canvas widget or listbox items.
For the canvas widget, the item must already be present in the canvas
widget and will be found with a \fBfind withtag\fR lookup.
For listbox widgets the item(s) may be created later but the programmer
is responsible for managing the link between the listbox item index and the
corresponding tooltip. If the listbox items are re-ordered, the tooltips
will need amending.
.sp
If the widget is not a canvas or listbox then an error is raised.
.TP
\fB-tag\fR \fIname\fR
The \fB-tag\fR option can be used to set a tooltip for a text widget
tag. The tag should already be present when this command is called or
an error will be returned. The widget must also be a text widget.
.RE
.PP
.SH EXAMPLE
.CS


# Demonstrate widget tooltip
package require tooltip
pack [label .l -text "label"]
tooltip::tooltip .l "This is a label widget"

.CE
.CS


# Demonstrate menu tooltip
package require tooltip
. configure -menu [menu .menu]
.menu add cascade -label Test -menu [menu .menu.test -tearoff 0]
.menu.test add command -label Tooltip
tooltip::tooltip .menu.test -index 0 "This is a menu tooltip"

.CE
.CS


# Demonstrate canvas item tooltip
package require tooltip
pack [canvas .c]
set item [.c create rectangle 10 10 80 80]
tooltip::tooltip .c -item $item "Canvas item tooltip"

.CE
.CS


# Demonstrate listbox item tooltip
package require tooltip
pack [listbox .lb]
.lb insert 0 "item one"
tooltip::tooltip .lb -item 0 "Listbox item tooltip"

.CE
.CS


# Demonstrate text tag tooltip
package require tooltip
pack [text .txt]
.txt tag configure TIP-1 -underline 1
tooltip::tooltip .txt -tag TIP-1 "tooltip one text"
.txt insert end "An example of a " {} "tooltip" TIP-1 " tag.\\n" {}

.CE
.SH KEYWORDS
balloon, help, hover, tooltip
.SH COPYRIGHT
.nf
Copyright (c) 1996-2008, Jeffrey Hobbs

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/tooltip/tooltip\&.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 1996-2008, Jeffrey Hobbs
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "tooltip" n 1\&.4\&.4 tklib "Tooltip management"
.BS
.SH NAME
tooltip \- Tooltip management
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBmsgcat  1\&.3\fR
.sp
package require \fBtooltip  ?1\&.4\&.4?\fR
.sp
\fB::tooltip::tooltip\fR \fIcommand\fR ?\fIoptions\fR?
.sp
\fB::tooltip::tooltip\fR \fIpathName\fR ?\fIoption arg\fR? \fImessage\fR
.sp
.BE
.SH DESCRIPTION
.PP
This package provides tooltips, small text messages that can be displayed
when the mouse hovers over a widget, menu item, canvas item, listbox item
or text widget tag\&.
.SH COMMANDS
.TP
\fB::tooltip::tooltip\fR \fIcommand\fR ?\fIoptions\fR?
Manage the tooltip package using the following subcommands\&.
.RS
.TP
\fBclear\fR \fIindex\fR
Prevents the specified widgets from showing tooltips\&. \fIpattern\fR
is a glob pattern and defaults to matching all widgets\&.
.TP
\fBdelay\fR ?\fImillisecs\fR?
Query or set the hover delay\&. This is the interval that the pointer must remain
over the widget before the tooltip is displayed\&. The delay is specified in
milliseconds and must be greater than 50ms\&.
With no argument the current delay is returned\&.
.TP
\fBfade\fR ?\fIboolean\fR?
Enable or disable fading of the tooltip\&.  The is enabled by default on Win32
and Aqua\&.  The tooltip will fade away on Leave events instead disappearing\&.
.TP
\fBdisable\fR
.TP
\fBoff\fR
Disable all tooltips
.TP
\fBenable\fR
.TP
\fBon\fR
Enables tooltips for defined widgets\&.
.RE
.sp
.TP
\fB::tooltip::tooltip\fR \fIpathName\fR ?\fIoption arg\fR? \fImessage\fR
This command arranges for widget \fIpathName\fR to display a tooltip with
message \fImessage\fR\&.  The tooltip uses a late-binding msgcat call on the
passed in message to allow for on-the-fly language changes in an application\&.
If the widget specified is a menu, canvas or text widget then additional options
are used to tie the tooltip to specific menu entries, canvas items or text
tags\&.
.RS
.TP
\fB-index\fR \fIindex\fR
This option is used to set a tooltip on a menu item\&. The index may be
either the entry index or the entry label\&. The widget must be a menu
widget but the entries do not have to exists when the tooltip is set\&.
.TP
\fB-items\fR \fIname\fR
This option is used to set a tooltip for canvas widget or listbox items\&.
For the canvas widget, the item must already be present in the canvas
widget and will be found with a \fBfind withtag\fR lookup\&.
For listbox widgets the item(s) may be created later but the programmer
is responsible for managing the link between the listbox item index and the
corresponding tooltip\&. If the listbox items are re-ordered, the tooltips
will need amending\&.
.sp
If the widget is not a canvas or listbox then an error is raised\&.
.TP
\fB-tag\fR \fIname\fR
The \fB-tag\fR option can be used to set a tooltip for a text widget
tag\&. The tag should already be present when this command is called or
an error will be returned\&. The widget must also be a text widget\&.
.RE
.PP
.SH EXAMPLE
.CS


# Demonstrate widget tooltip
package require tooltip
pack [label \&.l -text "label"]
tooltip::tooltip \&.l "This is a label widget"

.CE
.CS


# Demonstrate menu tooltip
package require tooltip
\&. configure -menu [menu \&.menu]
\&.menu add cascade -label Test -menu [menu \&.menu\&.test -tearoff 0]
\&.menu\&.test add command -label Tooltip
tooltip::tooltip \&.menu\&.test -index 0 "This is a menu tooltip"

.CE
.CS


# Demonstrate canvas item tooltip
package require tooltip
pack [canvas \&.c]
set item [\&.c create rectangle 10 10 80 80]
tooltip::tooltip \&.c -item $item "Canvas item tooltip"

.CE
.CS


# Demonstrate listbox item tooltip
package require tooltip
pack [listbox \&.lb]
\&.lb insert 0 "item one"
tooltip::tooltip \&.lb -item 0 "Listbox item tooltip"

.CE
.CS


# Demonstrate text tag tooltip
package require tooltip
pack [text \&.txt]
\&.txt tag configure TIP-1 -underline 1
tooltip::tooltip \&.txt -tag TIP-1 "tooltip one text"
\&.txt insert end "An example of a " {} "tooltip" TIP-1 " tag\&.\\n" {}

.CE
.SH KEYWORDS
balloon, help, hover, tooltip
.SH COPYRIGHT
.nf
Copyright (c) 1996-2008, Jeffrey Hobbs

.fi

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widget/widget.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget" n 3.0 tklib "Various megawidgets"
.BS
.SH NAME
widget \- Megawidget bundle
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBTk  8.4\fR
.sp
package require \fBwidget  ?3.0?\fR
.sp
package require \fBsnit \fR
.sp
\fBwidget::validate\fR \fIas\fR ?options?
.sp
\fBwidget::calendar\fR \fIpathname\fR ?options?
.sp
................................................................................
.sp
\fBwidget::superframe\fR \fIpathname\fR ?options?
.sp
\fBwidget::toolbar\fR \fIpathname\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides megawidgets based on the snit oo system (snidgets).
It makes use of the Tile/Ttk themed widget set.
.PP
.TP
\fBwidget::validate\fR \fIas\fR ?options?
commands:
.PP
.SH WIDGETS
.TP
................................................................................
options:
.PP
.SH EXAMPLE
.CS


package require widget::superframe ; # or widget::all
pack [widget::superframe .f -type separator -text "SuperFrame:"]

.CE
.SH KEYWORDS
bundle, calendar, dateentry, dialog, megawidget, menu, panelframe, ruler, screenruler, scrolledwindow, snit, statusbar, superframe, toolbar, widget
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widget/widget\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget" n 3\&.0 tklib "Various megawidgets"
.BS
.SH NAME
widget \- Megawidget bundle
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBTk  8\&.4\fR
.sp
package require \fBwidget  ?3\&.0?\fR
.sp
package require \fBsnit \fR
.sp
\fBwidget::validate\fR \fIas\fR ?options?
.sp
\fBwidget::calendar\fR \fIpathname\fR ?options?
.sp
................................................................................
.sp
\fBwidget::superframe\fR \fIpathname\fR ?options?
.sp
\fBwidget::toolbar\fR \fIpathname\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides megawidgets based on the snit oo system (snidgets)\&.
It makes use of the Tile/Ttk themed widget set\&.
.PP
.TP
\fBwidget::validate\fR \fIas\fR ?options?
commands:
.PP
.SH WIDGETS
.TP
................................................................................
options:
.PP
.SH EXAMPLE
.CS


package require widget::superframe ; # or widget::all
pack [widget::superframe \&.f -type separator -text "SuperFrame:"]

.CE
.SH KEYWORDS
bundle, calendar, dateentry, dialog, megawidget, menu, panelframe, ruler, screenruler, scrolledwindow, snit, statusbar, superframe, toolbar, widget
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widget/widget_calendar.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_calendar" n 1.00 tklib "Various megawidgets"
.BS
.SH NAME
widget_calendar \- Calendar Megawidget
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBTk  8.4\fR
.sp
package require \fBwidget  ?3.0?\fR
.sp
package require \fBwidget::calendar  ?1.00?\fR
.sp
\fBwidget::calendar\fR \fIpathname\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides a calendar megawidget (snidget).
.PP
.TP
\fBwidget::calendar\fR \fIpathname\fR ?options?
.PP
.SH "WIDGET OPTIONS"
.PP
.TP
\fB-command\fR
A script to evaluate when a date was selected.
.TP
\fB-dateformat\fR
The format of the date that is returned. Default: %m/%d/%Y.
.TP
\fB-firstday\fR
Set first day the week, Either sunday or monday. It defaults to monday.
.TP
\fB-font\fR
Select the font used in the widget. It defaults to Helvetica 9.
.TP
\fB-highlightcolor\fR
Selects the background color for the day that has been selected. Default: #FFCC00
.TP
\fB-language\fR
Specify language of the calendar contents. The language is specified
by abbreviations of the languge, for example: en - english, de - german ...
It defaults to en.
.sp
Supported languages: de en es fr gr he it ja sv pl pt zh fi tr nl ru crk crx-nak crx-lhe
.TP
\fB-shadecolor\fR
Selects the color of the parts that have a shaded background. Default: #888888
.TP
\fB-showpast\fR
Specify if the past shall be shown. It is a boolean value and defaults
to 1.
.TP
\fB-textvariable\fR
Specifies the name of a variable whose value is linked to the entry widget's contents.
Whenever the variable changes value, the widget's contents are updated, and
vice versa.
.PP
.SH "WIDGET COMMAND"
\fIpathname\fR \fBget\fR ?\fIwhat\fR?
.PP
Returns a part of the selected date or 'all'. The argument \fIwhat\fR selects
the part. Valid values for \fIwhat\fR are: day, month, year and all.
\'all' is the default and returns the complete date in the format given
with -dateformat.
.SH "DEFAULT BINDINGS"
On creation of the calendar widget the following bindings are installed.
When pressing a key the command is invoked and the textvariable is
updated.
updated.
.IP \(bu
Home - Move to the current date
.IP \(bu
Up - Move to week before current date
.IP \(bu
Down - Move to week after current date
.IP \(bu
................................................................................
Control-Down - Move to year after current date
.PP
.SH EXAMPLE
.CS


    package require widget::calendar ; # or widget::all
    set t [widget::calendar .t]
    pack $t -fill x -expand 1

.CE
.SH KEYWORDS
calendar, date, megawidget, snit, widget
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widget/widget_calendar\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_calendar" n 1\&.00 tklib "Various megawidgets"
.BS
.SH NAME
widget_calendar \- Calendar Megawidget
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBTk  8\&.4\fR
.sp
package require \fBwidget  ?3\&.0?\fR
.sp
package require \fBwidget::calendar  ?1\&.00?\fR
.sp
\fBwidget::calendar\fR \fIpathname\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides a calendar megawidget (snidget)\&.
.PP
.TP
\fBwidget::calendar\fR \fIpathname\fR ?options?
.PP
.SH "WIDGET OPTIONS"
.PP
.TP
\fB-command\fR
A script to evaluate when a date was selected\&.
.TP
\fB-dateformat\fR
The format of the date that is returned\&. Default: %m/%d/%Y\&.
.TP
\fB-firstday\fR
Set first day the week, Either sunday or monday\&. It defaults to monday\&.
.TP
\fB-font\fR
Select the font used in the widget\&. It defaults to Helvetica 9\&.
.TP
\fB-highlightcolor\fR
Selects the background color for the day that has been selected\&. Default: #FFCC00
.TP
\fB-language\fR
Specify language of the calendar contents\&. The language is specified
by abbreviations of the languge, for example: en - english, de - german \&.\&.\&.
It defaults to en\&.
.sp
Supported languages: de en es fr gr he it ja sv pl pt zh fi tr nl ru crk crx-nak crx-lhe
.TP
\fB-shadecolor\fR
Selects the color of the parts that have a shaded background\&. Default: #888888
.TP
\fB-showpast\fR
Specify if the past shall be shown\&. It is a boolean value and defaults
to 1\&.
.TP
\fB-textvariable\fR
Specifies the name of a variable whose value is linked to the entry widget's contents\&.
Whenever the variable changes value, the widget's contents are updated, and
vice versa\&.
.PP
.SH "WIDGET COMMAND"
\fIpathname\fR \fBget\fR ?\fIwhat\fR?
.PP
Returns a part of the selected date or 'all'\&. The argument \fIwhat\fR selects
the part\&. Valid values for \fIwhat\fR are: day, month, year and all\&.
\'all' is the default and returns the complete date in the format given
with -dateformat\&.
.SH "DEFAULT BINDINGS"
On creation of the calendar widget the following bindings are installed\&.
When pressing a key the command is invoked and the textvariable is
updated\&.
updated\&.
.IP \(bu
Home - Move to the current date
.IP \(bu
Up - Move to week before current date
.IP \(bu
Down - Move to week after current date
.IP \(bu
................................................................................
Control-Down - Move to year after current date
.PP
.SH EXAMPLE
.CS


    package require widget::calendar ; # or widget::all
    set t [widget::calendar \&.t]
    pack $t -fill x -expand 1

.CE
.SH KEYWORDS
calendar, date, megawidget, snit, widget
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widget/widget_dateentry.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_dateentry" n 0.95 tklib "Various megawidgets"
.BS
.SH NAME
widget_dateentry \- Date Entry Megawidget
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBTk  8.4\fR
.sp
package require \fBwidget  ?3.0?\fR
.sp
package require \fBwidget::dateentry  ?0.95?\fR
.sp
\fBwidget::dateentry\fR \fIpathname\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides a dateentry megawidget (snidget).
It is based on an ttk::entry. All widget commands of the ttk::entry
are available for the dateentry.
.PP
.TP
\fBwidget::dateentry\fR \fIpathname\fR ?options?
.PP
.SH "WIDGET OPTIONS"
.PP
.TP
\fB-command\fR
A script to evaluate when a date was selected.
.TP
\fB-dateformat\fR
The format of the date that is returned. Default: %m/%d/%Y.
.TP
\fB-firstday\fR
See the calendar man page.
.TP
\fB-font\fR
Select the font used in the widget. It defaults to Helvetica 9.
.TP
\fB-highlightcolor\fR
See the calendar man page.
.TP
\fB-language\fR
See the calendar man page.
.TP
\fB-shadecolor\fR
See the calendar man page.
.TP
\fB-showpast\fR
See the calendar man page.
.TP
\fB-textvariable\fR
Specifies the name of a variable whose value is linked to the entry widget's contents.
Whenever the variable changes value, the widget's contents are updated, and
vice versa.
.PP
.SH "WIDGET COMMAND"
\fIpathname\fR \fBget\fR
Returns the selected date.
.SH "DEFAULT BINDINGS"
On creation of the dateentry widget the following bindings are installed.
For navigation within the calendar, see its manpage.
.IP \(bu
Button-1 - Accept and select the date and close the calendar window.
.IP \(bu
Return, space - Accept the selected date and close the calendar window
.IP \(bu
Escape - Close calendar window
.IP \(bu
Control-space - Show calendar window
.PP
.SH EXAMPLE
.CS


    package require widget::dateentry; # or widget::all
    set t [widget::dateentry .de]
    pack $t -fill x -expand 1

.CE
.SH KEYWORDS
date, dateentry, megawidget, snit, widget
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widget/widget_dateentry\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_dateentry" n 0\&.95 tklib "Various megawidgets"
.BS
.SH NAME
widget_dateentry \- Date Entry Megawidget
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBTk  8\&.4\fR
.sp
package require \fBwidget  ?3\&.0?\fR
.sp
package require \fBwidget::dateentry  ?0\&.95?\fR
.sp
\fBwidget::dateentry\fR \fIpathname\fR ?options?
.sp
.BE
.SH DESCRIPTION
This package provides a dateentry megawidget (snidget)\&.
It is based on an ttk::entry\&. All widget commands of the ttk::entry
are available for the dateentry\&.
.PP
.TP
\fBwidget::dateentry\fR \fIpathname\fR ?options?
.PP
.SH "WIDGET OPTIONS"
.PP
.TP
\fB-command\fR
A script to evaluate when a date was selected\&.
.TP
\fB-dateformat\fR
The format of the date that is returned\&. Default: %m/%d/%Y\&.
.TP
\fB-firstday\fR
See the calendar man page\&.
.TP
\fB-font\fR
Select the font used in the widget\&. It defaults to Helvetica 9\&.
.TP
\fB-highlightcolor\fR
See the calendar man page\&.
.TP
\fB-language\fR
See the calendar man page\&.
.TP
\fB-shadecolor\fR
See the calendar man page\&.
.TP
\fB-showpast\fR
See the calendar man page\&.
.TP
\fB-textvariable\fR
Specifies the name of a variable whose value is linked to the entry widget's contents\&.
Whenever the variable changes value, the widget's contents are updated, and
vice versa\&.
.PP
.SH "WIDGET COMMAND"
\fIpathname\fR \fBget\fR
Returns the selected date\&.
.SH "DEFAULT BINDINGS"
On creation of the dateentry widget the following bindings are installed\&.
For navigation within the calendar, see its manpage\&.
.IP \(bu
Button-1 - Accept and select the date and close the calendar window\&.
.IP \(bu
Return, space - Accept the selected date and close the calendar window
.IP \(bu
Escape - Close calendar window
.IP \(bu
Control-space - Show calendar window
.PP
.SH EXAMPLE
.CS


    package require widget::dateentry; # or widget::all
    set t [widget::dateentry \&.de]
    pack $t -fill x -expand 1

.CE
.SH KEYWORDS
date, dateentry, megawidget, snit, widget
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widget/widget_toolbar.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_toolbar" n 3.0 tklib "Various megawidgets"
.BS
.SH NAME
widget_toolbar \- Toolbar Megawidget
.SH SYNOPSIS
package require \fBTcl  8.4\fR
.sp
package require \fBTk  8.4\fR
.sp
package require \fBwidget  ?3.0?\fR
.sp
package require \fBwidget::toolbar  ?1.0?\fR
.sp
\fBwidget::toolbar\fR \fIpathname\fR ?options?
.sp
getframe
.sp
add ?item? ?args?
.sp
delete item1 ?item2? ?...?
.sp
itemcget symbol option
.sp
itemconfigure symbol ?args?
.sp
items ?pattern?
.sp
remove ?-destroy? item1 ?item2? ?...?
.sp
.BE
.SH DESCRIPTION
This package provides a toolbar megawidget (snidget).
It makes use of the Tile/Ttk themed widget set.
.PP
.TP
\fBwidget::toolbar\fR \fIpathname\fR ?options?
.TP
getframe
.TP
add ?item? ?args?
.TP
delete item1 ?item2? ?...?
.TP
itemcget symbol option
.TP
itemconfigure symbol ?args?
.TP
items ?pattern?
.TP
remove ?-destroy? item1 ?item2? ?...?
.PP
.SH "WIDGET OPTIONS"
.TP
\fB-ipad\fR
.TP
\fB-pad\fR
.TP
................................................................................
\fB-weight\fR
.PP
.SH EXAMPLE
.CS


package require widget::toolbar ; # or widget::all
set t [widget::toolbar .t]
pack $t -fill x -expand 1
$t add button [button .b -text foo]
$t add separator -pad {2 4}
$t add button [button .c -text bar]

.CE
.SH KEYWORDS
megawidget, snit, toolbar, widget
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widget/widget_toolbar\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_toolbar" n 3\&.0 tklib "Various megawidgets"
.BS
.SH NAME
widget_toolbar \- Toolbar Megawidget
.SH SYNOPSIS
package require \fBTcl  8\&.4\fR
.sp
package require \fBTk  8\&.4\fR
.sp
package require \fBwidget  ?3\&.0?\fR
.sp
package require \fBwidget::toolbar  ?1\&.0?\fR
.sp
\fBwidget::toolbar\fR \fIpathname\fR ?options?
.sp
getframe
.sp
add ?item? ?args?
.sp
delete item1 ?item2? ?\&.\&.\&.?
.sp
itemcget symbol option
.sp
itemconfigure symbol ?args?
.sp
items ?pattern?
.sp
remove ?-destroy? item1 ?item2? ?\&.\&.\&.?
.sp
.BE
.SH DESCRIPTION
This package provides a toolbar megawidget (snidget)\&.
It makes use of the Tile/Ttk themed widget set\&.
.PP
.TP
\fBwidget::toolbar\fR \fIpathname\fR ?options?
.TP
getframe
.TP
add ?item? ?args?
.TP
delete item1 ?item2? ?\&.\&.\&.?
.TP
itemcget symbol option
.TP
itemconfigure symbol ?args?
.TP
items ?pattern?
.TP
remove ?-destroy? item1 ?item2? ?\&.\&.\&.?
.PP
.SH "WIDGET OPTIONS"
.TP
\fB-ipad\fR
.TP
\fB-pad\fR
.TP
................................................................................
\fB-weight\fR
.PP
.SH EXAMPLE
.CS


package require widget::toolbar ; # or widget::all
set t [widget::toolbar \&.t]
pack $t -fill x -expand 1
$t add button [button \&.b -text foo]
$t add separator -pad {2 4}
$t add button [button \&.c -text bar]

.CE
.SH KEYWORDS
megawidget, snit, toolbar, widget
.SH CATEGORY
Widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widgetl/widget_listentry.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_listentry" n 0.1 tklib "widget::listentry widget"
.BS
.SH NAME
widget_listentry \- widget::listentry widget
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBwidget::listentry  ?0.1?\fR
.sp
package require \fBwidget::validator  ?0.1?\fR
.sp
package require \fBwidget::scrolledwindow \fR
.sp
package require \fBsnit \fR
.sp
package require \fBtooltip \fR
.sp
................................................................................
.sp
\fBwidget::listentry\fR \fIpathname\fR ?options?
.sp
\fBwidgetCmd\fR \fBdestroy\fR
.sp
\fBwidgetCmd\fR \fBconfigure\fR
.sp
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR ...
.sp
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR
.sp
\fBwidgetCmd\fR \fBcget\fR \fIoption\fR
.sp
\fI{*}cmdprefix\fR \fBget\fR
.sp
................................................................................
\fI{*}cmdprefix\fR \fItext\fR
.sp
\fI{*}cmdprefix\fR \fIcookievar\fR
.sp
.BE
.SH DESCRIPTION
This package provides a megawidget for the interactive entry of
ordered and unordered lists.
For a simpler and more restricted megawidget please see the
package \fBwidget::listsimple\fR.
.SH "CLASS API"
The widget class supports a single command, for the creation of widgets.
.TP
\fBwidget::listentry\fR \fIpathname\fR ?options?
This command creates and configures new instances of the widget.
.sp
For details on the available options please see section
\fBWidget Options\fR.
.sp
The result of the command is the pathname of the new widget.
.PP
.SH "INSTANCE API"
All widget instances supported the following methods.
.TP
\fBwidgetCmd\fR \fBdestroy\fR
This method destroys the widget.
Any further access to the widget will generate errors.
.sp
The result of the command is the empty string.
.TP
\fBwidgetCmd\fR \fBconfigure\fR
This method comes in three variants. This variant here returns a list
containing the current configuration of the widget, i.e. the values
for all options.
.sp
For details on the available options please see section
\fBWidget Options\fR.
.TP
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR ...
This method comes in three variants. This variant here reconfigures
the widget, setting the specified options to the given values.
.sp
\fINote\fR that it is not possible to change the
construction-time only options.
.sp
For details on the available options please see section
\fBWidget General Options\fR.
.sp
The result of the command is the empty string.
.TP
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR
This method comes in three variants. This variant here is an alias
for the method \fBcget\fR below and identical to it.
.TP
\fBwidgetCmd\fR \fBcget\fR \fIoption\fR
This method returns the current value of the specified \fIoption\fR.
.sp
For details on the available options please see section
\fBWidget Options\fR.
.PP
.SH "WIDGET OPTIONS"
This section explains all the options available to instances of
\fBwidget::listentry\fR. Please note that a few of the options
can be set only at instance construction time. The majority of the
options can however be set both during construction- and runtime.
.SS "WIDGET CONSTRUCTION-TIME ONLY OPTIONS"
.TP
\fB-ordered\fR boolean
This options tells the new widget instance whether the list it manages
is ordered or not. If it is ordered the widget will show buttons with
which the selected entries can be moved around, editing the order.
.sp
The default is \fBfalse\fR, indicating an unordered list.
.TP
\fB-allow-duplicates\fR boolean
This options tells the new widget instance whether we are allowed to
add a string to the list multiple times, or not.
.sp
The default is \fBfalse\fR, indicating that duplicates are not
allowed.
.TP
\fB-values\fR cmdprefix
This option specifies a callback for the management of a predefined
list of strings a user may enter.
.sp
If specified the widget will use a combobox instead of a plain
entry field and fill its list during widget construction using the data
delivered by this callback.
The callback will be further invoked whenever a new value is entered
into the main list, to save the extended list of predefined values.
.sp
The signature of this callback is
.RS
.TP
\fI{*}cmdprefix\fR \fBget\fR
In this form the callback is expected to return a list of strings.
The strings are loaded into the list of the internal combobox for
quick access by the user.
.sp
It will be invoked once, during widget construction, to load the
list of predefined strings a user may enter.
.TP
\fI{*}cmdprefix\fR \fBset\fR \fIvalues\fR
In this form the callback is given a list of new strings and
expected to save them somewhere for future use.
.sp
The return value of the callback is ignored.
.sp
This form is invoked whenever the user entered a new string
into the main list. The order of strings in \fIvalues\fR represents
the order used to show them in the combobox's list.
.RE
.TP
\fB-validate\fR cmdprefix
This option specifies a callback which is invoked after every change of
the contents of the internal entry field. The signature of this callback is
.RS
.TP
\fI{*}cmdprefix\fR \fItext\fR \fIerrvar\fR
where \fItext\fR is the string to validate, and \fIerrvar\fR the name of
a variable the callback can store an error message into when it detects
invalid data.
.sp
The widget expects that the callback returns a boolean value, where
\fBtrue\fR indicates that \fItext\fR is valid.
.RE
.IP
The default validation, when no callback was specified, will treat the
empty string as invalid, and everything else as valid.
.sp
\fIPlease note\fR that the widget will prevent the entry of
duplicate values into the main list, regardless of the validity of the
input otherwise. This is in keeping with that this widget is meant for
the entry of unordered lists, essentially a set of strings.
.TP
\fB-transform\fR cmdprefix
This option specifies a callback which is invoked whenever a newly
entered element is moved from the entry field to the main list, or the
entry field is validated, as part of a check for duplicates, if such are
not allowed. The callback is given the text in the entry field and has
to return the text which is actually added to, or checked against the list.
.sp
The use case for this callback is essentially
\fIinput normalization\fR. The most simple case of such would be, for
example the use of
.CS

string tolower
.CE
.IP to impose a standard letter
case on the data. More complex example can be thought of, like rewriting
of multiple syntaxes of input to a canonical form.
The signature of this callback is
.RS
.TP
\fI{*}cmdprefix\fR \fItext\fR
where \fItext\fR is the string to transform.
.sp
The widget expects that the callback returns the transformed string.
.RE
.sp
The default is to not transform the entered strings.
.TP
\fB-browse\fR cmdprefix
If this option is specified the widget will display a "Search" button
and invoke the callback provided by the option whenever the user clicks
on that button.
The signature of the callback is
.RS
.TP
\fI{*}cmdprefix\fR \fIcookievar\fR
where the cookie variable provides access to context information the
callback may wish to preserve between invokations. The initial value
stored in the variable is the empty string. After that it is whatever
the callback wishes to store.
.sp
The widget expects that the callback returns a list of strings,
which are then added to the list, modulo validity and duplicate checks.
.RE
.sp
By default there is no browse callback and no button shown.
.PP
.SS "WIDGET GENERAL OPTIONS"
.TP
\fB-listvariable\fR varname
This option specifies the variable holding the list to be manipulated by
the widget. Any changes to the list outside of the widget are automatically
imported into the widget. Similarly, all changes made to the list by the
widget are automatically exported to this variable.
.TP
\fB-state\fR normal|disabled
This option specifies the status of the widget, \fBnormal\fR (= active),
or \fBdisabled\fR. A disabled widget can not be edited.
.sp
The default is \fBnormal\fR.
.TP
\fB-height\fR integer
This option specifies the height of the internal listbox, in lines.
.sp
The default is \fB20\fR.
.TP
\fB-skin-add\fR string
.TP
\fB-skin-remove\fR string
.TP
\fB-skin-up\fR string
.TP
................................................................................
\fB-skin-img-up\fR string
.TP
\fB-skin-img-down\fR string
.TP
\fB-skin-img-browse\fR string
.TP
\fB-skin-invalid-color\fR color
These options all modify the appearance of the widget, i.e. its skin.
.sp
All options taking a string argument influence the various labels
shown, with the \fB-skin-tip-*\fR options influencing the tooltips
shown on hovering the over various parts in particular.
.sp
All the strings are run through \fBmsgcat\fR first, enabling
text localization through message catalogs. The default values are keys
into the message catalogs which are part of the package itself.
.sp
The options taking images modify the images shown on the buttons
for adding and removing elements of the list. They default to the PNG
images distributed with the package itself.
.sp
The single option taking a color value modifies the color used to
highlight invalid data entered into the internal entry field of the
widget. This option defaults to \fByellow\fR.
.PP
.SH EXAMPLE
.CS


.CE
.SH KEYWORDS
data entry lists, data entry ordered list, data entry set of strings, data entry unordered list, list entry panel, set entry panel, widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widgetl/widget_listentry\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_listentry" n 0\&.1 tklib "widget::listentry widget"
.BS
.SH NAME
widget_listentry \- widget::listentry widget
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBwidget::listentry  ?0\&.1?\fR
.sp
package require \fBwidget::validator  ?0\&.1?\fR
.sp
package require \fBwidget::scrolledwindow \fR
.sp
package require \fBsnit \fR
.sp
package require \fBtooltip \fR
.sp
................................................................................
.sp
\fBwidget::listentry\fR \fIpathname\fR ?options?
.sp
\fBwidgetCmd\fR \fBdestroy\fR
.sp
\fBwidgetCmd\fR \fBconfigure\fR
.sp
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR \&.\&.\&.
.sp
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR
.sp
\fBwidgetCmd\fR \fBcget\fR \fIoption\fR
.sp
\fI{*}cmdprefix\fR \fBget\fR
.sp
................................................................................
\fI{*}cmdprefix\fR \fItext\fR
.sp
\fI{*}cmdprefix\fR \fIcookievar\fR
.sp
.BE
.SH DESCRIPTION
This package provides a megawidget for the interactive entry of
ordered and unordered lists\&.
For a simpler and more restricted megawidget please see the
package \fBwidget::listsimple\fR\&.
.SH "CLASS API"
The widget class supports a single command, for the creation of widgets\&.
.TP
\fBwidget::listentry\fR \fIpathname\fR ?options?
This command creates and configures new instances of the widget\&.
.sp
For details on the available options please see section
\fBWidget Options\fR\&.
.sp
The result of the command is the pathname of the new widget\&.
.PP
.SH "INSTANCE API"
All widget instances supported the following methods\&.
.TP
\fBwidgetCmd\fR \fBdestroy\fR
This method destroys the widget\&.
Any further access to the widget will generate errors\&.
.sp
The result of the command is the empty string\&.
.TP
\fBwidgetCmd\fR \fBconfigure\fR
This method comes in three variants\&. This variant here returns a list
containing the current configuration of the widget, i\&.e\&. the values
for all options\&.
.sp
For details on the available options please see section
\fBWidget Options\fR\&.
.TP
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR \&.\&.\&.
This method comes in three variants\&. This variant here reconfigures
the widget, setting the specified options to the given values\&.
.sp
\fINote\fR that it is not possible to change the
construction-time only options\&.
.sp
For details on the available options please see section
\fBWidget General Options\fR\&.
.sp
The result of the command is the empty string\&.
.TP
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR
This method comes in three variants\&. This variant here is an alias
for the method \fBcget\fR below and identical to it\&.
.TP
\fBwidgetCmd\fR \fBcget\fR \fIoption\fR
This method returns the current value of the specified \fIoption\fR\&.
.sp
For details on the available options please see section
\fBWidget Options\fR\&.
.PP
.SH "WIDGET OPTIONS"
This section explains all the options available to instances of
\fBwidget::listentry\fR\&. Please note that a few of the options
can be set only at instance construction time\&. The majority of the
options can however be set both during construction- and runtime\&.
.SS "WIDGET CONSTRUCTION-TIME ONLY OPTIONS"
.TP
\fB-ordered\fR boolean
This options tells the new widget instance whether the list it manages
is ordered or not\&. If it is ordered the widget will show buttons with
which the selected entries can be moved around, editing the order\&.
.sp
The default is \fBfalse\fR, indicating an unordered list\&.
.TP
\fB-allow-duplicates\fR boolean
This options tells the new widget instance whether we are allowed to
add a string to the list multiple times, or not\&.
.sp
The default is \fBfalse\fR, indicating that duplicates are not
allowed\&.
.TP
\fB-values\fR cmdprefix
This option specifies a callback for the management of a predefined
list of strings a user may enter\&.
.sp
If specified the widget will use a combobox instead of a plain
entry field and fill its list during widget construction using the data
delivered by this callback\&.
The callback will be further invoked whenever a new value is entered
into the main list, to save the extended list of predefined values\&.
.sp
The signature of this callback is
.RS
.TP
\fI{*}cmdprefix\fR \fBget\fR
In this form the callback is expected to return a list of strings\&.
The strings are loaded into the list of the internal combobox for
quick access by the user\&.
.sp
It will be invoked once, during widget construction, to load the
list of predefined strings a user may enter\&.
.TP
\fI{*}cmdprefix\fR \fBset\fR \fIvalues\fR
In this form the callback is given a list of new strings and
expected to save them somewhere for future use\&.
.sp
The return value of the callback is ignored\&.
.sp
This form is invoked whenever the user entered a new string
into the main list\&. The order of strings in \fIvalues\fR represents
the order used to show them in the combobox's list\&.
.RE
.TP
\fB-validate\fR cmdprefix
This option specifies a callback which is invoked after every change of
the contents of the internal entry field\&. The signature of this callback is
.RS
.TP
\fI{*}cmdprefix\fR \fItext\fR \fIerrvar\fR
where \fItext\fR is the string to validate, and \fIerrvar\fR the name of
a variable the callback can store an error message into when it detects
invalid data\&.
.sp
The widget expects that the callback returns a boolean value, where
\fBtrue\fR indicates that \fItext\fR is valid\&.
.RE
.IP
The default validation, when no callback was specified, will treat the
empty string as invalid, and everything else as valid\&.
.sp
\fIPlease note\fR that the widget will prevent the entry of
duplicate values into the main list, regardless of the validity of the
input otherwise\&. This is in keeping with that this widget is meant for
the entry of unordered lists, essentially a set of strings\&.
.TP
\fB-transform\fR cmdprefix
This option specifies a callback which is invoked whenever a newly
entered element is moved from the entry field to the main list, or the
entry field is validated, as part of a check for duplicates, if such are
not allowed\&. The callback is given the text in the entry field and has
to return the text which is actually added to, or checked against the list\&.
.sp
The use case for this callback is essentially
\fIinput normalization\fR\&. The most simple case of such would be, for
example the use of
.CS

string tolower
.CE
.IP to impose a standard letter
case on the data\&. More complex example can be thought of, like rewriting
of multiple syntaxes of input to a canonical form\&.
The signature of this callback is
.RS
.TP
\fI{*}cmdprefix\fR \fItext\fR
where \fItext\fR is the string to transform\&.
.sp
The widget expects that the callback returns the transformed string\&.
.RE
.sp
The default is to not transform the entered strings\&.
.TP
\fB-browse\fR cmdprefix
If this option is specified the widget will display a "Search" button
and invoke the callback provided by the option whenever the user clicks
on that button\&.
The signature of the callback is
.RS
.TP
\fI{*}cmdprefix\fR \fIcookievar\fR
where the cookie variable provides access to context information the
callback may wish to preserve between invokations\&. The initial value
stored in the variable is the empty string\&. After that it is whatever
the callback wishes to store\&.
.sp
The widget expects that the callback returns a list of strings,
which are then added to the list, modulo validity and duplicate checks\&.
.RE
.sp
By default there is no browse callback and no button shown\&.
.PP
.SS "WIDGET GENERAL OPTIONS"
.TP
\fB-listvariable\fR varname
This option specifies the variable holding the list to be manipulated by
the widget\&. Any changes to the list outside of the widget are automatically
imported into the widget\&. Similarly, all changes made to the list by the
widget are automatically exported to this variable\&.
.TP
\fB-state\fR normal|disabled
This option specifies the status of the widget, \fBnormal\fR (= active),
or \fBdisabled\fR\&. A disabled widget can not be edited\&.
.sp
The default is \fBnormal\fR\&.
.TP
\fB-height\fR integer
This option specifies the height of the internal listbox, in lines\&.
.sp
The default is \fB20\fR\&.
.TP
\fB-skin-add\fR string
.TP
\fB-skin-remove\fR string
.TP
\fB-skin-up\fR string
.TP
................................................................................
\fB-skin-img-up\fR string
.TP
\fB-skin-img-down\fR string
.TP
\fB-skin-img-browse\fR string
.TP
\fB-skin-invalid-color\fR color
These options all modify the appearance of the widget, i\&.e\&. its skin\&.
.sp
All options taking a string argument influence the various labels
shown, with the \fB-skin-tip-*\fR options influencing the tooltips
shown on hovering the over various parts in particular\&.
.sp
All the strings are run through \fBmsgcat\fR first, enabling
text localization through message catalogs\&. The default values are keys
into the message catalogs which are part of the package itself\&.
.sp
The options taking images modify the images shown on the buttons
for adding and removing elements of the list\&. They default to the PNG
images distributed with the package itself\&.
.sp
The single option taking a color value modifies the color used to
highlight invalid data entered into the internal entry field of the
widget\&. This option defaults to \fByellow\fR\&.
.PP
.SH EXAMPLE
.CS


.CE
.SH KEYWORDS
data entry lists, data entry ordered list, data entry set of strings, data entry unordered list, list entry panel, set entry panel, widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widgetl/widget_listsimple.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_listsimple" n 0.1 tklib "widget::listsimple widget"
.BS
.SH NAME
widget_listsimple \- widget::listsimple widget
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBwidget::listsimple  ?0.1?\fR
.sp
package require \fBwidget::validator  ?0.1?\fR
.sp
package require \fBwidget::scrolledwindow \fR
.sp
package require \fBsnit \fR
.sp
package require \fBtooltip \fR
.sp
................................................................................
.sp
\fBwidget::listsimple\fR \fIpathname\fR ?options?
.sp
\fBwidgetCmd\fR \fBdestroy\fR
.sp
\fBwidgetCmd\fR \fBconfigure\fR
.sp
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR ...
.sp
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR
.sp
\fBwidgetCmd\fR \fBcget\fR \fIoption\fR
.sp
\fI{*}cmdprefix\fR \fBget\fR
.sp
\fI{*}cmdprefix\fR \fBset\fR \fIvalues\fR
.sp
\fI{*}cmdprefix\fR \fItext\fR \fIerrvar\fR
.sp
.BE
.SH DESCRIPTION
This package provides a megawidget for the interactive entry of unordered lists.
For a megawidget allowing the entry of ordered lists, and more, please see the
package \fBwidget::listentry\fR.
.SH "CLASS API"
The widget class supports a single command, for the creation of widgets.
.TP
\fBwidget::listsimple\fR \fIpathname\fR ?options?
This command creates and configures new instances of the widget.
.sp
For details on the available options please see section
\fBWidget Options\fR.
.sp
The result of the command is the pathname of the new widget.
.PP
.SH "INSTANCE API"
All widget instances supported the following methods.
.TP
\fBwidgetCmd\fR \fBdestroy\fR
This method destroys the widget.
Any further access to the widget will generate errors.
.sp
The result of the command is the empty string.
.TP
\fBwidgetCmd\fR \fBconfigure\fR
This method comes in three variants. This variant here returns a list
containing the current configuration of the widget, i.e. the values
for all options.
.sp
For details on the available options please see section
\fBWidget Options\fR.
.TP
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR ...
This method comes in three variants. This variant here reconfigures
the widget, setting the specified options to the given values.
.sp
\fINote\fR that it is not possible to change the
construction-time only options.
.sp
For details on the available options please see section
\fBWidget General Options\fR.
.sp
The result of the command is the empty string.
.TP
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR
This method comes in three variants. This variant here is an alias
for the method \fBcget\fR below and identical to it.
.TP
\fBwidgetCmd\fR \fBcget\fR \fIoption\fR
This method returns the current value of the specified \fIoption\fR.
.sp
For details on the available options please see section
\fBWidget Options\fR.
.PP
.SH "WIDGET OPTIONS"
This section explains all the options available to instances of
\fBwidget::listsimple\fR. Please note that a few of the options
can be set only at instance construction time. The majority of the
options can however be set both during construction- and runtime.
.SS "WIDGET CONSTRUCTION-TIME ONLY OPTIONS"
.TP
\fB-values\fR cmdprefix
This option specifies a callback for the management of a predefined
list of strings a user may enter.
.sp
If specified the widget will use a combobox instead of a plain
entry field and fill its list during widget construction using the data
delivered by this callback.
The callback will be further invoked whenever a new value is entered
into the main list, to save the extended list of predefined values.
.sp
The signature of this callback is
.RS
.TP
\fI{*}cmdprefix\fR \fBget\fR
In this form the callback is expected to return a list of strings.
The strings are loaded into the list of the internal combobox for
quick access by the user.
.sp
It will be invoked once, during widget construction, to load the
list of predefined strings a user may enter.
.TP
\fI{*}cmdprefix\fR \fBset\fR \fIvalues\fR
In this form the callback is given a list of new strings and
expected to save them somewhere for future use.
.sp
The return value of the callback is ignored.
.sp
This form is invoked whenever the user entered a new string
into the main list. The order of strings in \fIvalues\fR represents
the order used to show them in the combobox's list.
.RE
.TP
\fB-validate\fR cmdprefix
This option specifies a callback which is invoked after every change of
the contents of the internal entry field. The signature of this callback is
.RS
.TP
\fI{*}cmdprefix\fR \fItext\fR \fIerrvar\fR
where \fItext\fR is the string to validate, and \fIerrvar\fR the name of
a variable the callback can store an error message into when it detects
invalid data.
.sp
The system expects that the callback returns a boolean value, where
\fBtrue\fR indicates that \fItext\fR is valid.
.RE
.IP
The default validation, when no callback was specified, will treat the
empty string as invalid, and everything else as valid.
.sp
\fIPlease note\fR that the widget will prevent the entry of
duplicate values into the main list, regardless of the validity of the
input otherwise. This is in keeping with that this widget is meant for
the entry of unordered lists, essentially a set of strings.
.PP
.SS "WIDGET GENERAL OPTIONS"
.TP
\fB-listvariable\fR varname
This option specifies the variable holding the list to be manipulated by
the widget. Any changes to the list outside of the widget are automatically
imported into the widget. Similarly, all changes made to the list by the
widget are automatically exported to this variable.
.TP
\fB-skin-add\fR string
.TP
\fB-skin-remove\fR string
.TP
\fB-skin-tip-add\fR string
.TP
................................................................................
\fB-skin-tip-remove-none\fR string
.TP
\fB-skin-img-add\fR image
.TP
\fB-skin-img-remove\fR image
.TP
\fB-skin-invalid-color\fR color
These options all modify the appearance of the widget, i.e. its skin.
.sp
All options taking a string argument influence the various labels
shown, with the \fB-skin-tip-*\fR options influencing the tooltips
shown on hovering the over various parts in particular.
.sp
All the strings are run through \fBmsgcat\fR first, enabling
text localization through message catalogs. The default values are keys
into the message catalogs which are part of the package itself.
.sp
The options taking images modify the images shown on the buttons
for adding and removing elements of the list. They default to the PNG
images distributed with the package itself.
.sp
The single option taking a color value modifies the color used to
highlight invalid data entered into the internal entry field of the
widget. This option defaults to \fByellow\fR.
.PP
.SH EXAMPLE
.CS


.CE
.SH KEYWORDS
data entry lists, data entry set of strings, data entry unordered list, list entry panel, set entry panel, widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widgetl/widget_listsimple\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_listsimple" n 0\&.1 tklib "widget::listsimple widget"
.BS
.SH NAME
widget_listsimple \- widget::listsimple widget
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBwidget::listsimple  ?0\&.1?\fR
.sp
package require \fBwidget::validator  ?0\&.1?\fR
.sp
package require \fBwidget::scrolledwindow \fR
.sp
package require \fBsnit \fR
.sp
package require \fBtooltip \fR
.sp
................................................................................
.sp
\fBwidget::listsimple\fR \fIpathname\fR ?options?
.sp
\fBwidgetCmd\fR \fBdestroy\fR
.sp
\fBwidgetCmd\fR \fBconfigure\fR
.sp
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR \&.\&.\&.
.sp
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR
.sp
\fBwidgetCmd\fR \fBcget\fR \fIoption\fR
.sp
\fI{*}cmdprefix\fR \fBget\fR
.sp
\fI{*}cmdprefix\fR \fBset\fR \fIvalues\fR
.sp
\fI{*}cmdprefix\fR \fItext\fR \fIerrvar\fR
.sp
.BE
.SH DESCRIPTION
This package provides a megawidget for the interactive entry of unordered lists\&.
For a megawidget allowing the entry of ordered lists, and more, please see the
package \fBwidget::listentry\fR\&.
.SH "CLASS API"
The widget class supports a single command, for the creation of widgets\&.
.TP
\fBwidget::listsimple\fR \fIpathname\fR ?options?
This command creates and configures new instances of the widget\&.
.sp
For details on the available options please see section
\fBWidget Options\fR\&.
.sp
The result of the command is the pathname of the new widget\&.
.PP
.SH "INSTANCE API"
All widget instances supported the following methods\&.
.TP
\fBwidgetCmd\fR \fBdestroy\fR
This method destroys the widget\&.
Any further access to the widget will generate errors\&.
.sp
The result of the command is the empty string\&.
.TP
\fBwidgetCmd\fR \fBconfigure\fR
This method comes in three variants\&. This variant here returns a list
containing the current configuration of the widget, i\&.e\&. the values
for all options\&.
.sp
For details on the available options please see section
\fBWidget Options\fR\&.
.TP
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR \&.\&.\&.
This method comes in three variants\&. This variant here reconfigures
the widget, setting the specified options to the given values\&.
.sp
\fINote\fR that it is not possible to change the
construction-time only options\&.
.sp
For details on the available options please see section
\fBWidget General Options\fR\&.
.sp
The result of the command is the empty string\&.
.TP
\fBwidgetCmd\fR \fBconfigure\fR \fIoption\fR
This method comes in three variants\&. This variant here is an alias
for the method \fBcget\fR below and identical to it\&.
.TP
\fBwidgetCmd\fR \fBcget\fR \fIoption\fR
This method returns the current value of the specified \fIoption\fR\&.
.sp
For details on the available options please see section
\fBWidget Options\fR\&.
.PP
.SH "WIDGET OPTIONS"
This section explains all the options available to instances of
\fBwidget::listsimple\fR\&. Please note that a few of the options
can be set only at instance construction time\&. The majority of the
options can however be set both during construction- and runtime\&.
.SS "WIDGET CONSTRUCTION-TIME ONLY OPTIONS"
.TP
\fB-values\fR cmdprefix
This option specifies a callback for the management of a predefined
list of strings a user may enter\&.
.sp
If specified the widget will use a combobox instead of a plain
entry field and fill its list during widget construction using the data
delivered by this callback\&.
The callback will be further invoked whenever a new value is entered
into the main list, to save the extended list of predefined values\&.
.sp
The signature of this callback is
.RS
.TP
\fI{*}cmdprefix\fR \fBget\fR
In this form the callback is expected to return a list of strings\&.
The strings are loaded into the list of the internal combobox for
quick access by the user\&.
.sp
It will be invoked once, during widget construction, to load the
list of predefined strings a user may enter\&.
.TP
\fI{*}cmdprefix\fR \fBset\fR \fIvalues\fR
In this form the callback is given a list of new strings and
expected to save them somewhere for future use\&.
.sp
The return value of the callback is ignored\&.
.sp
This form is invoked whenever the user entered a new string
into the main list\&. The order of strings in \fIvalues\fR represents
the order used to show them in the combobox's list\&.
.RE
.TP
\fB-validate\fR cmdprefix
This option specifies a callback which is invoked after every change of
the contents of the internal entry field\&. The signature of this callback is
.RS
.TP
\fI{*}cmdprefix\fR \fItext\fR \fIerrvar\fR
where \fItext\fR is the string to validate, and \fIerrvar\fR the name of
a variable the callback can store an error message into when it detects
invalid data\&.
.sp
The system expects that the callback returns a boolean value, where
\fBtrue\fR indicates that \fItext\fR is valid\&.
.RE
.IP
The default validation, when no callback was specified, will treat the
empty string as invalid, and everything else as valid\&.
.sp
\fIPlease note\fR that the widget will prevent the entry of
duplicate values into the main list, regardless of the validity of the
input otherwise\&. This is in keeping with that this widget is meant for
the entry of unordered lists, essentially a set of strings\&.
.PP
.SS "WIDGET GENERAL OPTIONS"
.TP
\fB-listvariable\fR varname
This option specifies the variable holding the list to be manipulated by
the widget\&. Any changes to the list outside of the widget are automatically
imported into the widget\&. Similarly, all changes made to the list by the
widget are automatically exported to this variable\&.
.TP
\fB-skin-add\fR string
.TP
\fB-skin-remove\fR string
.TP
\fB-skin-tip-add\fR string
.TP
................................................................................
\fB-skin-tip-remove-none\fR string
.TP
\fB-skin-img-add\fR image
.TP
\fB-skin-img-remove\fR image
.TP
\fB-skin-invalid-color\fR color
These options all modify the appearance of the widget, i\&.e\&. its skin\&.
.sp
All options taking a string argument influence the various labels
shown, with the \fB-skin-tip-*\fR options influencing the tooltips
shown on hovering the over various parts in particular\&.
.sp
All the strings are run through \fBmsgcat\fR first, enabling
text localization through message catalogs\&. The default values are keys
into the message catalogs which are part of the package itself\&.
.sp
The options taking images modify the images shown on the buttons
for adding and removing elements of the list\&. They default to the PNG
images distributed with the package itself\&.
.sp
The single option taking a color value modifies the color used to
highlight invalid data entered into the internal entry field of the
widget\&. This option defaults to \fByellow\fR\&.
.PP
.SH EXAMPLE
.CS


.CE
.SH KEYWORDS
data entry lists, data entry set of strings, data entry unordered list, list entry panel, set entry panel, widget

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widgetv/widget_validator.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_validator" n 0.1 tklib "widget::validator behaviour"
.BS
.SH NAME
widget_validator \- widget::validator behaviour
.SH SYNOPSIS
package require \fBTcl  8.5\fR
.sp
package require \fBTk  8.5\fR
.sp
package require \fBwidget::validator  ?0.1?\fR
.sp
\fBwidget::validator\fR \fBattach\fR \fIw\fR \fIcolor\fR \fIcmdprefix\fR
.sp
\fBwidget::validator\fR \fBdetach\fR \fIw\fR
.sp
\fBwidget::validator\fR \fBvalidate\fR \fIw\fR
.sp
.BE
.SH DESCRIPTION
This package provides a unified validation API
for \fBttk\fR's entry and combobox widgets.
.PP
Please note that the validation behaviour
defined in this package will not reject invalid
edits. It will only highlight the entry containing
invalid data and set the proper state flag.
.PP
It is the responsibility of the using package
or application to decide how and when to actually
reject such invalid content.
.PP
.TP
\fBwidget::validator\fR \fBattach\fR \fIw\fR \fIcolor\fR \fIcmdprefix\fR
This method adds a validating behaviour to the widget \fIw\fR.
.sp
Whenever the content of the widget's entry field changes
the specified \fIcmdprefix\fR is invoked and has to return a
boolean value, where \fBtrue\fR means that content is ok, and
\fBfalse\fR that the content is invalid. For more information
on the command prefix see section \fBValidation\fR.
In case of the latter the background color of the entry field
is changed to \fIcolor\fR to indicate the invalidity.
.sp
The system does not support nesting of validators on a
widget, nor the attachment of multiple validators. To change
validating conditions \fBdetach\fR the current validator first
before attaching the new.
.sp
An error is thrown if the widget has already
validating behaviour attached to it.
.sp
The result of the method is the empty string.
.sp
To achieve its aims the package overrides various
configuration options of the widget the behaviour is
attached to. These options are restored to their previous
values on \fBdetach\fR.
.sp
If other behaviours are attached the validator
may be rendered temporarily (partially) non-functional.
Similarly, if the validator is detached while a different
behaviour is also attached its restoration of configuration
settings may render the other non-functional
.TP
\fBwidget::validator\fR \fBdetach\fR \fIw\fR
This method removes the validating behaviour from
the widget \fIw\fR and restores it to its original
state.
.sp
An error is thrown if the widget has no
validating behaviour attached to it.
.sp
The result of the method is the empty string.
.TP
\fBwidget::validator\fR \fBvalidate\fR \fIw\fR
Invoking this method forces a validation of the
widget \fIw\fR, assuming that it has a validator
behaviour attached to it.
.sp
The result of the method is the empty string.
.PP
.SH VALIDATION
The command prefix for used for validation has to
have the following signature:
.TP
{*}\fIcmdprefix\fR \fItext\fR
The argument is the text to validate.
.sp
The result of the callback has to be a boolean value
where \fBtrue\fR means that \fItext\fR is ok, and
\fBfalse\fR that \fItext\fR is invalid.
.PP
.SH EXAMPLE
.CS


package require Tk 8.5
package require widget::validator

set TE {}
set TC {}

ttk::entry    .e -textvariable TE
ttk::combobox .c -textvariable TC -values {fruit vegetable corn}
ttk::combobox .n -values {fruit vegetable corn}
ttk::button   .x -command ::exit -text Exit

pack .e -expand 1 -fill both -side top
pack .c -expand 1 -fill both -side top
pack .n -expand 1 -fill both -side top
pack .x -expand 1 -fill both -side top

widget::validator attach .e lightblue {apply {text {
    expr {$text ne {}}
}}}

widget::validator attach .c yellow {apply {text {
    expr {$text ni {{} hello world}}
}}}

widget::validator attach .n pink {apply {text {
    expr {$text ni {{} blub}}
}}}

.CE
.SH KEYWORDS
invalid, state management, ttk::combobox, ttk::entry, validation, widget validation

'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/man/files/modules/widgetv/widget_validator\&.n' by tcllib/doctools with format 'nroff'
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
................................................................................
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "widget_validator" n 0\&.1 tklib "widget::validator behaviour"
.BS
.SH NAME
widget_validator \- widget::validator behaviour
.SH SYNOPSIS
package require \fBTcl  8\&.5\fR
.sp
package require \fBTk  8\&.5\fR
.sp
package require \fBwidget::validator  ?0\&.1?\fR
.sp
\fBwidget::validator\fR \fBattach\fR \fIw\fR \fIcolor\fR \fIcmdprefix\fR
.sp
\fBwidget::validator\fR \fBdetach\fR \fIw\fR
.sp
\fBwidget::validator\fR \fBvalidate\fR \fIw\fR
.sp
.BE
.SH DESCRIPTION
This package provides a unified validation API
for \fBttk\fR's entry and combobox widgets\&.
.PP
Please note that the validation behaviour
defined in this package will not reject invalid
edits\&. It will only highlight the entry containing
invalid data and set the proper state flag\&.
.PP
It is the responsibility of the using package
or application to decide how and when to actually
reject such invalid content\&.
.PP
.TP
\fBwidget::validator\fR \fBattach\fR \fIw\fR \fIcolor\fR \fIcmdprefix\fR
This method adds a validating behaviour to the widget \fIw\fR\&.
.sp
Whenever the content of the widget's entry field changes
the specified \fIcmdprefix\fR is invoked and has to return a
boolean value, where \fBtrue\fR means that content is ok, and
\fBfalse\fR that the content is invalid\&. For more information
on the command prefix see section \fBValidation\fR\&.
In case of the latter the background color of the entry field
is changed to \fIcolor\fR to indicate the invalidity\&.
.sp
The system does not support nesting of validators on a
widget, nor the attachment of multiple validators\&. To change
validating conditions \fBdetach\fR the current validator first
before attaching the new\&.
.sp
An error is thrown if the widget has already
validating behaviour attached to it\&.
.sp
The result of the method is the empty string\&.
.sp
To achieve its aims the package overrides various
configuration options of the widget the behaviour is
attached to\&. These options are restored to their previous
values on \fBdetach\fR\&.
.sp
If other behaviours are attached the validator
may be rendered temporarily (partially) non-functional\&.
Similarly, if the validator is detached while a different
behaviour is also attached its restoration of configuration
settings may render the other non-functional
.TP
\fBwidget::validator\fR \fBdetach\fR \fIw\fR
This method removes the validating behaviour from
the widget \fIw\fR and restores it to its original
state\&.
.sp
An error is thrown if the widget has no
validating behaviour attached to it\&.
.sp
The result of the method is the empty string\&.
.TP
\fBwidget::validator\fR \fBvalidate\fR \fIw\fR
Invoking this method forces a validation of the
widget \fIw\fR, assuming that it has a validator
behaviour attached to it\&.
.sp
The result of the method is the empty string\&.
.PP
.SH VALIDATION
The command prefix for used for validation has to
have the following signature:
.TP
{*}\fIcmdprefix\fR \fItext\fR
The argument is the text to validate\&.
.sp
The result of the callback has to be a boolean value
where \fBtrue\fR means that \fItext\fR is ok, and
\fBfalse\fR that \fItext\fR is invalid\&.
.PP
.SH EXAMPLE
.CS


package require Tk 8\&.5
package require widget::validator

set TE {}
set TC {}

ttk::entry    \&.e -textvariable TE
ttk::combobox \&.c -textvariable TC -values {fruit vegetable corn}
ttk::combobox \&.n -values {fruit vegetable corn}
ttk::button   \&.x -command ::exit -text Exit

pack \&.e -expand 1 -fill both -side top
pack \&.c -expand 1 -fill both -side top
pack \&.n -expand 1 -fill both -side top
pack \&.x -expand 1 -fill both -side top

widget::validator attach \&.e lightblue {apply {text {
    expr {$text ne {}}
}}}

widget::validator attach \&.c yellow {apply {text {
    expr {$text ni {{} hello world}}
}}}

widget::validator attach \&.n pink {apply {text {
    expr {$text ni {{} blub}}
}}}

.CE
.SH KEYWORDS
invalid, state management, ttk::combobox, ttk::entry, validation, widget validation

<! -- CVS: $Id$ Keyword Index
   -->
<head>
<title> Keyword Index </title>
</head>
<body>
<hr> [
   <a href="/tklib">Home</a>
| <a href="toc.html">Table Of Contents</a>



 ] <hr>
<h3> Keyword Index </h3>
<hr><div class="#idxnav">
<a href="#c1"> 2 </a> &#183; <a href="#c2"> 3 </a> &#183; <a href="#c3"> A </a> &#183; <a href="#c4"> B </a> &#183; <a href="#c5"> C </a> &#183; <a href="#c6"> D </a> &#183; <a href="#c7"> E </a> &#183; <a href="#c8"> G </a> &#183; <a href="#c9"> H </a> &#183; <a href="#c10"> I </a> &#183; <a href="#c11"> L </a> &#183; <a href="#c12"> M </a> &#183; <a href="#c13"> N </a> &#183; <a href="#c14"> P </a> &#183; <a href="#c15"> Q </a> &#183; <a href="#c16"> R </a> &#183; <a href="#c17"> S </a> &#183; <a href="#c18"> T </a> &#183; <a href="#c19"> V </a> &#183; <a href="#c20"> W </a> &#183; <a href="#c21"> X </a> &#183; <a href="#c22"> Z </a>
</div>
<hr><table class="#idx" width="100%">
<tr class="#idxheader"><th colspan="2">
................................................................................
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c2">Keywords: 3</a>
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key60"> 3D bars </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key58"> 3D surfaces </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c3">Keywords: A</a>
</th></tr>
<tr class="#idxodd" valign=top>
................................................................................
</th></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key101"> balloon </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/tooltip/tooltip.html"> tooltip </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key55"> bar charts </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key6"> bindtags </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/ntext/ntext.html"> ntext </a> &#183; <a href="tklib/files/modules/ntext/ntextBindings.html"> ntextBindings </a> &#183; <a href="tklib/files/modules/ntext/ntextIndent.html"> ntextIndent </a> &#183; <a href="tklib/files/modules/ntext/ntextWordBreak.html"> ntextWordBreak </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key32"> cell </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_sqmap.html"> canvas::sqmap </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key44"> character </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/khim/khim.html"> khim </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key50"> charts </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key17"> chat </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/chatwidget/chatwidget.html"> chatwidget </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key135"> controlling </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/controlwidget/controlwidget.html"> controlwidget </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key39"> conversion </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/apps/dia.html"> dia </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key4"> convex </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_equad.html"> canvas::edit::quadrilateral </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key47"> coordinate transformations </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key56"> coordinates </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key140"> cross-hairs </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/crosshair/crosshair.html"> crosshair </a>
................................................................................
<td class="#idxright" width="65%">
<a href="tklib/files/modules/cursor/cursor.html"> cursor </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c6">Keywords: D</a>
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key130"> data entry lists </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a> &#183; <a href="tklib/files/modules/widgetl/widget_listsimple.html"> widget_listsimple </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key131"> data entry ordered list </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key129"> data entry set of strings </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a> &#183; <a href="tklib/files/modules/widgetl/widget_listsimple.html"> widget_listsimple </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key126"> data entry unordered list </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a> &#183; <a href="tklib/files/modules/widgetl/widget_listsimple.html"> widget_listsimple </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key10"> dateentry </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/datefield/datefield.html"> datefield </a> &#183; <a href="tklib/files/modules/widget/widget.html"> widget </a> &#183; <a href="tklib/files/modules/widget/widget_dateentry.html"> widget_dateentry </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key38"> diagram </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/apps/dia.html"> dia </a> &#183; <a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key22"> dialog </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/getstring/tk_getString.html"> getstring </a> &#183; <a href="tklib/files/modules/swaplist/swaplist.html"> swaplist </a> &#183; <a href="tklib/files/modules/widget/widget.html"> widget </a>
................................................................................
<td class="#idxright" width="65%">
<a href="tklib/files/modules/ico/ico.html"> ico </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c8">Keywords: G</a>
</th></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key51"> graphical presentation </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key116"> graphics </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_mvg.html"> canvas::mvg </a>
................................................................................
<td class="#idxright" width="65%">
<a href="tklib/files/modules/tooltip/tooltip.html"> tooltip </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c10">Keywords: I</a>
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key41"> i18n </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/khim/khim.html"> khim </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key98"> ico </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/ico/ico.html"> ico </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key120"> imagemagick </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_mvg.html"> canvas::mvg </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key43"> input </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/khim/khim.html"> khim </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key92"> insert tag </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_tags.html"> canvas::tag </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key42"> international </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/khim/khim.html"> khim </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key84"> interpolation </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key18"> irc </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/chatwidget/chatwidget.html"> chatwidget </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key54"> isometric plots </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c11">Keywords: L</a>
</th></tr>
<tr class="#idxodd" valign=top>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key83"> line </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key128"> list entry panel </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a> &#183; <a href="tklib/files/modules/widgetl/widget_listsimple.html"> widget_listsimple </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key146"> listbox </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/swaplist/swaplist.html"> swaplist </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key31"> menu </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widget/widget.html"> widget </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key45"> method </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/khim/khim.html"> khim </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key89"> move </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key62"> pie </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/tkpiechart/canvaslabel.html"> canvasLabel </a> &#183; <a href="tklib/files/modules/tkpiechart/pie.html"> pie </a> &#183; <a href="tklib/files/modules/tkpiechart/pieboxlabeler.html"> pieBoxLabeler </a> &#183; <a href="tklib/files/modules/tkpiechart/pieperipherallabeler.html"> piePeripheralLabeler </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key57"> pie charts </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key143"> pixel </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/apps/bitmap-editor.html"> bitmap-editor </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key79"> plane geometry </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key53"> plotting </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a> &#183; <a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key75"> point </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key123"> points </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_epoints.html"> canvas::edit::points </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key46"> polar plots </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key111"> polyline </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_epolyline.html"> canvas::edit::polyline </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key118"> serialization </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_mvg.html"> canvas::mvg </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key127"> set entry panel </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a> &#183; <a href="tklib/files/modules/widgetl/widget_listsimple.html"> widget_listsimple </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key61"> slice </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/tkpiechart/canvaslabel.html"> canvasLabel </a> &#183; <a href="tklib/files/modules/tkpiechart/pie.html"> pie </a> &#183; <a href="tklib/files/modules/tkpiechart/pieboxlabeler.html"> pieBoxLabeler </a> &#183; <a href="tklib/files/modules/tkpiechart/pieperipherallabeler.html"> piePeripheralLabeler </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key137"> string </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/getstring/tk_getString.html"> getstring </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key59"> strip charts </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key27"> superframe </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widget/widget.html"> widget </a>
................................................................................
<td class="#idxright" width="65%">
<a href="tklib/files/modules/ctext/ctext.html"> ctext </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c18">Keywords: T</a>
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key48"> tables </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key94"> tags </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_tags.html"> canvas::tag </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key34"> tile </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_sqmap.html"> canvas::sqmap </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key49"> time charts </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key23"> toolbar </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widget/widget.html"> widget </a> &#183; <a href="tklib/files/modules/widget/widget_toolbar.html"> widget_toolbar </a>
................................................................................
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key69"> validation </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetv/widget_validator.html"> widget_validator </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key40"> vector </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/apps/dia.html"> dia </a> &#183; <a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key115"> vector graphics </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_mvg.html"> canvas::mvg </a>
................................................................................
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key145"> xbm </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/apps/bitmap-editor.html"> bitmap-editor </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key52"> xy-plots </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c22">Keywords: Z</a>
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key136"> zoom </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_zoom.html"> canvas::zoom </a>
</td></tr>
</table>
</body></html>

<! -- CVS: $Id$ Keyword Index
   -->
<head>
<title> Keyword Index </title>
</head>
<body>
<hr> [
   <a href="../../../../home">Tcllib Home</a>
| <a href="toc.html">Table Of Contents</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
 ] <hr>
<h3> Keyword Index </h3>
<hr><div class="#idxnav">
<a href="#c1"> 2 </a> &#183; <a href="#c2"> 3 </a> &#183; <a href="#c3"> A </a> &#183; <a href="#c4"> B </a> &#183; <a href="#c5"> C </a> &#183; <a href="#c6"> D </a> &#183; <a href="#c7"> E </a> &#183; <a href="#c8"> G </a> &#183; <a href="#c9"> H </a> &#183; <a href="#c10"> I </a> &#183; <a href="#c11"> L </a> &#183; <a href="#c12"> M </a> &#183; <a href="#c13"> N </a> &#183; <a href="#c14"> P </a> &#183; <a href="#c15"> Q </a> &#183; <a href="#c16"> R </a> &#183; <a href="#c17"> S </a> &#183; <a href="#c18"> T </a> &#183; <a href="#c19"> V </a> &#183; <a href="#c20"> W </a> &#183; <a href="#c21"> X </a> &#183; <a href="#c22"> Z </a>
</div>
<hr><table class="#idx" width="100%">
<tr class="#idxheader"><th colspan="2">
................................................................................
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c2">Keywords: 3</a>
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key52"> 3D bars </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key50"> 3D surfaces </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c3">Keywords: A</a>
</th></tr>
<tr class="#idxodd" valign=top>
................................................................................
</th></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key101"> balloon </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/tooltip/tooltip.html"> tooltip </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key47"> bar charts </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key6"> bindtags </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/ntext/ntext.html"> ntext </a> &#183; <a href="tklib/files/modules/ntext/ntextBindings.html"> ntextBindings </a> &#183; <a href="tklib/files/modules/ntext/ntextIndent.html"> ntextIndent </a> &#183; <a href="tklib/files/modules/ntext/ntextWordBreak.html"> ntextWordBreak </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key32"> cell </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_sqmap.html"> canvas::sqmap </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key56"> character </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/khim/khim.html"> khim </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key42"> charts </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key17"> chat </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/chatwidget/chatwidget.html"> chatwidget </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key135"> controlling </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/controlwidget/controlwidget.html"> controlwidget </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key59"> conversion </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/apps/dia.html"> dia </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key4"> convex </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_equad.html"> canvas::edit::quadrilateral </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key39"> coordinate transformations </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key48"> coordinates </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key140"> cross-hairs </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/crosshair/crosshair.html"> crosshair </a>
................................................................................
<td class="#idxright" width="65%">
<a href="tklib/files/modules/cursor/cursor.html"> cursor </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c6">Keywords: D</a>
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key131"> data entry lists </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a> &#183; <a href="tklib/files/modules/widgetl/widget_listsimple.html"> widget_listsimple </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key127"> data entry ordered list </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key130"> data entry set of strings </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a> &#183; <a href="tklib/files/modules/widgetl/widget_listsimple.html"> widget_listsimple </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key126"> data entry unordered list </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a> &#183; <a href="tklib/files/modules/widgetl/widget_listsimple.html"> widget_listsimple </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key10"> dateentry </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/datefield/datefield.html"> datefield </a> &#183; <a href="tklib/files/modules/widget/widget.html"> widget </a> &#183; <a href="tklib/files/modules/widget/widget_dateentry.html"> widget_dateentry </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key58"> diagram </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/apps/dia.html"> dia </a> &#183; <a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key22"> dialog </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/getstring/tk_getString.html"> getstring </a> &#183; <a href="tklib/files/modules/swaplist/swaplist.html"> swaplist </a> &#183; <a href="tklib/files/modules/widget/widget.html"> widget </a>
................................................................................
<td class="#idxright" width="65%">
<a href="tklib/files/modules/ico/ico.html"> ico </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c8">Keywords: G</a>
</th></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key43"> graphical presentation </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key116"> graphics </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_mvg.html"> canvas::mvg </a>
................................................................................
<td class="#idxright" width="65%">
<a href="tklib/files/modules/tooltip/tooltip.html"> tooltip </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c10">Keywords: I</a>
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key53"> i18n </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/khim/khim.html"> khim </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key98"> ico </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/ico/ico.html"> ico </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key120"> imagemagick </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_mvg.html"> canvas::mvg </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key55"> input </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/khim/khim.html"> khim </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key92"> insert tag </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_tags.html"> canvas::tag </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key54"> international </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/khim/khim.html"> khim </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key84"> interpolation </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key18"> irc </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/chatwidget/chatwidget.html"> chatwidget </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key46"> isometric plots </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c11">Keywords: L</a>
</th></tr>
<tr class="#idxodd" valign=top>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key83"> line </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key129"> list entry panel </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a> &#183; <a href="tklib/files/modules/widgetl/widget_listsimple.html"> widget_listsimple </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key146"> listbox </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/swaplist/swaplist.html"> swaplist </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key31"> menu </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widget/widget.html"> widget </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key57"> method </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/khim/khim.html"> khim </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key89"> move </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key62"> pie </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/tkpiechart/canvaslabel.html"> canvasLabel </a> &#183; <a href="tklib/files/modules/tkpiechart/pie.html"> pie </a> &#183; <a href="tklib/files/modules/tkpiechart/pieboxlabeler.html"> pieBoxLabeler </a> &#183; <a href="tklib/files/modules/tkpiechart/pieperipherallabeler.html"> piePeripheralLabeler </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key49"> pie charts </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key143"> pixel </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/apps/bitmap-editor.html"> bitmap-editor </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key79"> plane geometry </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key45"> plotting </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a> &#183; <a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key75"> point </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key123"> points </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_epoints.html"> canvas::edit::points </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key38"> polar plots </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key111"> polyline </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_epolyline.html"> canvas::edit::polyline </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key118"> serialization </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_mvg.html"> canvas::mvg </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key128"> set entry panel </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetl/widget_listentry.html"> widget_listentry </a> &#183; <a href="tklib/files/modules/widgetl/widget_listsimple.html"> widget_listsimple </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key61"> slice </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/tkpiechart/canvaslabel.html"> canvasLabel </a> &#183; <a href="tklib/files/modules/tkpiechart/pie.html"> pie </a> &#183; <a href="tklib/files/modules/tkpiechart/pieboxlabeler.html"> pieBoxLabeler </a> &#183; <a href="tklib/files/modules/tkpiechart/pieperipherallabeler.html"> piePeripheralLabeler </a>
................................................................................
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key137"> string </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/getstring/tk_getString.html"> getstring </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key51"> strip charts </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key27"> superframe </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widget/widget.html"> widget </a>
................................................................................
<td class="#idxright" width="65%">
<a href="tklib/files/modules/ctext/ctext.html"> ctext </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c18">Keywords: T</a>
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key40"> tables </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key94"> tags </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_tags.html"> canvas::tag </a>
................................................................................
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key34"> tile </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_sqmap.html"> canvas::sqmap </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key41"> time charts </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key23"> toolbar </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widget/widget.html"> widget </a> &#183; <a href="tklib/files/modules/widget/widget_toolbar.html"> widget_toolbar </a>
................................................................................
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key69"> validation </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/widgetv/widget_validator.html"> widget_validator </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key60"> vector </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/apps/dia.html"> dia </a> &#183; <a href="tklib/files/modules/diagrams/diagram.html"> diagram </a>
</td></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key115"> vector graphics </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_mvg.html"> canvas::mvg </a>
................................................................................
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key145"> xbm </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/apps/bitmap-editor.html"> bitmap-editor </a>
</td></tr>
<tr class="#idxeven" valign=top>
<td class="#idxleft" width="35%"><a name="key44"> xy-plots </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/plotchart/plotchart.html"> Plotchart </a>
</td></tr>
<tr class="#idxheader"><th colspan="2">
<a name="c22">Keywords: Z</a>
</th></tr>
<tr class="#idxodd" valign=top>
<td class="#idxleft" width="35%"><a name="key136"> zoom </a></td>
<td class="#idxright" width="65%">
<a href="tklib/files/modules/canvas/canvas_zoom.html"> canvas::zoom </a>
</td></tr>
</table>
</body></html>

   -->
<! -- Copyright &copy; 
   -->
<! -- CVS: $Id$ bitmap-editor.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../toc.html">Main Table Of Contents</a>
| <a href="../../toc.html">Table Of Contents</a>
| <a href="../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">bitmap-editor(n) 1.0 tklib &quot;Bitmap handling&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>bitmap-editor - Editor for XBM images</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

   -->
<! -- Copyright &copy; 
   -->
<! -- CVS: $Id$ bitmap-editor.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../home">Tcllib Home</a>
| <a href="../../../toc.html">Main Table Of Contents</a>
| <a href="../../toc.html">Table Of Contents</a>
| <a href="../../../index.html">Keyword Index</a>
| <a href="../../../toc0.html">Categories</a>
| <a href="../../../toc1.html">Modules</a>
| <a href="../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">bitmap-editor(n) 1.0 tklib &quot;Bitmap handling&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>bitmap-editor - Editor for XBM images</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

   -->
<! -- Copyright &copy; 2010 Andreas Kupries &lt;andreas_kupries@users.sourceforge.net&gt;
   -->
<! -- CVS: $Id$ dia.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../toc.html">Main Table Of Contents</a>
| <a href="../../toc.html">Table Of Contents</a>
| <a href="../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">dia(n) 1.0 tklib &quot;Documentation toolbox&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>dia - Lightweight Diagram Processor</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
................................................................................
<dt>(handle) <i class="arg">format</i> (in)</dt>
<dd><p>This argument specifies the image format to convert the diagrams into
when processing the input. The application recognizes all formats
supported by the <b class="package">Img</b> package, i.e. for which it can load a
package <b class="package">img::<b class="variable">format</b></b></p></dd>
<dt>path <i class="arg">inputfile</i> (in)</dt>
<dd><p>This argument specifies the path to the diagram file to process. It
has to exist, must be readable, and written in <i class="term"><a href="../../../index.html#key38">diagram</a></i> format.</p></dd>
</dl></dd>
</dl>
</div>
</div>
<div id="section2" class="section"><h2><a name="section2">BUGS, IDEAS, FEEDBACK</a></h2>
<p>This document, and the application it describes, will undoubtedly
contain bugs and other problems.
Please report such in the category <em>diagram</em> of the
<a href="http://sourceforge.net/tracker/?group_id=12883">Tcllib SF Trackers</a>.
Please also report any ideas for enhancements you may have for either
application and/or documentation.</p>
</div>
<div id="keywords" class="section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../index.html#key1">canvas</a>, <a href="../../../index.html#key39">conversion</a>, <a href="../../../index.html#key38">diagram</a>, <a href="../../../index.html#key40">vector</a></p>
</div>
<div id="category" class="section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; 2010 Andreas Kupries &lt;andreas_kupries@users.sourceforge.net&gt;</p>
</div>
</div></body></html>

   -->
<! -- Copyright &copy; 2010 Andreas Kupries &lt;andreas_kupries@users.sourceforge.net&gt;
   -->
<! -- CVS: $Id$ dia.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../home">Tcllib Home</a>
| <a href="../../../toc.html">Main Table Of Contents</a>
| <a href="../../toc.html">Table Of Contents</a>
| <a href="../../../index.html">Keyword Index</a>
| <a href="../../../toc0.html">Categories</a>
| <a href="../../../toc1.html">Modules</a>
| <a href="../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">dia(n) 1.0 tklib &quot;Documentation toolbox&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>dia - Lightweight Diagram Processor</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
................................................................................
<dt>(handle) <i class="arg">format</i> (in)</dt>
<dd><p>This argument specifies the image format to convert the diagrams into
when processing the input. The application recognizes all formats
supported by the <b class="package">Img</b> package, i.e. for which it can load a
package <b class="package">img::<b class="variable">format</b></b></p></dd>
<dt>path <i class="arg">inputfile</i> (in)</dt>
<dd><p>This argument specifies the path to the diagram file to process. It
has to exist, must be readable, and written in <i class="term"><a href="../../../index.html#key58">diagram</a></i> format.</p></dd>
</dl></dd>
</dl>
</div>
</div>
<div id="section2" class="section"><h2><a name="section2">BUGS, IDEAS, FEEDBACK</a></h2>
<p>This document, and the application it describes, will undoubtedly
contain bugs and other problems.
Please report such in the category <em>diagram</em> of the
<a href="http://sourceforge.net/tracker/?group_id=12883">Tcllib SF Trackers</a>.
Please also report any ideas for enhancements you may have for either
application and/or documentation.</p>
</div>
<div id="keywords" class="section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../index.html#key1">canvas</a>, <a href="../../../index.html#key59">conversion</a>, <a href="../../../index.html#key58">diagram</a>, <a href="../../../index.html#key60">vector</a></p>
</div>
<div id="category" class="section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; 2010 Andreas Kupries &lt;andreas_kupries@users.sourceforge.net&gt;</p>
</div>
</div></body></html>

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/autoscroll/autoscroll.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ autoscroll.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">autoscroll(n) 1.1 tklib &quot;Automatic mapping of scrollbars&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>autoscroll - Provides for a scrollbar to automatically mapped and unmapped as needed</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/autoscroll/autoscroll.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ autoscroll.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">autoscroll(n) 1.1 tklib &quot;Automatic mapping of scrollbars&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>autoscroll - Provides for a scrollbar to automatically mapped and unmapped as needed</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_drag.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::drag.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">canvas::drag(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::drag - Manage the dragging of canvas items or item groups</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_drag.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::drag.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">canvas::drag(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::drag - Manage the dragging of canvas items or item groups</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_epoints.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::edit::points.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">canvas::edit::points(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::edit::points - Editing a cloud of points on a canvas</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_epoints.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::edit::points.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">canvas::edit::points(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::edit::points - Editing a cloud of points on a canvas</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_epolyline.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::edit::polyline.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">canvas::edit::polyline(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::edit::polyline - Editing a polyline on a canvas</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_epolyline.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::edit::polyline.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">canvas::edit::polyline(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::edit::polyline - Editing a polyline on a canvas</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_equad.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::edit::quadrilateral.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">canvas::edit::quadrilateral(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::edit::quadrilateral - Editing a quadrilateral on a canvas</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_equad.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::edit::quadrilateral.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">canvas::edit::quadrilateral(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::edit::quadrilateral - Editing a quadrilateral on a canvas</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_highlight.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::highlight.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">canvas::highlight(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::highlight - Manage the highlighting of canvas items or item groups</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_highlight.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::highlight.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">canvas::highlight(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::highlight - Manage the highlighting of canvas items or item groups</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

   -->
<! -- Copyright &copy; 2010 Wolf-Dieter Busch (http://wiki.tcl.tk/15505)   -- Copyright &copy; 2010 Documentation, Andreas Kupries
   -->
<! -- CVS: $Id$ canvas::mvg.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">canvas::mvg(n) 1.0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::mvg - Canvas to ImageMagick MVG vector format</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

   -->
<! -- Copyright &copy; 2010 Wolf-Dieter Busch (http://wiki.tcl.tk/15505)   -- Copyright &copy; 2010 Documentation, Andreas Kupries
   -->
<! -- CVS: $Id$ canvas::mvg.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">canvas::mvg(n) 1.0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::mvg - Canvas to ImageMagick MVG vector format</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

   -->
<! -- Copyright &copy; 2004 George Petasis (http://wiki.tcl.tk/1404)   -- Copyright &copy; 2010 Documentation, Andreas Kupries
   -->
<! -- CVS: $Id$ canvas::snap.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">canvas::snap(n) 1.0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::snap - Canvas snapshot to Tk photo image</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

   -->
<! -- Copyright &copy; 2004 George Petasis (http://wiki.tcl.tk/1404)   -- Copyright &copy; 2010 Documentation, Andreas Kupries
   -->
<! -- CVS: $Id$ canvas::snap.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">canvas::snap(n) 1.0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::snap - Canvas snapshot to Tk photo image</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_sqmap.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::sqmap.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">canvas::sqmap(n) 0.3.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::sqmap - Canvas with map background based on square tiles</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_sqmap.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::sqmap.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">canvas::sqmap(n) 0.3.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::sqmap - Canvas with map background based on square tiles</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_tags.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::tag.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">canvas::tag(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::tag - Easier management of the tags on canvas items or item groups</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_tags.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::tag.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">canvas::tag(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::tag - Easier management of the tags on canvas items or item groups</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_trlines.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::track::lines.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">canvas::track::lines(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::track::lines - Manage a group of rubber band lines</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_trlines.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::track::lines.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">canvas::track::lines(n) 0.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::track::lines - Manage a group of rubber band lines</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_zoom.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::zoom.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">canvas::zoom(n) 0.2.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::zoom - Zoom control for canvas::sqmap</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/canvas/canvas_zoom.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ canvas::zoom.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">canvas::zoom(n) 0.2.1 tklib &quot;Variations on a canvas&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>canvas::zoom - Zoom control for canvas::sqmap</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/chatwidget/chatwidget.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ chatwidget.n
   -->
<body><div class="doctools">
<hr> [
   <a href="/tklib">Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>



 ] <hr>
<h1 class="title">chatwidget(n) 1.0.0 tklib &quot;Composite widget for chat applications&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>chatwidget - Provides a multi-paned view suitable for display of chat room or irc channel information</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">

</head>
<! -- Generated from file '/net/nas/data/andreask/Dev/Tcllib/tklib/embedded/www/tklib/files/modules/chatwidget/chatwidget.html' by tcllib/doctools with format 'html'
   -->
<! -- CVS: $Id$ chatwidget.n
   -->
<body><div class="doctools">
<hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<h1 class="title">chatwidget(n) 1.0.0 tklib &quot;Composite widget for chat applications&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>chatwidget - Provides a multi-paned view suitable for display of chat room or irc channel information</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">