man/mann/itclvars.n - toolchains/skids - Git at Google

 '\"
 '\" Copyright (c) 1993-1998  Lucent Technologies, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
 '\" RCS: $Id: itclvars.n,v 1.1 1998/07/27 18:42:02 stanton Exp $
 '\"
 '\" 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",
 '\"	or "in/out" to describe whether procedure reads or modifies arg,
 '\"	and indent is equivalent to second arg of .IP (shouldn't ever be
 '\"	needed;  use .AS below instead)
 '\"
 '\" .AS ?type? ?name?
 '\"	Give maximum sizes of arguments for setting tab stops.  Type and
 '\"	name are examples of largest possible arguments that will be passed
 '\"	to .AP later.  If args are omitted, default tab stops are used.
 '\"
 '\" .BS
 '\"	Start box enclosure.  From here until next .BE, everything will be
 '\"	enclosed in one large box.
 '\"
 '\" .BE
 '\"	End of box enclosure.
 '\"
 '\" .CS
 '\"	Begin code excerpt.
 '\"
 '\" .CE
 '\"	End code excerpt.
 '\"
 '\" .VS ?version? ?br?
 '\"	Begin vertical sidebar, for use in marking newly-changed parts
 '\"	of man pages.  The first argument is ignored and used for recording
 '\"	the version when the .VS was added, so that the sidebars can be
 '\"	found and removed when they reach a certain age.  If another argument
 '\"	is present, then a line break is forced before starting the sidebar.
 '\"
 '\" .VE
 '\"	End of vertical sidebar.
 '\"
 '\" .DS
 '\"	Begin an indented unfilled display.
 '\"
 '\" .DE
 '\"	End of indented unfilled display.
 '\"
 '\" .SO
 '\"	Start of list of standard options for a Tk widget.  The
 '\"	options follow on successive lines, in four columns separated
 '\"	by tabs.
 '\"
 '\" .SE
 '\"	End of list of standard options for a Tk widget.
 '\"
 '\" .OP cmdName dbName dbClass
 '\"	Start of description of a specific option.  cmdName gives the
 '\"	option's name as specified in the class command, dbName gives
 '\"	the option's name in the option database, and dbClass gives
 '\"	the option's class in the option database.
 '\"
 '\" .UL arg1 arg2
 '\"	Print arg1 underlined, then print arg2 normally.
 '\"
 '\" SCCS: @(#) man.macros 1.9 97/08/22 18:50:59
 '\"
 '\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
 .if t .wh -1.3i ^B
 .nr ^l \n(.l
 .ad b
 '\"	# Start an argument description
 .de AP
 .ie !"\\$4"" .TP \\$4
 .el \{\
 .   ie !"\\$2"" .TP \\n()Cu
 .   el          .TP 15
 .\}
 .ie !"\\$3"" \{\
 .ta \\n()Au \\n()Bu
 \&\\$1	\\fI\\$2\\fP	(\\$3)
 .\".b
 .\}
 .el \{\
 .br
 .ie !"\\$2"" \{\
 \&\\$1	\\fI\\$2\\fP
 .\}
 .el \{\
 \&\\fI\\$1\\fP
 .\}
 .\}
 ..
 '\"	# define tabbing values for .AP
 .de AS
 .nr )A 10n
 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 .nr )B \\n()Au+15n
 .\"
 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 ..
 .AS Tcl_Interp Tcl_CreateInterp in/out
 '\"	# BS - start boxed text
 '\"	# ^y = starting y location
 '\"	# ^b = 1
 .de BS
 .br
 .mk ^y
 .nr ^b 1u
 .if n .nf
 .if n .ti 0
 .if n \l'\\n(.lu\(ul'
 .if n .fi
 ..
 '\"	# BE - end boxed text (draw box now)
 .de BE
 .nf
 .ti 0
 .mk ^t
 .ie n \l'\\n(^lu\(ul'
 .el \{\
 .\"	Draw four-sided box normally, but don't draw top of
 .\"	box if the box started on an earlier page.
 .ie !\\n(^b-1 \{\
 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 .\}
 .el \}\
 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 .\}
 .\}
 .fi
 .br
 .nr ^b 0
 ..
 '\"	# VS - start vertical sidebar
 '\"	# ^Y = starting y location
 '\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
 .de VS
 .if !"\\$2"" .br
 .mk ^Y
 .ie n 'mc \s12\(br\s0
 .el .nr ^v 1u
 ..
 '\"	# VE - end of vertical sidebar
 .de VE
 .ie n 'mc
 .el \{\
 .ev 2
 .nf
 .ti 0
 .mk ^t
 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 .sp -1
 .fi
 .ev
 .\}
 .nr ^v 0
 ..
 '\"	# Special macro to handle page bottom:  finish off current
 '\"	# box/sidebar if in box/sidebar mode, then invoked standard
 '\"	# page bottom macro.
 .de ^B
 .ev 2
 'ti 0
 'nf
 .mk ^t
 .if \\n(^b \{\
 .\"	Draw three-sided box if this is the box's first page,
 .\"	draw two sides but no top otherwise.
 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 .\}
 .if \\n(^v \{\
 .nr ^x \\n(^tu+1v-\\n(^Yu
 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 .\}
 .bp
 'fi
 .ev
 .if \\n(^b \{\
 .mk ^y
 .nr ^b 2
 .\}
 .if \\n(^v \{\
 .mk ^Y
 .\}
 ..
 '\"	# DS - begin display
 .de DS
 .RS
 .nf
 .sp
 ..
 '\"	# DE - end display
 .de DE
 .fi
 .RE
 .sp
 ..
 '\"	# SO - start of list of standard options
 .de SO
 .SH "STANDARD OPTIONS"
 .LP
 .nf
 .ta 4c 8c 12c
 .ft B
 ..
 '\"	# SE - end of list of standard options
 .de SE
 .fi
 .ft R
 .LP
 See the \\fBoptions\\fR manual entry for details on the standard options.
 ..
 '\"	# OP - start of full description for a single option
 .de OP
 .LP
 .nf
 .ta 4c
 Command-Line Name:	\\fB\\$1\\fR
 Database Name:	\\fB\\$2\\fR
 Database Class:	\\fB\\$3\\fR
 .fi
 .IP
 ..
 '\"	# CS - begin code excerpt
 .de CS
 .RS
 .nf
 .ta .25i .5i .75i 1i
 ..
 '\"	# CE - end code excerpt
 .de CE
 .fi
 .RE
 ..
 .de UL
 \\$1\l'|0\(ul'\\$2
 ..
 .TH itclvars n 3.0 itcl "[incr\ Tcl]"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 itclvars \- variables used by [incr\ Tcl]
 .BE

 .SH DESCRIPTION
 .PP
 The following global variables are created and managed automatically
 by the \fB[incr\ Tcl]\fR library.  Except where noted below, these
 variables should normally be treated as read-only by application-specific
 code and by users.
 .TP
 \fBitcl::library\fR
 When an interpreter is created, \fB[incr\ Tcl]\fR initializes this variable
 to hold the name of a directory containing the system library of
 \fB[incr\ Tcl]\fR scripts.  The initial value of \fBitcl::library\fR
 is set from the ITCL_LIBRARY environment variable if it exists,
 or from a compiled-in value otherwise.
 .TP
 \fBitcl::patchLevel\fR
 When an interpreter is created, \fB[incr\ Tcl]\fR initializes this
 variable to hold the current patch level for \fB[incr\ Tcl]\fR.
 For example, the value "\fB2.0p1\fR" indicates \fB[incr\ Tcl]\fR
 version 2.0 with the first set of patches applied.
 .TP
 \fBitcl::purist\fR
 When an interpreter is created containing Tcl/Tk and the
 \fB[incr\ Tcl]\fR namespace facility, this variable controls
 a "backward-compatibility" mode for widget access.
 .sp
 In vanilla Tcl/Tk, there is a single pool of commands, so the
 access command for a widget is the same as the window name.
 When a widget is created within a namespace, however, its access
 command is installed in that namespace, and should be accessed
 outside of the namespace using a qualified name.  For example,
 .CS
 namespace foo {
     namespace bar {
         button .b -text "Testing"
     }
 }
 foo::bar::.b configure -background red
 pack .b
 .CE
 Note that the window name "\fC.b\fR" is still used in conjunction
 with commands like \fBpack\fR and \fBdestroy\fR.  However, the
 access command for the widget (i.e., name that appears as the
 \fIfirst\fR argument on a command line) must be more specific.
 .sp
 The "\fBwinfo command\fR" command can be used to query the
 fully-qualified access command for any widget, so one can write:
 .CS
 [winfo command .b] configure -background red
 .CE
 and this is good practice when writing library procedures.  Also,
 in conjunction with the \fBbind\fR command, the "%q" field can be
 used in place of "%W" as the access command:
 .CS
 bind Button <Key-Return> {%q flash; %q invoke}
 .CE
 While this behavior makes sense from the standpoint of encapsulation,
 it causes problems with existing Tcl/Tk applications.  Many existing
 applications are written with bindings that use "%W".  Many
 library procedures assume that the window name is the access
 command.
 .sp
 The \fBitcl::purist\fR variable controls a backward-compatibility
 mode.  By default, this variable is "0", and the window name
 can be used as an access command in any context.  Whenever the
 \fBunknown\fR procedure stumbles across a widget name, it simply
 uses "\fBwinfo command\fR" to determine the appropriate command
 name.  If this variable is set to "1", this backward-compatibility
 mode is disabled.  This gives better encapsulation, but using the
 window name as the access command may lead to "invalid command"
 errors.
 .TP
 \fBitcl::version\fR
 When an interpreter is created, \fB[incr\ Tcl]\fR initializes this
 variable to hold the version number of the form \fIx.y\fR.
 Changes to \fIx\fR represent major changes with probable
 incompatibilities and changes to \fIy\fR represent small enhancements
 and bug fixes that retain backward compatibility.

 .SH KEYWORDS
 itcl, variables
	'\"
	'\" Copyright (c) 1993-1998 Lucent Technologies, Inc.
	'\"
	'\" See the file "license.terms" for information on usage and redistribution
	'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
	'\"
	'\" RCS: $Id: itclvars.n,v 1.1 1998/07/27 18:42:02 stanton Exp $
	'\"
	'\" 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",
	'\" or "in/out" to describe whether procedure reads or modifies arg,
	'\" and indent is equivalent to second arg of .IP (shouldn't ever be
	'\" needed; use .AS below instead)
	'\"
	'\" .AS ?type? ?name?
	'\" Give maximum sizes of arguments for setting tab stops. Type and
	'\" name are examples of largest possible arguments that will be passed
	'\" to .AP later. If args are omitted, default tab stops are used.
	'\"
	'\" .BS
	'\" Start box enclosure. From here until next .BE, everything will be
	'\" enclosed in one large box.
	'\"
	'\" .BE
	'\" End of box enclosure.
	'\"
	'\" .CS
	'\" Begin code excerpt.
	'\"
	'\" .CE
	'\" End code excerpt.
	'\"
	'\" .VS ?version? ?br?
	'\" Begin vertical sidebar, for use in marking newly-changed parts
	'\" of man pages. The first argument is ignored and used for recording
	'\" the version when the .VS was added, so that the sidebars can be
	'\" found and removed when they reach a certain age. If another argument
	'\" is present, then a line break is forced before starting the sidebar.
	'\"
	'\" .VE
	'\" End of vertical sidebar.
	'\"
	'\" .DS
	'\" Begin an indented unfilled display.
	'\"
	'\" .DE
	'\" End of indented unfilled display.
	'\"
	'\" .SO
	'\" Start of list of standard options for a Tk widget. The
	'\" options follow on successive lines, in four columns separated
	'\" by tabs.
	'\"
	'\" .SE
	'\" End of list of standard options for a Tk widget.
	'\"
	'\" .OP cmdName dbName dbClass
	'\" Start of description of a specific option. cmdName gives the
	'\" option's name as specified in the class command, dbName gives
	'\" the option's name in the option database, and dbClass gives
	'\" the option's class in the option database.
	'\"
	'\" .UL arg1 arg2
	'\" Print arg1 underlined, then print arg2 normally.
	'\"
	'\" SCCS: @(#) man.macros 1.9 97/08/22 18:50:59
	'\"
	'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
	.if t .wh -1.3i ^B
	.nr ^l \n(.l
	.ad b
	'\" # Start an argument description
	.de AP
	.ie !"\\$4"" .TP \\$4
	.el \{\
	. ie !"\\$2"" .TP \\n()Cu
	. el .TP 15
	.\}
	.ie !"\\$3"" \{\
	.ta \\n()Au \\n()Bu
	\&\\$1 \\fI\\$2\\fP (\\$3)
	.\".b
	.\}
	.el \{\
	.br
	.ie !"\\$2"" \{\
	\&\\$1 \\fI\\$2\\fP
	.\}
	.el \{\
	\&\\fI\\$1\\fP
	.\}
	.\}
	..
	'\" # define tabbing values for .AP
	.de AS
	.nr )A 10n
	.if !"\\$1"" .nr )A \\w'\\$1'u+3n
	.nr )B \\n()Au+15n
	.\"
	.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
	.nr )C \\n()Bu+\\w'(in/out)'u+2n
	..
	.AS Tcl_Interp Tcl_CreateInterp in/out
	'\" # BS - start boxed text
	'\" # ^y = starting y location
	'\" # ^b = 1
	.de BS
	.br
	.mk ^y
	.nr ^b 1u
	.if n .nf
	.if n .ti 0
	.if n \l'\\n(.lu\(ul'
	.if n .fi
	..
	'\" # BE - end boxed text (draw box now)
	.de BE
	.nf
	.ti 0
	.mk ^t
	.ie n \l'\\n(^lu\(ul'
	.el \{\
	.\" Draw four-sided box normally, but don't draw top of
	.\" box if the box started on an earlier page.
	.ie !\\n(^b-1 \{\
	\h'-1.5n'\L'\|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'\|0u-1.5n\(ul'
	.\}
	.el \}\
	\h'-1.5n'\L'\|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'\|0u-1.5n\(ul'
	.\}
	.\}
	.fi
	.br
	.nr ^b 0
	..
	'\" # VS - start vertical sidebar
	'\" # ^Y = starting y location
	'\" # ^v = 1 (for troff; for nroff this doesn't matter)
	.de VS
	.if !"\\$2"" .br
	.mk ^Y
	.ie n 'mc \s12\(br\s0
	.el .nr ^v 1u
	..
	'\" # VE - end of vertical sidebar
	.de VE
	.ie n 'mc
	.el \{\
	.ev 2
	.nf
	.ti 0
	.mk ^t
	\h'\|\\n(^lu+3n'\L'\|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-\|\\n(^lu+3n'
	.sp -1
	.fi
	.ev
	.\}
	.nr ^v 0
	..
	'\" # Special macro to handle page bottom: finish off current
	'\" # box/sidebar if in box/sidebar mode, then invoked standard
	'\" # page bottom macro.
	.de ^B
	.ev 2
	'ti 0
	'nf
	.mk ^t
	.if \\n(^b \{\
	.\" Draw three-sided box if this is the box's first page,
	.\" draw two sides but no top otherwise.
	.ie !\\n(^b-1 \h'-1.5n'\L'\|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'\|0u'\c
	.el \h'-1.5n'\L'\|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'\|0u'\c
	.\}
	.if \\n(^v \{\
	.nr ^x \\n(^tu+1v-\\n(^Yu
	\kx\h'-\\nxu'\h'\|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'\|0u'\c
	.\}
	.bp
	'fi
	.ev
	.if \\n(^b \{\
	.mk ^y
	.nr ^b 2
	.\}
	.if \\n(^v \{\
	.mk ^Y
	.\}
	..
	'\" # DS - begin display
	.de DS
	.RS
	.nf
	.sp
	..
	'\" # DE - end display
	.de DE
	.fi
	.RE
	.sp
	..
	'\" # SO - start of list of standard options
	.de SO
	.SH "STANDARD OPTIONS"
	.LP
	.nf
	.ta 4c 8c 12c
	.ft B
	..
	'\" # SE - end of list of standard options
	.de SE
	.fi
	.ft R
	.LP
	See the \\fBoptions\\fR manual entry for details on the standard options.
	..
	'\" # OP - start of full description for a single option
	.de OP
	.LP
	.nf
	.ta 4c
	Command-Line Name: \\fB\\$1\\fR
	Database Name: \\fB\\$2\\fR
	Database Class: \\fB\\$3\\fR
	.fi
	.IP
	..
	'\" # CS - begin code excerpt
	.de CS
	.RS
	.nf
	.ta .25i .5i .75i 1i
	..
	'\" # CE - end code excerpt
	.de CE
	.fi
	.RE
	..
	.de UL
	\\$1\l'\|0\(ul'\\$2
	..
	.TH itclvars n 3.0 itcl "[incr\ Tcl]"
	.BS
	'\" Note: do not modify the .SH NAME line immediately below!
	.SH NAME
	itclvars \- variables used by [incr\ Tcl]
	.BE

	.SH DESCRIPTION
	.PP
	The following global variables are created and managed automatically
	by the \fB[incr\ Tcl]\fR library. Except where noted below, these
	variables should normally be treated as read-only by application-specific
	code and by users.
	.TP
	\fBitcl::library\fR
	When an interpreter is created, \fB[incr\ Tcl]\fR initializes this variable
	to hold the name of a directory containing the system library of
	\fB[incr\ Tcl]\fR scripts. The initial value of \fBitcl::library\fR
	is set from the ITCL_LIBRARY environment variable if it exists,
	or from a compiled-in value otherwise.
	.TP
	\fBitcl::patchLevel\fR
	When an interpreter is created, \fB[incr\ Tcl]\fR initializes this
	variable to hold the current patch level for \fB[incr\ Tcl]\fR.
	For example, the value "\fB2.0p1\fR" indicates \fB[incr\ Tcl]\fR
	version 2.0 with the first set of patches applied.
	.TP
	\fBitcl::purist\fR
	When an interpreter is created containing Tcl/Tk and the
	\fB[incr\ Tcl]\fR namespace facility, this variable controls
	a "backward-compatibility" mode for widget access.
	.sp
	In vanilla Tcl/Tk, there is a single pool of commands, so the
	access command for a widget is the same as the window name.
	When a widget is created within a namespace, however, its access
	command is installed in that namespace, and should be accessed
	outside of the namespace using a qualified name. For example,
	.CS
	namespace foo {
	namespace bar {
	button .b -text "Testing"
	}
	}
	foo::bar::.b configure -background red
	pack .b
	.CE
	Note that the window name "\fC.b\fR" is still used in conjunction
	with commands like \fBpack\fR and \fBdestroy\fR. However, the
	access command for the widget (i.e., name that appears as the
	\fIfirst\fR argument on a command line) must be more specific.
	.sp
	The "\fBwinfo command\fR" command can be used to query the
	fully-qualified access command for any widget, so one can write:
	.CS
	[winfo command .b] configure -background red
	.CE
	and this is good practice when writing library procedures. Also,
	in conjunction with the \fBbind\fR command, the "%q" field can be
	used in place of "%W" as the access command:
	.CS
	bind Button <Key-Return> {%q flash; %q invoke}
	.CE
	While this behavior makes sense from the standpoint of encapsulation,
	it causes problems with existing Tcl/Tk applications. Many existing
	applications are written with bindings that use "%W". Many
	library procedures assume that the window name is the access
	command.
	.sp
	The \fBitcl::purist\fR variable controls a backward-compatibility
	mode. By default, this variable is "0", and the window name
	can be used as an access command in any context. Whenever the
	\fBunknown\fR procedure stumbles across a widget name, it simply
	uses "\fBwinfo command\fR" to determine the appropriate command
	name. If this variable is set to "1", this backward-compatibility
	mode is disabled. This gives better encapsulation, but using the
	window name as the access command may lead to "invalid command"
	errors.
	.TP
	\fBitcl::version\fR
	When an interpreter is created, \fB[incr\ Tcl]\fR initializes this
	variable to hold the version number of the form \fIx.y\fR.
	Changes to \fIx\fR represent major changes with probable
	incompatibilities and changes to \fIy\fR represent small enhancements
	and bug fixes that retain backward compatibility.

	.SH KEYWORDS
	itcl, variables