1------------------------------------------------------------------------
2 [incr Tcl] - version 3.3.1 for Tcl/Tk 8.0.3 and beyond
3------------------------------------------------------------------------
4 This is a bug-fix release in the itcl3.x series.
5
6 As much as possible, I've tried to make itcl3.x backward-compatible
7 with earlier releases. The class definition syntax has not changed
8 at all from itcl2.2, and the old itcl1.x syntax is still supported.
9 But you'll notice changes related to the new namespace mechanism in
10 Tcl 8.0. For information on incompatibilities and porting to itcl3.x,
11 read the INCOMPATIBLE file in this directory, or check out the itcl
12 web site:
13
14 http://incrtcl.sourceforge.net/
15 http://www.tcltk.com/itcl/
16
17 Many people through the years have helped me with [incr Tcl]
18 development, and I thank them for their contributions. Please
19 read the acknowledgements section below.
20
21 Send comments or suggestions to the [incr Tcl] mailing list
22 (itcl@scriptics.com) or directly to me (mmc@cadence.com).
23 If you want to subscribe to the mailing list, send a message
24 with the subject "subscribe" to "itcl-request@tcltk.com".
25
26========================================================================
27 Copyright (c) 1993-1998 Lucent Technologies, Inc.
28 Copyright (c) 1998-2000 Cadence Design Systems, Inc.
29========================================================================
30
31 OVERVIEW
32------------------------------------------------------------------------
33 - What is [incr Tcl]?
34 - Getting started
35 - Installation
36 - Integrating [incr Tcl] with other extensions
37 - Acknowledgements
38------------------------------------------------------------------------
39
40
41 What is [incr Tcl]?
42------------------------------------------------------------------------
43 [incr Tcl] is an object-oriented extension of the Tcl language. It
44 was created to support more structured programming in Tcl. Tcl scripts
45 that grow beyond a few thousand lines become extremely difficult to
46 maintain. This is because the building blocks of vanilla Tcl are
47 procedures and global variables, and all of these building blocks
48 must reside in a single global namespace. There is no support for
49 protection or encapsulation.
50
51 [incr Tcl] introduces the notion of objects. Each object is a bag
52 of data with a set of procedures or "methods" that are used to
53 manipulate it. Objects are organized into "classes" with identical
54 characteristics, and classes can inherit functionality from one
55 another. This object-oriented paradigm adds another level of
56 organization on top of the basic variable/procedure elements, and
57 the resulting code is easier to understand and maintain.
58
59 Among other things, [incr Tcl] can be used to create new widgets that
60 look and work like the usual Tk widgets, but are written entirely at
61 the Tcl language level (C code is optional). These "mega-widgets"
62 can be created using [incr Tk], a set of base classes which provide
63 the core mega-widget functionality. [incr Widgets] is a set of
64 high-level mega-widgets built using [incr Tk]. It has more than
65 50 widget classes, and can be used right out of the box to create:
66
67 - fileselectiondialog
68 - tabnotebook
69 - panedwindow
70 - scrolledhtml
71 - combobox
72 - optionmenu
73 - scrolledlistbox
74 - scrolledframe
75 - messagedialog
76 - and many others...
77
78 Classes and/or related procedures can also be encapsulated in their
79 own "namespace". A namespace is a collection of commands, variables,
80 classes and other namespaces that is set apart from the usual global
81 scope. Elements within a namespace can be "private" or "protected",
82 so that access to them is restricted. An "import" command allows all
83 of the elements from one namespace to be integrated into another.
84
85 Extension writers will immediately see the benefit of namespaces.
86 With vanilla Tcl, each extension must add its commands and variables
87 at the global scope. Extension writers are encouraged to add a unique
88 prefix to all of the names in their package, to avoid naming collisions.
89 Extensions can now sit in their own namespace of commands and variables,
90 and sensitive elements can be protected from accidental access. For
91 example, the current release of [incr Tcl] has a namespace "itcl"
92 for object-oriented support, a namespace "itk" for mega-widget
93 support, and a namespace "iwidgets" for the [incr Widgets] package.
94 Each of these namespaces has its own collection of commands and
95 variables. Developers can then pick and choose among the extensions,
96 and integrate the parts that they need for their application by
97 importing various namespaces at the global scope.
98
99
100 Getting started
101------------------------------------------------------------------------
102 If you're just getting started with [incr Tcl], check out these
103 useful resources:
104
105 - FREE TUTORIAL on our web site: http://www.tcltk.com/itcl/
106
107 - BOOK: "[incr Tcl/Tk] from the Ground Up," by Chad Smith
108 (ISBN 0-07-212106-8)
109
110 - BOOK: "Tcl/Tk Tools," edited by Mark Harrison
111 (ISBN 1-56592-218-2)
112
113 Also, run the "catalog" demo to get an overview of the [incr Widgets]
114 package. On Windows and Macintosh systems, this is installed as one
115 of the executables. On Unix systems, this is installed in the
116 "lib/itcl/iwidgets3.0.0/demos" library directory.
117
118 The file "iwidgets3.0.0/doc/iwidgets.ps" contains a tutorial
119 introduction to the [incr Widgets] package. The mega-widget classes
120 in [incr Widgets] show off most of the functionality in this release.
121 You can use them as a pattern to create your own widget classes.
122
123 If you're a seasoned itcl professional, check the CHANGES file for a
124 summary of recent enhancements. Consult the man pages for detailed
125 information on particular commands.
126
127 Check out our web site for the latest news:
128
129 http://incrtcl.sourceforge.net/
130
131 Installation on Unix Systems
132------------------------------------------------------------------------
133 1) Obtain this distribution from an archive site like this:
134
135 http://incrtcl.sourceforge.net/
136 http://sourceforge.net/project/showfiles.php?group_id=13244
137
138 2) Uncompress and untar the distribution:
139
140 gunzip itcl<version>.tar.gz
141 tar xvf itcl<version>.tar
142
143 3) Run the configuration script:
144
145 cd itcl<version>
146 ./configure
147
148 or, for systems that don't recognize "#!" in shell scripts:
149
150 cd itcl<version>
151 /bin/sh ./configure
152
153 The "configure" script finds the appropriate compiler flags and
154 generates new Makefiles from template files (Makefile.in).
155
156 By default, the configuration script will set things up so
157 that everything is installed in "/usr/local". You can change
158 this by specifying a different "prefix" in the "configure" command:
159
160 ./configure --prefix=/your/install/path
161
162 If your Tcl installation is sitting somewhere other than right
163 next to this package, you may have to tell configure where to
164 find it:
165
166 ./configure --with-tcl=/usr/local/tcl/lib
167
168 If you want to debug, you can add this option as well:
169
170 ./configure --enable-symbols
171
172 4) Build the libraries and the executables. From the toplevel
173 directory type:
174
175 make all
176
177 5) Install the libraries, executables, man pages and script files.
178 From the toplevel directory type:
179
180 make install
181
182 6) Use the final product:
183
184 $ tclsh
185 % package require Itcl
186 % itcl::class Foo { method testing {} { return "testing!" } }
187
188 If you don't like the itcl:: prefix, you can import the itcl
189 commands into the global namespace:
190
191 % namespace import -force itcl::*
192 % class Foo { ... }
193
194 Note that you'll find the same behavior with [incr Widgets]:
195
196 $ wish
197 % package require Iwidgets
198 % iwidgets::optionmenu .om
199 % namespace import -force iwidgets::*
200 % optionmenu .om
201
202
203 Installation on Windows
204------------------------------------------------------------------------
205 Follow the usual TEA instructions for building under Windows.
206 Requires Cygwin and Visual C++ 6.0.
207
208
209 Installation on Macintosh Systems
210------------------------------------------------------------------------
211 Many thanks to Jim Ingham for putting up Macintosh binaries for
212 various releases. Check out http://www.tcltk.com/itcl for downloads.
213
214
215 Integrating [incr Tcl] with other extensions
216------------------------------------------------------------------------
217 [incr Tcl] is now a pure extension to Tcl/Tk. Therefore, if you
218 build the Tcl/Tk core and this package with the "--enable-shared"
219 option, you can load [incr Tcl] into a vanilla tclsh, as follows:
220
221 package require Itcl
222
223 Similarly, you can load [incr Tcl] along with the [incr Tk] mega-widget
224 facility into a vanilla wish, as follows:
225
226 package require Itk
227
228 You can load [incr Tcl], [incr Tk], and the [incr Widgets] package
229 like this:
230
231 package require Iwidgets
232
233 If you require the earlier release of [incr Widgets] for some reason,
234 you can specify the version number:
235
236 package require Iwidgets 2.2
237
238 Other packages should plug-and-play in the same fashion.
239
240 >> NOTE: If you have any trouble with dynamic loading on UNIX
241 >> systems, you may need to set your LD_LIBRARY_PATH environment
242 >> variable to include the "lib" directory for your Tcl/Tk
243 >> installation. For example:
244 >>
245 >> LD_LIBRARY_PATH="/usr/local/tcl/lib:$LD_LIBRARY_PATH"
246 >> export LD_LIBRARY_PATH
247
248
249 Acknowledgements
250------------------------------------------------------------------------
251 Thanks to Chad Smith for writing an excellent, comprehensive
252 book "[incr Tcl/Tk] from the Ground Up," for many helpful bug
253 reports, and for nudging me along to fix things.
254
255 Thanks to Matt Newman for providing the Tcl-only "tcl++" package
256 that helped so many people move forward while waiting for the
257 itcl3.0 release.
258
259 Thanks to John Ousterhout and the Scriptics team for bundling this
260 package with their TclPro product. It's gratifying to see [incr Tcl]
261 accepted as a mainstream product.
262
263 Thanks to Mark Ulferts, Sue Yockey, John Sigler, Bill Scott, Alfredo
264 Jahn, Bret Schuhmacher, Tako Schotanus and Kris Raney for building
265 the [incr Widgets] package. With a sketchy overview and a crappy
266 prototype of [incr Tk], they managed to build a nice set of mega-widgets.
267 Their initial designs helped me smooth out the rough spots in [incr Tk].
268 Thanks especially to Mark Ulferts for keeping things up over the past
269 few years, and for streamlining the package for itcl3.0.
270
271 Thanks to Jan Nijtmans, Karel Zuiderveld, and Vince Darley for helping
272 to keep up with Tcl/Tk releases, and for supporting the "plus" and
273 "dash" patches under [incr Tcl].
274
275 Thanks to Forest Rouse and ICEM CFD Engineering for integrating
276 [incr Tcl] into their Tcl/Tk compiler. This is a large undertaking,
277 and they have done an excellent job.
278
279 Thanks to Alfredo Jahn and Bret Schuhmacher at WebNet for helping
280 to create the [incr Tcl] web site, and for maintaining the
281 [incr Tcl] mailing list for many years.
282
283 Thanks to extension writers like Mark Diekhans (tclX) and Ioi Lam (Tix)
284 for making their packages compatible with [incr Tcl].
285
286 Thanks to George Howlett for teaching me how namespaces should really
287 work. He has been a constant source of inspiration, and has kept
288 a careful watch against many bad ideas. Jim Ingham fleshed out the
289 notion of explicit scoping, added many nice features to [incr Tk],
290 and has helped tremendously with porting. Lee Bernhard worked on
291 distributed systems with Iclient/Iserver, and also helped with porting.
292 Bill Scott, with a steady stream of bug reports, helped me understand
293 the questions that a typical user might have. He forced me to reinvent
294 the paradigm on more than one occasion.
295
296 Thanks to all of the alpha-testers that helped me polish this release.
297
298 Thanks to Mark Harrison for his enthusiasm and support. Due in
299 large part to his evangelism, I have been able to make [incr Tcl]
300 development a mainstream activity.
301
302 And many thanks to my wife Maria and my children Maxwell and Katie
303 for putting up with all of this.
304
305--Michael
306. . . . . . . . . . . . . . . . . ---_-----------
307 . . . . . . . . . | c a d e n c e |
308 Michael McLennan . ---------------
309 mmc@cadence.com . Cadence Design Systems, Inc.
310 phone: 610-398-6348 . 7535 Windsor Dr. Suite A-200
311 fax: 610-530-7985 . Allentown, PA 18195
312