1 |
578 |
markom |
'\"
|
2 |
|
|
'\" Copyright (c) 1993-1998 Lucent Technologies, Inc.
|
3 |
|
|
'\"
|
4 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
5 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
6 |
|
|
'\"
|
7 |
|
|
'\" RCS: $Id: code.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $
|
8 |
|
|
'\"
|
9 |
|
|
.so man.macros
|
10 |
|
|
.TH code n 3.0 itcl "[incr\ Tcl]"
|
11 |
|
|
.BS
|
12 |
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
13 |
|
|
.SH NAME
|
14 |
|
|
code \- capture the namespace context for a code fragment
|
15 |
|
|
.SH SYNOPSIS
|
16 |
|
|
\fBcode \fR?\fB-namespace \fIname\fR? \fIcommand \fR?\fIarg arg ...\fR?
|
17 |
|
|
.BE
|
18 |
|
|
|
19 |
|
|
.SH DESCRIPTION
|
20 |
|
|
.PP
|
21 |
|
|
Creates a scoped value for the specified \fIcommand\fR and its
|
22 |
|
|
associated \fIarg\fR arguments. A scoped value is a list with three
|
23 |
|
|
elements: the "\fC@scope\fR" keyword, a namespace context,
|
24 |
|
|
and a value string. For example, the command
|
25 |
|
|
.CS
|
26 |
|
|
namespace foo {
|
27 |
|
|
code puts "Hello World!"
|
28 |
|
|
}
|
29 |
|
|
.CE
|
30 |
|
|
produces the scoped value:
|
31 |
|
|
.CS
|
32 |
|
|
@scope ::foo {puts {Hello World!}}
|
33 |
|
|
.CE
|
34 |
|
|
Note that the \fBcode\fR command captures the current namespace
|
35 |
|
|
context. If the \fB-namespace\fR flag is specified, then the
|
36 |
|
|
current context is ignored, and the \fIname\fR string is used
|
37 |
|
|
as the namespace context.
|
38 |
|
|
.PP
|
39 |
|
|
Extensions like Tk execute ordinary code fragments in the global
|
40 |
|
|
namespace. A scoped value captures a code fragment together with
|
41 |
|
|
its namespace context in a way that allows it to be executed
|
42 |
|
|
properly later. It is needed, for example, to wrap up code fragments
|
43 |
|
|
when a Tk widget is used within a namespace:
|
44 |
|
|
.CS
|
45 |
|
|
namespace foo {
|
46 |
|
|
private proc report {mesg} {
|
47 |
|
|
puts "click: $mesg"
|
48 |
|
|
}
|
49 |
|
|
|
50 |
|
|
button .b1 -text "Push Me" \
|
51 |
|
|
-command [code report "Hello World!"]
|
52 |
|
|
pack .b1
|
53 |
|
|
}
|
54 |
|
|
.CE
|
55 |
|
|
The code fragment associated with button \fC.b1\fR only makes
|
56 |
|
|
sense in the context of namespace "foo". Furthermore, the
|
57 |
|
|
"report" procedure is private, and can only be accessed within
|
58 |
|
|
that namespace. The \fBcode\fR command wraps up the code
|
59 |
|
|
fragment in a way that allows it to be executed properly
|
60 |
|
|
when the button is pressed.
|
61 |
|
|
.PP
|
62 |
|
|
Also, note that the \fBcode\fR command preserves the integrity
|
63 |
|
|
of arguments on the command line. This makes it a natural replacement
|
64 |
|
|
for the \fBlist\fR command, which is often used to format Tcl code
|
65 |
|
|
fragments. In other words, instead of using the \fBlist\fR command
|
66 |
|
|
like this:
|
67 |
|
|
.CS
|
68 |
|
|
after 1000 [list puts "Hello $name!"]
|
69 |
|
|
.CE
|
70 |
|
|
use the \fBcode\fR command like this:
|
71 |
|
|
.CS
|
72 |
|
|
after 1000 [code puts "Hello $name!"]
|
73 |
|
|
.CE
|
74 |
|
|
This not only formats the command correctly, but also captures
|
75 |
|
|
its namespace context.
|
76 |
|
|
.PP
|
77 |
|
|
Scoped commands can be invoked like ordinary code fragments, with
|
78 |
|
|
or without the \fBeval\fR command. For example, the following
|
79 |
|
|
statements work properly:
|
80 |
|
|
.CS
|
81 |
|
|
set cmd {@scope ::foo .b1}
|
82 |
|
|
$cmd configure -background red
|
83 |
|
|
|
84 |
|
|
set opts {-bg blue -fg white}
|
85 |
|
|
eval $cmd configure $opts
|
86 |
|
|
.CE
|
87 |
|
|
Note that scoped commands by-pass the usual protection mechanisms;
|
88 |
|
|
the command:
|
89 |
|
|
.CS
|
90 |
|
|
@scope ::foo {report {Hello World!}}
|
91 |
|
|
.CE
|
92 |
|
|
can be used to access the "foo::report" proc from any namespace
|
93 |
|
|
context, even though it is private.
|
94 |
|
|
|
95 |
|
|
.SH KEYWORDS
|
96 |
|
|
scope, callback, namespace, public, protected, private
|