2 '\" Copyright (c) 1993-1998 Lucent Technologies, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH code n 3.0 itcl "[incr\ Tcl]"
8 '\" The definitions below are for supplemental macros used in Tcl/Tk
11 '\" .AP type name in/out ?indent?
12 '\" Start paragraph describing an argument to a library procedure.
13 '\" type is type of argument (int, etc.), in/out is either "in", "out",
14 '\" or "in/out" to describe whether procedure reads or modifies arg,
15 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 '\" needed; use .AS below instead)
19 '\" Give maximum sizes of arguments for setting tab stops. Type and
20 '\" name are examples of largest possible arguments that will be passed
21 '\" to .AP later. If args are omitted, default tab stops are used.
24 '\" Start box enclosure. From here until next .BE, everything will be
25 '\" enclosed in one large box.
28 '\" End of box enclosure.
31 '\" Begin code excerpt.
36 '\" .VS ?version? ?br?
37 '\" Begin vertical sidebar, for use in marking newly-changed parts
38 '\" of man pages. The first argument is ignored and used for recording
39 '\" the version when the .VS was added, so that the sidebars can be
40 '\" found and removed when they reach a certain age. If another argument
41 '\" is present, then a line break is forced before starting the sidebar.
44 '\" End of vertical sidebar.
47 '\" Begin an indented unfilled display.
50 '\" End of indented unfilled display.
53 '\" Start of list of standard options for a Tk widget. The
54 '\" options follow on successive lines, in four columns separated
58 '\" End of list of standard options for a Tk widget.
60 '\" .OP cmdName dbName dbClass
61 '\" Start of description of a specific option. cmdName gives the
62 '\" option's name as specified in the class command, dbName gives
63 '\" the option's name in the option database, and dbClass gives
64 '\" the option's class in the option database.
67 '\" Print arg1 underlined, then print arg2 normally.
69 '\" SCCS: @(#) man.macros 1.9 97/08/22 18:50:59
71 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
75 '\" # Start an argument description
79 . ie !"\\$2"" .TP \\n()Cu
84 \&\\$1 \\fI\\$2\\fP (\\$3)
97 '\" # define tabbing values for .AP
100 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
103 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
104 .nr )C \\n()Bu+\\w'(in/out)'u+2n
106 .AS Tcl_Interp Tcl_CreateInterp in/out
107 '\" # BS - start boxed text
108 '\" # ^y = starting y location
116 .if n \l'\\n(.lu\(ul'
119 '\" # BE - end boxed text (draw box now)
124 .ie n \l'\\n(^lu\(ul'
126 .\" Draw four-sided box normally, but don't draw top of
127 .\" box if the box started on an earlier page.
129 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
132 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 '\" # VS - start vertical sidebar
140 '\" # ^Y = starting y location
141 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
145 .ie n 'mc \s12\(br\s0
148 '\" # VE - end of vertical sidebar
156 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
163 '\" # Special macro to handle page bottom: finish off current
164 '\" # box/sidebar if in box/sidebar mode, then invoked standard
165 '\" # page bottom macro.
172 .\" Draw three-sided box if this is the box's first page,
173 .\" draw two sides but no top otherwise.
174 .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
175 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
178 .nr ^x \\n(^tu+1v-\\n(^Yu
179 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
192 '\" # DS - begin display
198 '\" # DE - end display
204 '\" # SO - start of list of standard options
206 .SH "STANDARD OPTIONS"
212 '\" # SE - end of list of standard options
217 See the \\fBoptions\\fR manual entry for details on the standard options.
219 '\" # OP - start of full description for a single option
224 Command-Line Name: \\fB\\$1\\fR
225 Database Name: \\fB\\$2\\fR
226 Database Class: \\fB\\$3\\fR
230 '\" # CS - begin code excerpt
236 '\" # CE - end code excerpt
245 '\" Note: do not modify the .SH NAME line immediately below!
247 itcl::code \- capture the namespace context for a code fragment
249 \fBitcl::code \fR?\fB-namespace \fIname\fR? \fIcommand \fR?\fIarg arg ...\fR?
254 Creates a scoped value for the specified \fIcommand\fR and its
255 associated \fIarg\fR arguments. A scoped value is a list with three
256 elements: the "\fC@scope\fR" keyword, a namespace context,
257 and a value string. For example, the command
260 code puts "Hello World!"
263 produces the scoped value:
265 @scope ::foo {puts {Hello World!}}
267 Note that the \fBcode\fR command captures the current namespace
268 context. If the \fB-namespace\fR flag is specified, then the
269 current context is ignored, and the \fIname\fR string is used
270 as the namespace context.
272 Extensions like Tk execute ordinary code fragments in the global
273 namespace. A scoped value captures a code fragment together with
274 its namespace context in a way that allows it to be executed
275 properly later. It is needed, for example, to wrap up code fragments
276 when a Tk widget is used within a namespace:
279 private proc report {mesg} {
283 button .b1 -text "Push Me" \
284 -command [code report "Hello World!"]
288 The code fragment associated with button \fC.b1\fR only makes
289 sense in the context of namespace "foo". Furthermore, the
290 "report" procedure is private, and can only be accessed within
291 that namespace. The \fBcode\fR command wraps up the code
292 fragment in a way that allows it to be executed properly
293 when the button is pressed.
295 Also, note that the \fBcode\fR command preserves the integrity
296 of arguments on the command line. This makes it a natural replacement
297 for the \fBlist\fR command, which is often used to format Tcl code
298 fragments. In other words, instead of using the \fBlist\fR command
301 after 1000 [list puts "Hello $name!"]
303 use the \fBcode\fR command like this:
305 after 1000 [code puts "Hello $name!"]
307 This not only formats the command correctly, but also captures
308 its namespace context.
310 Scoped commands can be invoked like ordinary code fragments, with
311 or without the \fBeval\fR command. For example, the following
312 statements work properly:
314 set cmd {@scope ::foo .b1}
315 $cmd configure -background red
317 set opts {-bg blue -fg white}
318 eval $cmd configure $opts
320 Note that scoped commands by-pass the usual protection mechanisms;
323 @scope ::foo {report {Hello World!}}
325 can be used to access the "foo::report" proc from any namespace
326 context, even though it is private.
329 scope, callback, namespace, public, protected, private