Tcl and the Tk Toolkit

Preface
Preface to the First Edition
Introduction
PART I The Tcl Language
Chapter 1 An Overview of Tcl and Tk
1.1 Getting Started
1.2 “Hello, World!” with Tk
1.3 Script Files
1.3.1 Executable Scripts on Unix and Mac OS X
1.3.2 Executable Scripts on Windows
1.3.3 Executing Scripts in an Interactive Interpreter
1.4 Variables and Substitutions
1.5 Control Structures
1.6 On the Tcl Language
1.7 Event Bindings
1.8 Additional Features of Tcl and Tk
Chapter 2 Tcl Language Syntax
2.1 Scripts, Commands, and Words
2.2 Evaluating a Command
2.3 Variable Substitution
2.4 Command Substitution
2.5 Backslash Substitution
2.6 Quoting with Double Quotes
2.7 Quoting with Braces
2.8 Argument Expansion
2.9 Comments
2.10 Normal and Exceptional Returns
2.11 More on Substitutions
Chapter 3 Variables
3.1 Commands Presented in This Chapter
3.2 Simple Variables and the set Command
3.3 Tcl’s Internal Storage of Data
3.4 Arrays
3.5 Variable Substitution
3.6 Multidimensional Arrays
3.7 Querying the Elements of an Array
3.8 The incr and append Commands
3.9 Removing Variables: unset and array unset
3.10 Predefined Variables
3.11 Preview of Other Variable Facilities
Chapter 4 Expressions
4.1 Commands Presented in This Chapter
4.2 Numeric Operands
4.3 Operators and Precedence
4.3.1 Arithmetic Operators
4.3.2 Relational Operators
4.3.3 Logical Operators
4.3.4 Bit-wise Operators
4.3.5 Choice Operator
4.4 Math Functions
4.5 Substitutions
4.6 String Manipulation
4.7 List Manipulation
4.8 Types and Conversions
4.9 Precision
Chapter 5 String Manipulation
5.1 Commands Presented in This Chapter
5.2 Extracting Characters: string index and string range
5.3 Length, Case Conversion, Trimming, and Repeating
5.4 Simple Searching
5.5 String Comparisons
5.6 String Replacements
5.7 Determining String Types
5.8 Generating Strings with format
5.9 Parsing Strings with scan
5.10 Glob-Style Pattern Matching
5.11 Pattern Matching with Regular Expressions
5.11.1 Regular Expression Atoms
5.11.2 Regular Expression Branches and Quantifiers
5.11.3 Back References
5.11.4 Non-capturing Subexpressions
5.11.5 The regexp Command
5.12 Using Regular Expressions for Substitutions
5.13 Character Set Issues
5.13.1 Character Encodings and the Operating System
5.13.2 Encodings and Channel Input/output
5.13.3 Converting Strings to Different Encodings
5.14 Message Catalogs
5.14.1 Using Message Catalogs
5.14.2 Creating Localized Message Files
5.14.3 Using Conversion Specifiers in Source and
Translation Strings
5.14.4 Using Message Catalogs with Namespaces
5.15 Binary Strings
Chapter 6 Lists
6.1 Commands Presented in This Chapter
6.2 Basic List Structure and the lindex and llength Commands
6.3 Creating Lists: list , concat , and lrepeat
6.4 Modifying Lists: lrange , linsert , lreplace , lset , and lappend
6.5 Extracting List Elements: lassign
6.6 Searching Lists: lsearch
6.7 Sorting Lists: lsort
6.8 Converting between Strings and Lists: split and join
6.9 Creating Commands as Lists
Chapter 7 Dictionaries
7.1 Commands Presented in This Chapter
7.2 Basic Dictionary Structure and the dict get Command
7.3 Creating and Updating Dictionaries
7.4 Examining Dictionaries: The size , exists , keys , and for
Subcommands
7.5 Updating Dictionary Values
7.6 Working with Nested Dictionaries
Chapter 8 Control Flow
8.1 Commands Presented in This Chapter
8.2 The if Command
8.3 The switch Command
8.4 Looping Commands: while , for , and foreach
8.5 Loop Control: break and continue
8.6 The eval Command
8.7 Executing from Files: source
Chapter 9 Procedures
9.1 Commands Presented in This Chapter
9.2 Procedure Basics: proc and return
9.3 Local and Global Variables
9.4 Defaults and Variable Numbers of Arguments
9.5 Call by Reference: upvar
9.6 Creating New Control Structures: uplevel
9.7 Applying Anonymous Procedures
Chapter 10 Namespaces
10.1 Commands Presented in This Chapter
10.2 Evaluating Tcl Code in a Namespace
10.3 Manipulating Qualified Names
10.4 Exporting and Importing Namespace Commands
10.5 Inspecting Namespaces
10.6 Working with Ensemble Commands
10.6.1 Basic Ensembles
10.6.2 Placing Ensembles Inside Ensembles
10.6.3 Controlling the Ensemble Configuration
10.6.4 Handling Unknown Ensemble Subcommands
10.7 Accessing Variables from Other Namespaces
10.8 Controlling the Name Resolution Path
Chapter 11 Accessing Files
11.1 Commands Presented in This Chapter
11.2 Manipulating File and Directory Names
11.3 The Current Working Directory
11.4 Listing Directory Contents
11.5 Working with Files on Disk
11.5.1 Creating Directories
11.5.2 Deleting Files
11.5.3 Copying Files
11.5.4 Renaming and Moving Files
11.5.5 File Information Commands
11.5.6 Dealing with Oddly Named Files
11.6 Reading and Writing Files
11.6.1 Basic File I/O
11.6.2 Output Buffering
11.6.3 Handling Platform End-of-Line Conventions
11.6.4 Handling Character Set Encoding
11.6.5 Working with Binary Files
11.6.6 Random Access to Files
11.6.7 Copying File Content
11.7 Virtual File Systems
11.8 Errors in System Calls
Chapter 12 Processes and Interprocess Communication
12.1 Commands Presented in This Chapter
12.2 Terminating the Tcl Process with exit
12.3 Invoking Subprocesses with exec
12.4 I/O to and from a Command Pipeline
12.5 Configuring Channel Options
12.5.1 Channel Blocking Mode
12.5.2 Channel Buffering Mode
12.6 Event-Driven Channel Interaction
12.6.1 Entering the Tcl Event Loop with vwait
12.6.2 Registering File Event Handlers
12.7 Process IDs
12.8 Environment Variables
12.9 TCP/IP Socket Communication
12.9.1 Creating Client Communication Sockets
12.9.2 Creating Server Sockets
12.10 Sending Commands to Tcl Programs
12.10.1 Basics of send
12.10.2 Application Names
12.10.3 Security Issues with send
Chapter 13 Errors and Exceptions
13.1 Commands Presented in This Chapter
13.2 What Happens after an Error?
13.3 Generating Errors from Tcl Scripts
13.4 Trapping Errors with catch
13.5 Exceptions in General
13.6 Background Errors and bgerror
Chapter 14 Creating and Using Tcl Script Libraries
14.1 Commands Presented in This Chapter
14.2 The load Command
14.3 Using Libraries
14.4 Autoloading
14.5 Packages
14.5.1 Using Packages
14.5.2 Creating Packages
14.5.3 Using ::pkg::create
14.5.4 Installing Packages
14.5.5 Utility Package Commands
14.6 Tcl Modules
14.6.1 Using Tcl Modules
14.6.2 Installing Tcl Modules
14.7 Packaging Your Scripts as Starkits
14.7.1 Installing a Tclkit
14.7.2 Creating Starkits
14.7.3 Creating a Platform-Specific Executable
Chapter 15 Managing Tcl Internals
15.1 Commands Presented in This Chapter
15.2 Time Delays
15.3 Time and Date Manipulation
15.3.1 Generating Human-Readable Time and Date Strings
15.3.2 Scanning Human-Readable Time and Date Strings
15.3.3 Performing Clock Arithmetic
15.4 Timing Command Execution
15.5 The info Command
15.5.1 Information about Variables
15.5.2 Information about Procedures
15.5.3 Information about Commands
15.5.4 The Tcl Interpreter Version and Other Runtime
Environment Information
15.6 Tracing Operations on Simple Variables
15.7 Tracing Array Variables
15.8 Renaming and Deleting Commands
15.9 Tracing Commands
15.10 Unknown Commands
15.11 Slave Interpreters
15.11.1 Command Aliases
15.11.2 Safe Slave Interpreters and Hidden Commands
15.11.3 Transferring Channels between Interpreters
15.11.4 Placing Limits on an Interpreter
Chapter 16 History
16.1 Commands Presented in This Chapter
16.2 The History List
16.3 Specifying Events
16.4 Re-executing Commands from the History List
16.5 Shortcuts Implemented by unknown
16.6 Current Event Number: history nextid
PART II Writing Scripts for Tk
Chapter 17 An Introduction to Tk
17.1 A Brief Introduction to Windowing Systems
17.2 Widgets
17.3 Applications, Toplevel Widgets, and Screens
17.4 Scripts and Events
17.5 Creating and Destroying Widgets
17.6 Geometry Managers
17.7 Widget Commands
17.8 Commands for Interconnection
Chapter 18 A Tour of the Tk Widgets
18.1 Widget Basics
18.2 Frames
18.2.1 Relief Options
18.2.2 Screen Distance Options
18.3 Color Options
18.3.1 Synonyms
18.4 Toplevels
18.5 Labels
18.5.1 Text Options
18.5.2 Font Options
18.5.3 Image Options
18.5.4 Compound Options
18.6 Labelframes
18.7 Buttons
18.7.1 Checkbuttons
18.7.2 Radiobuttons
18.7.3 Menubuttons
18.8 Listboxes
18.9 Scrollbars
18.9.1 Scrolling a Single Widget
18.9.2 Synchronized Scrolling of Multiple Widgets
18.10 Scales
18.11 Entries
18.11.1 Entry Widget
18.11.2 Spinbox
18.11.3 The show Option
18.11.4 Validation
18.12 Menus
18.12.1 Pull-Down Menus
18.12.2 Cascaded Menus
18.12.3 Keyboard Traversal and Shortcuts
18.12.4 Platform-Specific Menus
18.12.5 Pop-up Menus
18.13 Panedwindow
18.14 Standard Dialogs
18.15 Other Common Options
18.15.1 Widget State
18.15.2 Widget Size Options
18.15.3 Anchor Options
18.15.4 Internal Padding
18.15.5 Cursor Options
Chapter 19 Themed Widgets
19.1 Comparing Classic and Themed Widgets
19.2 Combobox
19.3 Notebook
19.4 Progressbar
19.5 Separator
19.6 Sizegrip
19.7 Treeview
19.7.1 Manipulating Treeview Items
19.7.2 Managing Treeview Columns and Headings
19.7.3 Treeview Item Selection Management
19.7.4 Treeview Item Tags
19.8 Themed Widget States
19.9 Themed Widget Styles
19.9.1 Using Themes
19.9.2 The Elements of Style
19.9.3 Creating and Configuring Styles
19.10 Other Standard Themed Widget Options
Chapter 20 Fonts, Bitmaps, and Images
20.1 Commands Presented in This Chapter
20.2 The font Command
20.2.1 Manipulating and Using Named Fonts
20.2.2 Other Font Utilities
20.2.3 Font Descriptions
20.3 The image Command
20.3.1 Bitmap Images
20.3.2 Photo Images
20.3.3 Images and Namespaces
Chapter 21 Geometry Managers
21.1 Commands Presented in This Chapter
21.2 An Overview of Geometry Management
21.3 The Gridder
21.3.1 The grid Command and the -sticky Options
21.3.2 Spanning Rows and Columns
21.3.3 Stretch Behavior and the -weight and -uniform Options
21.3.4 Relative Placement Characters
21.4 The Packer
21.4.1 The pack Command and -side Options
21.4.2 Filling
21.4.3 Expansion
21.4.4 Anchors
21.4.5 Packing Order
21.5 Padding
21.6 The Placer
21.7 Hierarchical Geometry Management
21.8 Widget Stacking Order
21.9 Other Geometry Manager Options
21.10 Other Geometry Managers in Tk
Chapter 22 Events and Bindings
22.1 Commands Presented in This Chapter
22.2 Events
22.3 An Overview of the bind Command
22.4 Event Patterns
22.5 Sequences of Events
22.6 Substitutions in Scripts
22.7 Conflict Resolution
22.8 Event-Binding Hierarchy
22.9 When Are Events Processed?
22.10 Named Virtual Events
22.11 Generating Events
22.12 Logical Actions
22.13 Other Uses of Bindings
Chapter 23 The Canvas Widget
23.1 Canvas Basics: Items and Types
23.2 Manipulating Items with Identifiers and Tags
23.3 Bindings
23.4 Canvas Scrolling
23.5 PostScript Generation
Chapter 24 The Text Widget
24.1 Text Widget Basics
24.2 Text Indices and Marks
24.3 Search and Replace
24.4 Text Tags
24.4.1 Tag Options
24.4.2 Tag Priorities
24.4.3 Tag Bindings
24.5 Virtual Events
24.6 Embedded Windows
24.7 Embedded Images
24.8 Undo
24.9 Peer Text Widgets
Chapter 25 Selection and the Clipboard
25.1 Commands Presented in This Chapter
25.2 Selections, Retrievals, and Types
25.3 Locating and Clearing the Selection
25.4 Supplying the Selection with Tcl Scripts
25.5 The clipboard Command
25.6 Drag and Drop
Chapter 26 Window Managers
26.1 Commands Presented in This Chapter
26.2 Window Sizes
26.3 Window Positions
26.4 Gridded Windows
26.5 Window States
26.6 Decorations
26.7 Special Handling: Transients, Groups, and Override-Redirect
26.8 System-Specific Window Attributes
26.9 Dockable Windows
26.10 Window Close
26.11 Session Management
Chapter 27 Focus, Modal Interaction, and Custom Dialogs
27.1 Commands Presented in This Chapter
27.2 Input Focus
27.2.1 Focus Model: Explicit versus Implicit
27.2.2 Setting the Input Focus
27.2.3 Querying the Input Focus
27.3 Modal Interactions
27.3.1 Grabs
27.3.2 Local versus Global Grabs
27.3.3 Keyboard Handling during Grabs
27.3.4 Waiting: The tkwait Command
27.4 Custom Dialogs
Chapter 28 More on Configuration Options
28.1 Commands Presented in This Chapter
28.2 The Option Database
28.3 Option Database Entries
28.4 The RESOURCE_MANAGER Property and .Xdefaults File
28.5 Priorities in the Option Database
28.6 The option Command
28.7 The configure Widget Command
28.8 The cget Widget Command
Chapter 29 Odds and Ends
29.1 Commands Presented in This Chapter
29.2 Destroying Widgets
29.3 The update Command
29.4 Information about Widgets
29.5 The tk Command
29.6 Variables Managed by Tk
29.7 Ringing the Bell
PART III Writing Tcl Applications in C
Chapter 30 Tcl and C Integration Philosophy
30.1 Tcl versus C: Where to Draw the Line
30.2 Resource Names—Connecting C Constructs to Tcl
30.3 “Action-Oriented” versus “Object-Oriented”
30.4 Representing Information
Chapter 31 Interpreters
31.1 Functions Presented in This Chapter
31.2 Interpreters
31.3 A Simple Tcl Application
31.4 Deleting Interpreters
31.5 Multiple Interpreters
Chapter 32 Tcl Objects
32.1 Functions Presented in This Chapter
32.2 String Objects
32.3 Numerical Objects
32.4 Fetching C Values from Objects
32.5 The Dynamic Nature of a Tcl Object
32.6 Byte Arrays
32.7 Composite Objects
32.8 Reference Counting
32.9 Shared Objects
32.10 New Object Types
32.11 Parsing Strings
32.12 Memory Allocation
Chapter 33 Evaluating Tcl Code
33.1 Functions Presented in This Chapter
33.2 Evaluating Tcl Code
33.3 Dynamically Building Scripts
33.4 Tcl Expressions
Chapter 34 Accessing Tcl Variables
34.1 Functions Presented in This Chapter
34.2 Setting Variable Values
34.3 Reading Variables
34.4 Unsetting Variables
34.5 Linking Tcl and C Variables
34.6 Setting and Unsetting Variable Traces
34.7 Trace Callbacks
34.8 Whole-Array Traces
34.9 Multiple Traces
34.10 Unset Callbacks
Chapter 35 Creating New Tcl Commands
35.1 Functions Presented in This Chapter
35.2 Command Functions
35.3 Registering Commands
35.4 The Result Protocol
35.5 Tcl_AppendResult
35.6 Tcl_SetResult and interp->result
35.7 clientData and Deletion Callbacks
35.8 Deleting Commands
35.9 Fetching and Setting Command Parameters
35.10 How Tcl Procedures Work
35.11 Command Traces
Chapter 36 Extensions
36.1 Functions Presented in This Chapter
36.2 The Init Function
36.3 Packages
36.4 Namespaces
36.5 Tcl Stubs
36.6 The ifconfig Extension
Chapter 37 Embedding Tcl
37.1 Functions Presented in This Chapter
37.2 Adding Tcl to an Application
37.3 Initialize Tcl
37.4 Creating New Tcl Shells
Chapter 38 Exceptions
38.1 Functions Presented in This Chapter
38.2 Completion Codes
38.3 Setting errorCode
38.4 Managing the Return Options Dictionary
38.5 Adding to the Stack Trace in errorInfo
38.6 Tcl_Panic
Chapter 39 String Utilities
39.1 Functions Presented in This Chapter
39.2 Dynamic Strings
39.3 String Matching
39.4 Regular Expression Matching
39.5 Working with Character Encodings
39.6 Handling Unicode and UTF-8 Strings
39.7 Command Completeness
Chapter 40 Hash Tables
40.1 Functions Presented in This Chapter
40.2 Keys and Values
40.3 Creating and Deleting Hash Tables
40.4 Creating Entries
40.5 Finding Existing Entries
40.6 Searching
40.7 Deleting Entries
40.8 Statistics
Chapter 41 List and Dictionary Objects
41.1 Functions Presented in This Chapter
41.2 Lists
41.3 Dictionaries
Chapter 42 Channels
42.1 Functions Presented in This Chapter
42.1.1 Basic Channel Operations
42.1.2 Channel Registration Functions
42.1.3 Channel Attribute Functions
42.1.4 Channel Query Functions
42.1.5 Channel Type Definition Functions
42.2 Channel Operations
42.3 Registering Channels
42.4 Standard Channels
42.5 Creating a New Channel Type
42.5.1 Creating a Custom Channel Instance
42.5.2 Stacked Channels
42.5.3 ROT13 Channel
Chapter 43 Handling Events
43.1 Functions Presented in This Chapter
43.2 Channel Events
43.3 Timer Events
43.4 Idle Callbacks
43.5 Invoking the Event Dispatcher
Chapter 44 File System Interaction
44.1 Tcl File System Functions
44.2 Virtual File Systems
Chapter 45 Operating System Utilities
45.1 Functions Presented in This Chapter
45.2 Processes
45.3 Reaping Child Processes
45.4 Asynchronous Events
45.5 Signal Names
45.6 Exiting and Cleanup
45.7 Miscellaneous
Chapter 46 Threads
46.1 Functions Presented in This Chapter
46.2 Thread Safety
46.3 Building Threaded Tcl
46.4 Creating Threads
46.5 Terminating Threads
46.6 Mutexes
46.7 Condition Variables
46.8 Miscellaneous
Chapter 47 Building Tcl and Extensions
47.1 Building Tcl and Tk
47.1.1 Building Tcl and Tk on Unix
47.1.2 Building Tcl and Tk on Mac OS
47.1.3 Building Tcl and Tk on Windows
47.2 The Tcl Extension Architecture (TEA)
47.2.1 TEA Standard Configure Options
47.2.2 Directory Layout for TEA Extensions
47.2.3 Customizing the aclocal.m4 File
47.2.4 Customizing the configure.in File
47.2.5 Customizing the Makefile.in File
47.2.6 Building an Extension on Windows
47.3 Building Embedded Tcl
Appendixes
Appendix A Installing Tcl and Tk
A.1 Versions
A.2 Bundled Tcl Distributions
A.3 ActiveTcl
A.4 Tclkits
A.5 Compiling Tcl/Tk from Source Distributions
Appendix B Extensions and Applications
B.1 Obtaining and Installing Extensions
B.1.1 Installing Extensions Manually
B.1.2 Installing Extensions from ActiveState TEApot Repositories
B.2 TkCon Extended Console
B.3 The Standard Tcl Library, Tcllib
B.4 Additional Image Formats with Img
B.5 Sound Support with Snack
B.6 Object-Oriented Tcl
B.7 Multithreaded Tcl Scripting
B.8 XML Programming
B.9 Database Programming
B.10 Integrating Tcl and Java
B.11 SWIG
B.12 Expect
B.13 Extended Tcl
Appendix C Tcl Resources
C.1 Online Resources
C.2 Books
Appendix D Tcl Source Distribution License