'\"
|
'\"
|
'\" Copyright (c) 1993-1998 Lucent Technologies, Inc.
|
'\" Copyright (c) 1993-1998 Lucent Technologies, Inc.
|
'\"
|
'\"
|
'\" See the file "license.terms" for information on usage and redistribution
|
'\" See the file "license.terms" for information on usage and redistribution
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
'\"
|
'\"
|
'\" RCS: $Id: code.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $
|
'\" RCS: $Id: code.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $
|
'\"
|
'\"
|
.so man.macros
|
.so man.macros
|
.TH code n 3.0 itcl "[incr\ Tcl]"
|
.TH code n 3.0 itcl "[incr\ Tcl]"
|
.BS
|
.BS
|
'\" Note: do not modify the .SH NAME line immediately below!
|
'\" Note: do not modify the .SH NAME line immediately below!
|
.SH NAME
|
.SH NAME
|
code \- capture the namespace context for a code fragment
|
code \- capture the namespace context for a code fragment
|
.SH SYNOPSIS
|
.SH SYNOPSIS
|
\fBcode \fR?\fB-namespace \fIname\fR? \fIcommand \fR?\fIarg arg ...\fR?
|
\fBcode \fR?\fB-namespace \fIname\fR? \fIcommand \fR?\fIarg arg ...\fR?
|
.BE
|
.BE
|
|
|
.SH DESCRIPTION
|
.SH DESCRIPTION
|
.PP
|
.PP
|
Creates a scoped value for the specified \fIcommand\fR and its
|
Creates a scoped value for the specified \fIcommand\fR and its
|
associated \fIarg\fR arguments. A scoped value is a list with three
|
associated \fIarg\fR arguments. A scoped value is a list with three
|
elements: the "\fC@scope\fR" keyword, a namespace context,
|
elements: the "\fC@scope\fR" keyword, a namespace context,
|
and a value string. For example, the command
|
and a value string. For example, the command
|
.CS
|
.CS
|
namespace foo {
|
namespace foo {
|
code puts "Hello World!"
|
code puts "Hello World!"
|
}
|
}
|
.CE
|
.CE
|
produces the scoped value:
|
produces the scoped value:
|
.CS
|
.CS
|
@scope ::foo {puts {Hello World!}}
|
@scope ::foo {puts {Hello World!}}
|
.CE
|
.CE
|
Note that the \fBcode\fR command captures the current namespace
|
Note that the \fBcode\fR command captures the current namespace
|
context. If the \fB-namespace\fR flag is specified, then the
|
context. If the \fB-namespace\fR flag is specified, then the
|
current context is ignored, and the \fIname\fR string is used
|
current context is ignored, and the \fIname\fR string is used
|
as the namespace context.
|
as the namespace context.
|
.PP
|
.PP
|
Extensions like Tk execute ordinary code fragments in the global
|
Extensions like Tk execute ordinary code fragments in the global
|
namespace. A scoped value captures a code fragment together with
|
namespace. A scoped value captures a code fragment together with
|
its namespace context in a way that allows it to be executed
|
its namespace context in a way that allows it to be executed
|
properly later. It is needed, for example, to wrap up code fragments
|
properly later. It is needed, for example, to wrap up code fragments
|
when a Tk widget is used within a namespace:
|
when a Tk widget is used within a namespace:
|
.CS
|
.CS
|
namespace foo {
|
namespace foo {
|
private proc report {mesg} {
|
private proc report {mesg} {
|
puts "click: $mesg"
|
puts "click: $mesg"
|
}
|
}
|
|
|
button .b1 -text "Push Me" \
|
button .b1 -text "Push Me" \
|
-command [code report "Hello World!"]
|
-command [code report "Hello World!"]
|
pack .b1
|
pack .b1
|
}
|
}
|
.CE
|
.CE
|
The code fragment associated with button \fC.b1\fR only makes
|
The code fragment associated with button \fC.b1\fR only makes
|
sense in the context of namespace "foo". Furthermore, the
|
sense in the context of namespace "foo". Furthermore, the
|
"report" procedure is private, and can only be accessed within
|
"report" procedure is private, and can only be accessed within
|
that namespace. The \fBcode\fR command wraps up the code
|
that namespace. The \fBcode\fR command wraps up the code
|
fragment in a way that allows it to be executed properly
|
fragment in a way that allows it to be executed properly
|
when the button is pressed.
|
when the button is pressed.
|
.PP
|
.PP
|
Also, note that the \fBcode\fR command preserves the integrity
|
Also, note that the \fBcode\fR command preserves the integrity
|
of arguments on the command line. This makes it a natural replacement
|
of arguments on the command line. This makes it a natural replacement
|
for the \fBlist\fR command, which is often used to format Tcl code
|
for the \fBlist\fR command, which is often used to format Tcl code
|
fragments. In other words, instead of using the \fBlist\fR command
|
fragments. In other words, instead of using the \fBlist\fR command
|
like this:
|
like this:
|
.CS
|
.CS
|
after 1000 [list puts "Hello $name!"]
|
after 1000 [list puts "Hello $name!"]
|
.CE
|
.CE
|
use the \fBcode\fR command like this:
|
use the \fBcode\fR command like this:
|
.CS
|
.CS
|
after 1000 [code puts "Hello $name!"]
|
after 1000 [code puts "Hello $name!"]
|
.CE
|
.CE
|
This not only formats the command correctly, but also captures
|
This not only formats the command correctly, but also captures
|
its namespace context.
|
its namespace context.
|
.PP
|
.PP
|
Scoped commands can be invoked like ordinary code fragments, with
|
Scoped commands can be invoked like ordinary code fragments, with
|
or without the \fBeval\fR command. For example, the following
|
or without the \fBeval\fR command. For example, the following
|
statements work properly:
|
statements work properly:
|
.CS
|
.CS
|
set cmd {@scope ::foo .b1}
|
set cmd {@scope ::foo .b1}
|
$cmd configure -background red
|
$cmd configure -background red
|
|
|
set opts {-bg blue -fg white}
|
set opts {-bg blue -fg white}
|
eval $cmd configure $opts
|
eval $cmd configure $opts
|
.CE
|
.CE
|
Note that scoped commands by-pass the usual protection mechanisms;
|
Note that scoped commands by-pass the usual protection mechanisms;
|
the command:
|
the command:
|
.CS
|
.CS
|
@scope ::foo {report {Hello World!}}
|
@scope ::foo {report {Hello World!}}
|
.CE
|
.CE
|
can be used to access the "foo::report" proc from any namespace
|
can be used to access the "foo::report" proc from any namespace
|
context, even though it is private.
|
context, even though it is private.
|
|
|
.SH KEYWORDS
|
.SH KEYWORDS
|
scope, callback, namespace, public, protected, private
|
scope, callback, namespace, public, protected, private
|
|
|
