mjVjJWRm

1Tcl/Tk Reference Guide
2for Tcl 8.4.3 / Tk 8.4.3
3
4Tk/Tcl program designed and created by
5John Ousterhout
6
7Reference guide contents written by
8Paul Raines <raines@slac.stanford.edu>
9Jeff Tranter <tranter@pobox.com>
10Dave Bodenstab <dave@bodenstab.org>
11Reference guide format designed and created by
12Johan Vromans <jvromans@squirrel.nl>
13Tcl/Tk Reference Guide
14Contents
151. Tcl Shell . . . . . . . . . . . . . . . . . . . . . . . . . 5
162. Basic Tcl Language Features . . . . . . . . . . . . . . . 5
173. Tcl Special Variables . . . . . . . . . . . . . . . . . . . 6
184. Operators and Expressions . . . . . . . . . . . . . . . . 7
195. Regular Expressions . . . . . . . . . . . . . . . . . . . 7
206. Pattern Globbing . . . . . . . . . . . . . . . . . . . . . 8
217. Control Statements . . . . . . . . . . . . . . . . . . . . 9
228. File Information . . . . . . . . . . . . . . . . . . . . . 9
239. Tcl Interpreter Information . . . . . . . . . . . . . . . . 11
2410. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2511. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2612. Strings and Binary Data . . . . . . . . . . . . . . . . . 15
2713. System Interaction . . . . . . . . . . . . . . . . . . . . 19
2814. File Input/Output . . . . . . . . . . . . . . . . . . . . . 20
2915. Multiple Interpreters . . . . . . . . . . . . . . . . . . . 23
3016. Packages . . . . . . . . . . . . . . . . . . . . . . . . . 24
3117. Namespaces . . . . . . . . . . . . . . . . . . . . . . . 25
3218. Other Tcl Commands . . . . . . . . . . . . . . . . . . 26
3319. Tk Shell . . . . . . . . . . . . . . . . . . . . . . . . . 31
3420. Tk Special Variables . . . . . . . . . . . . . . . . . . . 31
3521. General Tk Widget Information . . . . . . . . . . . . . 31
3622. Widget Scroll Commands . . . . . . . . . . . . . . . . 34
3723. Entry Validation . . . . . . . . . . . . . . . . . . . . . 35
3824. The Canvas Widget . . . . . . . . . . . . . . . . . . . 36
3925. The Entry Widget . . . . . . . . . . . . . . . . . . . . 44
4026. The Listbox Widget . . . . . . . . . . . . . . . . . . . 46
4127. The Menu Widget . . . . . . . . . . . . . . . . . . . . 47
4228. The Text Widget . . . . . . . . . . . . . . . . . . . . . 49
4329. Other Standard Widgets . . . . . . . . . . . . . . . . . 53
4430. Images . . . . . . . . . . . . . . . . . . . . . . . . . . 63
4531. Window Information . . . . . . . . . . . . . . . . . . . 65
4632. The Window Manager . . . . . . . . . . . . . . . . . . 67
4733. Binding and Virtual Events . . . . . . . . . . . . . . . . 69
4834. Geometry Management . . . . . . . . . . . . . . . . . 71
4935. Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
5036. Other Tk Commands . . . . . . . . . . . . . . . . . . . 74
5137. TclX 8.4 . . . . . . . . . . . . . . . . . . . . . . . . . 79
5238. TclX Special Variables and Commands . . . . . . . . . 79
5339. TclX General Commands . . . . . . . . . . . . . . . . 79
5440. TclX Debugging Commands . . . . . . . . . . . . . . . 81
5541. TclX Development Commands . . . . . . . . . . . . . . 81
5642. TclX Unix Access Commands . . . . . . . . . . . . . . 82
5743. TclX File Commands . . . . . . . . . . . . . . . . . . 84
5844. TclX Network Programming Support . . . . . . . . . . 86
592
60Tcl/Tk Reference Guide
6145. TclX File Scanning Commands . . . . . . . . . . . . . 86
6246. TclX Math Commands . . . . . . . . . . . . . . . . . . 86
6347. TclX List Manipulation Commands . . . . . . . . . . . 87
6448. TclX Keyed Lists . . . . . . . . . . . . . . . . . . . . 88
6549. TclX String/Character Commands . . . . . . . . . . . . 88
6650. TclX XPG/3 Message Catalog Commands . . . . . . . . 89
6751. Img 1.2.4 Package . . . . . . . . . . . . . . . . . . . . 90
6852. Tcllib 1.4 . . . . . . . . . . . . . . . . . . . . . . . . . 91
6953. Tktable 2.8 Package . . . . . . . . . . . . . . . . . . . 98
7054. Vu 2.1.0 Package . . . . . . . . . . . . . . . . . . . . . 105
7155. Vim 6.2 if tcl Interface . . . . . . . . . . . . . . . . . 112
72Rev. 80.3.1.17
733
74Tcl/Tk Reference Guide
75Notes
764
77Tcl/Tk Reference Guide
78Conventions
79fixed denotes literal text.
80this means variable text, i.e. things you must fill in.
81word is a keyword, i.e. a word with a special meaning.
82[. . . ] denotes an optional part.
831. Tcl Shell
84tclsh [script [arg . . . ]]
85Tclsh reads Tcl commands from its standard input or from file script and evaluates
86them.
87Without arguments, tclsh runs interactively, sourcing the file .tclshrc (if it exists)
88before reading the standard input. With arguments, script is the name of a file to
89source and any additional arguments will become the value of the Tcl variable
90$argv.
912. Basic Tcl Language Features
92; or newline statement separator
93\ statement continuation if last character in line
94# comments out rest of line (if first non-whitespace character)
95var simple variable
96var(index) associative array variable
97var(i,j) multi-dimensional array variable
98$var variable substitution (also ${var}xyz)
99[expr 1+2] command substitution
100\char backslash substitution (see below)
101"hello $a" quoting with substitution
102{hello $a} quoting with no substitution (deferred substitution)
103The only data type in Tcl is a string. However, some commands will interpret
104arguments as numbers/boolean in which case the formats are
105Integer: 123 0xff(hex) 0377 (octal).
106Floating Point: 2.1 3. 6e4 7.91e+16
107Boolean: true false 0 1 yes no
108Tcl makes the following backslash substitutions:
109\a audible alert (0x7) \space space
110\b backspace (0x8) \newline space
111\f form feed (0xC) \ddd octal value (d=0–7)
112\n newline (0xA) \xdd hexadecimal value (d=0–9, a–f)
113\r carriage return (0xD) \udddd hexadecimal unicode value (d=0–9, a–f)
114\t horizontal tab (0x9) \c replace ‘\c’ with ‘c’
115\v vertical tab (0xB) \\ a backslash
1165
117Tcl/Tk Reference Guide
1183. Tcl Special Variables
119argc Number of command line arguments, not including the
120name of the script file.
121argv Tcl list (possibly empty) of command line arguments.
122argv0 Name of script or command interpreter.
123auto_noexec If set to any value, then unknown will not attempt to
124auto-exec any commands.
125auto_noload If set to any value, then unknown will not attempt to
126auto-load any commands.
127auto_path List of directories to search during auto-load operations.
128$env(TCLLIBPATH)overrides the default list.
129env Array where each element name is an enviroment variable.
130errorCode Error code information from the last Tcl error. A list
131containing class [code [msg]].
132errorInfo Describes the stack trace of the last Tcl error.
133tcl_library Directory containing library of standard Tcl scripts. Value is
134returned by [info library]. $env(TCL_LIBRARY)
135overrides the built-in value.
136tcl_libPath List of all possible locations for Tcl packages.
137tcl_interactive
138True if command interpreter is running interactively.
139tcl_patchLevel Integer specifying current patch level for Tcl.
140tcl_pkgPath List of directories to search for installed packages. Value is
141added to $auto_path.
142tcl_platform Array with elements byteOrder, debug (if compiled
143with debugging enabled), machine, os, osVersion,
144platform, threaded(if compiled with threads
145enabled), user, and wordSize.
146tcl_precision Number of significant digits to retain when converting
147floating-point numbers to strings (default 12).
148tcl_prompt1 A script which, when evaluated, outputs the main command
149prompt during interactive execution of tclsh or wish.
150tcl_prompt2 A script which, when evaluated, outputs the secondary
151command prompt during interactive execution of tclsh or
152wish.
153tcl_rcFileName Name of script to source upon start-up of an interactive
154tclsh or wish.
155tcl_traceCompile
156Level of tracing info output during bytecode compilation: 0
157for none, 1 for summary line, or 2 for byte code instructions.
158tcl_traceExec Level of tracing info output during bytecode execution: 0
159for none, 1 for summary line, 2 and 3 for detailed trace.
160tcl_wordchars If set, a regular expression that controls what are considered
161to be “word” characters.
162tcl_nonwordchars
163If set, a regular expression that controls what are considered
164to be “non-word” characters.
165tcl_version Current version of Tcl in major.minor form.
1666
167Tcl/Tk Reference Guide
1684. Operators and Expressions
169The expr command recognizes the following operators, in decreasing order of
170precedence:
171- ˜ ! unary minus, bitwise NOT, logical NOT
172* / % multiply, divide, remainder
173+ - add, subtract
174<< >> bitwise shift left, bitwise shift right
175< > <= >= boolean comparisons
176== != boolean equals, not equals
177eq ne boolean string equals, not equals
178& bitwise AND
179∧ bitwise exclusive OR
180| bitwise inclusive OR
181&& logical AND
182|| logical OR
183x ? y : z if x != 0, then y, else z
184All operators support integers. All support floating point except ˜, %, <<, >>, &,
185∧,
186and |. Boolean operators can also be used for string operands (but note eq and
187ne), in which case string comparison will be used. This will occur if any of the
188operands are not valid numbers. The &&, ||, and ?: operators have “lazy
189evaluation”, as in C.
190Possible operands are numeric values, Tcl variables (with $), strings in double
191quotes or braces, Tcl comands in brackets, and the following math functions:
192abs cos hypot round tanh
193acos cosh int sin wide
194asin double log sinh
195atan exp log10 sqrt
196atan2 floor pow srand
197ceil fmod rand tan
1985. Regular Expressions
199regex* match zero or more of regex
200regex+ match one or more of regex
201regex? match zero or one of regex
202regex{m} match exactly m of regex
203regex{m,} match m or more of regex
204regex{m,n} match m through n of regex
205*? +? ?? {m}? {m,}? {m,n}?
206match smallest number of regex rather than longest
207regex|regex match either expression
208. any single character except newline
209( ) capture group (possibly empty)
210(?: ) non-capture group (possibly empty)
211∧ $ match beginning, end of line
212(?=regex) (?!regex) match ahead to point where regex begins, does not begin
213[abc] [∧abc] match characters in set, not in set
214[a-z] [∧a-z] match characters in range, not in range
2157
216Tcl/Tk Reference Guide
217[:class:] within range, match class character; class is alpha,
218upper, lower, digit, xdigit, alnum, print,
219blank, space, punct, graph, or cntrl
220\d \s \w synonym for [[:digit:]], [[:space:]], [[:alnum:]_]
221\D \S \W synonym for [∧[:digit:]], [∧[:space:]], [∧[:alnum:]_]
222\c match character c even if special
223\cX match control character ∧X
224\0 \xhhh match character with value 0, value 0xhhh
225\e match ESC
226\B synonym for \
227\A \Z match beginning, end of string
228\m \M match beginning, end of word
229\y match beginning or end of word
230\Y match at point which is not beginning or end of word
231\m back reference to mth group
232Meta syntax is specified when the regex begins with a special form.
233***=regex regex is a literal string
234(?letters)regex Embedded options:
235b regex is a basic regular expression
236c case-sensitive matching
237e regex is an extended regular expression
238i case-insensitive matching (-nocase)
239n new-line sensitive matching (-line)
240p partial new-line sensitive matching (-linestop)
241q rest of regex is a literal
242s non-newline sensitive matching (default)
243t tight syntax regex
244w inverse partial new-line sensitive matching
245(-lineanchor)
246x expanded syntax regex (-expanded)
2476. Pattern Globbing
248? match any single character
249* match zero or more characters
250[abc] match set of characters
251[a-z] match range of characters
252\c match character c
253{a,b,. . . } match any of strings a, b, etc.
254˜ home directory (for glob command)
255˜user match user’s home directory (for glob command)
256Note: for the glob command, a ‘.’ at the beginning of a file’s name or just after ‘/’
257must be matched explicitly and all ‘/’ characters must be matched explicitly.
2588
259Tcl/Tk Reference Guide
2607. Control Statements
261break Abort innermost containing loop command.
262case Obsolete, see switch.
263continue
264Skip to the next iteration of innermost containing loop command.
265exit [returnCode]
266Terminate the process, returning returnCode (an integer which defaults to
2670) to the system as the exit status.
268for start test next body
269Looping command where start, next, and body are Tcl command strings
270and test is an expression string to be passed to expr command.
271foreach varname list body
272The Tcl command string body is evaluated for each item in the string list
273where the variable varname is set to the item’s value.
274foreach varlist1 list1 [varlist2 list2 . . . ] body
275Same as above, except during each iteration of the loop, each variable in
276varlistN is set to the current value from listN.
277if expr1 [ then ] body1 [ elseif expr2 [ then ] body2 . . . ] [ [ else ] bodyN ]
278If expression string expr1 evaluates true, Tcl command string body1 is
279evaluated. Otherwise if expr2 is true, body2 is evaluated, and so on. If
280none of the expressions evaluate to true then bodyN is evaluated.
281return [-code code] [-errorinfo info] [-errorcode value] [string]
282Return immediately from current procedure with string as return value.
283The code is one of ok (default), error (-errorinfoand
284-errorcodeprovide values for the corresponding Tcl variables),
285return, break, continue, or integer.
286switch [options] string pattern1 body1 [ pattern2 body2 . . . ]
287switch [options] string {pattern1 body1 [ pattern2 body2 . . . ] }
288The string argument is matched against each of the pattern arguments in
289order. The bodyN of the first match found is evaluated. If no match is
290found and the last pattern is the keyword default, its bodyN is
291evaluated. Possible options are -glob, -regexp, and -exact(default).
292while test body
293Evaluates the Tcl command string body as long as expression string test
294evaluates to true.
2958. File Information
296file atime fileName [time]
297Query or set time fileName was last accessed as seconds since Jan. 1, 1970.
298file attributes fileName [option [value . . . ] ]
299Query or set platform-specific attributes of fileName. Options are for UNIX:
300-groupid | name, -ownerid | name, -permissionsoctal |
301[ugo]?[[+-=][rwxst],[...]]; for Windows -archive,
302-hidden, -longname, -readonly, -shortname, -system; and for
303MacOS: -creator, -hidden, -readonly, -type.
304file channels [pattern]
305Returns list of open channels matching glob pattern in current interpreter. If
306no pattern is given, returns all channels.
3079
308Tcl/Tk Reference Guide
309file copy [-force] [- -] source [source . . . ] target
310Makes a copy of source under name target. If multiple sources are given,
311target must be a directory. Use -force to overwrite existing files.
312file delete [-force] [- -] fileName [fileName . . . ]
313Removes given files. Use -force to remove non-empty directories.
314file dirname fileName
315Returns all directory path components of fileName.
316file executable fileName
317Returns 1 if fileName is executable by user, 0 otherwise.
318file exists fileName
319Returns 1 if fileName exists (and user can read its directory), 0 otherwise.
320file extension fileName
321Returns all characters in fileName after and including the last dot.
322file isdirectory fileName
323Returns 1 if fileName is a directory, 0 otherwise.
324file isfile fileName
325Returns 1 if fileName is a regular file, 0 otherwise.
326file join name [name . . . ]
327Joins file names using the correct path separator for the current platform.
328file link linkName
329Return target of symbolic link linkName.
330file link linkName target
331Create symbolic link linkName to target.
332file link [-hard] linkName [target]
333file link [-symbolic] linkName [target]
334Create either hard or symbolic link linkName to target.
335file lstat fileName varName
336Same as file stat except uses the lstat kernel call.
337file mkdir dirName [dirName . . . ]
338Creates given directories.
339file mtime fileName [time]
340Query or set time fileName was last modified as seconds since Jan. 1, 1970.
341file nativename fileName
342Returns the platform-specific name of fileName.
343file normalize fileName
344Returns normalised path representation for fileName.
345file owned fileName
346Returns 1 if fileName owned by the current user, 0 otherwise.
347file pathtype fileName
348Returns one of absolute, relative, or volumerelative.
349file readable fileName
350Returns 1 if fileName is readable by current user, 0 otherwise.
351file readlink fileName
352Returns value of symbolic link given by fileName.
353file rename [-force] [- -] source [source . . . ] target
354Renames file source to target. If target is an existing directory, each source
355file is moved there. The -force option forces overwriting of existing files.
356file rootname fileName
357Returns all the characters in fileName up to but not including last dot.
35810
359Tcl/Tk Reference Guide
360file separator
361Returns path separator for the current platform.
362file separator [fileName]
363Returns path separator for filesystem containing fileName.
364file size fileName
365Returns size of fileName in bytes.
366file split fileName
367Returns list whose elements are the path components of fileName.
368file stat fileName varName
369Place results of stat kernel call on fileName in variable varName as an array
370with elements atime, ctime, dev, gid, ino, mode, mtime, nlink,
371size, type, and uid.
372file system fileName
373Returns two-element list for fileName: filesystem name and type (which may
374be null).
375file tail fileName
376Return all characters in fileName after last directory separator.
377file type fileName
378Returns type of fileName. Possible values are file, directory,
379characterSpecial, blockSpecial, fifo, link, or socket.
380file volumes
381Returns just ‘/’ on UNIX, list of local drives on Windows, and list of local
382and network drives on MacOS.
383file writable fileName
384Returns 1 if fileName is writable by current user, 0 otherwise.
3859. Tcl Interpreter Information
386info args procName
387Returns list describing in order the names of arguments to procName.
388info body procName
389Returns the body of procedure procName.
390info cmdcount
391Returns the total number of commands that have been invoked.
392info commands [pattern]
393Returns list of Tcl commands (built-ins and procs) matching glob pattern
394(default *). If no pattern is given, returns all commands in current
395namespace.
396info complete command
397Returns 1 if command is a complete Tcl command, 0 otherwise. Complete
398means having no unclosed quotes, braces, brackets or array element names
399info default procName arg varName
400Returns 1 if procedure procName has a default for argument arg and places
401the value in variable varName. Returns 0 if there is no default.
402info exists varName
403Returns 1 if the variable varName exists in the current context, 0 otherwise.
404info functions [pattern]
405Returns list of math functions matching glob pattern (default *).
406info globals [pattern]
407Returns list of global variables matching glob pattern (default *).
40811
409Tcl/Tk Reference Guide
410info hostname
411Returns name of computer on which interpreter was invoked.
412info level
413Returns the stack level of the invoking procedure.
414info level number
415Returns name and arguments of procedure invoked at stack level number.
416info library
417Returns name of library directory where standard Tcl scripts are stored.
418info loaded [interp]
419Returns list describing packages loaded into interp.
420info locals [pattern]
421Returns list of local variables matching glob pattern (default *).
422info nameofexecutable
423Returns full pathname of binary from which the application was invoked.
424info patchlevel
425Returns current patch level for Tcl.
426info procs [pattern]
427Returns list of Tcl procedures in current namespace matching glob pattern
428(default *).
429info script [filename]
430Query or set name of Tcl script currently being evaluated.
431info sharedlibextension
432Returns extension used by platform for shared objects.
433info tclversion
434Returns version number of Tcl in major.minor form.
435info vars [pattern]
436Returns list of currently-visible variables matching glob pattern (default *).
43710. Lists
438concat [arg arg . . . ]
439If all args are lists, return a list which is a concatenation of each arg.
440Otherwise, return the concatenation of the string value of each arg
441(separated by a space) as a single string.
442join list [joinString]
443Returns string created by joining all elements of list with joinString.
444lappend varName [value value . . . ]
445Appends each value to the end of the list stored in varName.
446lindex list
447lindex list {}
448Returns list.
449lindex list index
450Returns value of element at index in list.
451lindex list index . . .
452lindex list indexList
453Each successive index value is used to select the element in the sublist
454selected by the previous index value. Return the result.
455linsert list index element [element . . . ]
456Returns new list formed by inserting given new elements at index in list.
45712
458Tcl/Tk Reference Guide
459list [arg arg . . . ]
460Returns new list formed by using each arg as an element.
461llength list
462Returns number of elements in list.
463lrange list first last
464Returns new list from slice of list at indices first through last inclusive.
465lreplace list first last [value value . . . ]
466Returns new list formed by replacing elements first through last in list with
467given values.
468lsearch [options] list pattern
469Returns index of first element in list that matches pattern (-1 for no match).
470Options are
471-all return all matching indices or values
472-ascii list elements are strings (only meaningful with
473-exactor -sorted)
474-decreasing list elements are sorted in decreasing order (only
475meaningful with -sorted)
476-dictionary list elements are compared using dictionary-style
477comparisons (only meaningful with -exactor
478-sorted)
479-exact string match
480-glob glob pattern match (default)
481-increasing list elements are sorted in increasing order (only
482meaningful with -sorted)
483-inline return matching value, not index
484-integer list elements are compared as integers (only
485meaningful with -exactor -sorted)
486-not negate the sense of the match
487-real list elements are compared as floating point values
488(only meaningful with -exactor -sorted)
489-regexp regex match
490-sorted use sorted list search algorithm (cannot be used with
491-globor -regexp)
492-startindex start search at index
493lset varName newValue
494lset varName {} newValue
495Replace the value of list varName with newValue. Return the result.
496lset varName index newValue
497Replace the element at index in list varName with newValue. Return the
498result.
499lset varName index . . . newValue
500lset varName indexList newValue
501Replace the element identified by index . . . (or indexList) in list varName
502with newValue. Each successive index value is used to select the element in
503the sublist selected by the previous index value. Return the result.
504lsort [switches] list
505Returns new list formed by sorting list according to switches. Switches are
506-ascii string comparison (default)
507-dictionary like -asciibut ignores case and is number smart.
50813
509Tcl/Tk Reference Guide
510-indexndx treats each elements as a sub-list and sorts on the
511ndxth element
512-integer integer comparison
513-real floating-point comparison
514-increasing sort in increasing order (default)
515-decreasing sort in decreasing order
516-commandcmd Use cmd which takes two arguments and returns an
517integer less than, equal to, or greater than zero
518-unique retain only the last duplicate element
519split string [splitChars]
520Returns a list formed by splitting string at each character in splitChars
521(default white-space).
522List Indices:
523Start at 0. The word end may be used to reference the last element in the
524list, and end-integer refers to the last element in the list minus the specified
525integer offset.
52611. Arrays
527array anymore arrayName searchId
528Returns 1 if anymore elements are left to be processed in array search
529searchId on arrayName, 0 otherwise.
530array donesearch arrayName searchId
531Terminates the array search searchId on arrayName.
532array exists arrayName
533Returns 1 if arrayName is an array variable, 0 otherwise.
534array get arrayName
535Returns a list where each odd element is an element name and the following
536even element its corresponding value.
537array names arrayName [mode] [pattern]
538Returns list of all element names in arrayName that match pattern. Mode
539may be -exact, -glob (default *), or -regexp.
540array nextelement arrayName searchId
541Returns name of next element in arrayName for the search searchId.
542array set arrayName list
543Sets values of elements in arrayName for list in array get format.
544array size arrayName
545Return number of elements in arrayName.
546array startsearch arrayName
547Returns a search id to use for an element-by-element search of arrayName.
548array statistics arrayName
549Returns hashtable statistics for arranName.
550array unset arrayName [pattern]
551Unsets all of the elements in the array that match glob pattern (default *). If
552pattern is omitted, the entire array is unset.
553parray arrayName [pattern]
554Print to standard output the names and values of all element names in
555arrayName that match glob pattern (default *.)
55614
557Tcl/Tk Reference Guide
55812. Strings and Binary Data
559append varName [value value . . . ]
560Appends each of the given values to the string stored in varName.
561binary format formatString [arg arg . . . ]
562Returns a binary string representation of argss composed according to
563formatString, a sequence of zero or more field codes each followed by an
564optional integer count or *. The possible field codes are:
565a chars (null padding) c 8-bit int W 64-bit int (big)
566A chars (space padding) s 16-bit int (little) f float
567b binary (low-to-high) S 16-bit int (big) d double
568B binary (high-to-low) i 32-bit int (little) x nulls
569h hex (low-to-high) I 32-bit int (big) X backspace
570H hex (high-to-low) w 64-bit int (little) @ absolute position
571binary scan string formatString [varName varName . . . ]
572Extracts values into varName’s from binary string according to
573formatString. Returns the number of values extracted. For integer and
574floating point field codes, a list of count values are consumed and stored in
575the corresponding varName. Field codes are the same as for binary format
576with the additional:
577a chars (no trimming) A chars (trimming) x skip forward
578format formatString [arg arg . . . ]
579Returns a formated string generated in the ANSI C sprintf-like manner.
580Place holders have the form %[argpos$][flag][width][.prec][h|l]char
581where argpos is an integer, width and prec are integers or *, possible values
582for char are:
583d signed decimal X unsigned HEX E float (0E0)
584u unsigned decimal c int to char g auto float (f or e)
585i signed decimal s string G auto float (f or E)
586o unsigned octal f float (fixed) % plain %
587x unsigned hex e float (0e0)
588and possible values for flag are:
589- left-justified 0 zero padding # alternate output
590+ always signed space space padding
591The optional trailing h or l truncates the data to 16-bits or expands it to
59264-bits for integer conversions.
593regexp [switches] exp string [matchVar] [subMatchVar . . . ]
594Returns 1 if the regular expression exp matches part or all of string , 0
595otherwise. If specified, matchVar will be set to all the characters in the match
596and the following subMatchVar’s will be set to matched parenthesized
597subexpressions. Switches are
598-about Instead of matching, returns an informational list. The
599first element is a subexpression count, the second a
600list of property names that describe various attributes
601of the regular expression.
602-all Match as many times as possible in the string,
603returning the total number of matches found. If match
60415
605Tcl/Tk Reference Guide
606variables are present, they will continue information
607for the last match only.
608-expanded Enable expanded form of the regular expression.
609-indices matchVar and subMatchVar will be set to the start and
610ending indices in string of their corresponding match.
611-inline Return, as a list, the data that would otherwise be
612placed in match variables (which may not be
613specified.) If used with -all, the list will be
614concatenated at each iteration. For each match
615iteration, the command will append the overall match
616data, plus one element for each subexpression in the
617regular expression.
618-line Enable newline-sensitive matching. With this flag,
619‘[∧]’ bracket expressions and ‘.’ never match newline,
620‘
621∧’ matches an empty string after any newline in
622addition to its normal function, and ‘$’ matches an
623empty string before any newline in addition to its
624normal function. This flag is equivalent to specifying
625both -linestopand -lineanchor.
626-lineanchor With this flag, ‘∧’ and ‘$’ match the beginning and
627end of a line respectively.
628-linestop With this flag, ‘[∧]’ bracket expressions and ‘.’ stop at
629newlines.
630-nocase Ignore case in matching.
631-startindex An offset into the string to start matching.
632regsub [switches] exp string subSpec [varName]
633Replaces the first portion of string that matches the regular expression exp
634with subSpec and optionally places results in varName. If subSpec contains
635a ‘&’ or “\0”, then it is replaced in the substitution with the portion of string
636that matched exp. If subSpec contains a “\n” then it is replaced in the
637substitution with the portion of string that matched the nth parenthesized
638subexpression of exp. Returns either count of number of replacements made
639if varName was provided or the result of the substitution. Switches are
640-all Substitution is performed for each ranges in string
641that match.
642-expanded Enable expanded form of the regular expression.
643-indices matchVar and subMatchVar will be set to the start and
644ending indices in string of their corresponding match.
645-line Enable newline-sensitive matching. With this flag,
646‘[∧]’ bracket expressions and ‘.’ never match newline,
647‘
648∧’ matches an empty string after any newline in
649addition to its normal function, and ‘$’ matches an
650empty string before any newline in addition to its
651normal function. This flag is equivalent to specifying
652both -linestopand -lineanchor.
653-lineanchor With this flag, ‘∧’ and ‘$’ match the beginning and
654end of a line respectively.
655-linestop With this flag, ‘[∧]’ bracket expressions and ‘.’ stop at
656newlines.
657-nocase Ignore case in matching.
65816
659Tcl/Tk Reference Guide
660-startindex An offset into the string to start matching.
661scan string formatString [varName varName . . . ]
662Extracts values into given variables using ANSI C sscanf behavior. Returns
663the number of values extracted, or if no varName’s were specified, returns a
664list of the data that would otherwise be stored in the variables. Place holders
665have the form %[*][width][h|l|L]char where * is for discard, width is an
666integer. If the form is %integer$char, then the variable to use is taken from
667the argument indicated by the number, where 1 corresponds to the first
668varName. If there are any positional specifiers in format then all of the
669specifiers must be positional. Possible values for char are:
670d decimal e float s string (non-whitespace)
671o octal f float [chars] chars in given range
672x hex g float [
673∧chars] chars not in given range
674u unsigned i integer c char to int
675n number scanned
676The modifier h is ignored, but l or L scans a 64-bit value for integer
677conversions.
678string bytelength string
679Returns the number of bytes to represent the UTF-8 representation of string
680in memory.
681string compare [options] string1 string2
682Returns -1, 0, or 1, depending on whether string1 is lexicographically less
683than, equal to, or greater than string2. Options are -nocaseor -length
684integer.
685string equal [options] string1 string2
686Returns 0 or 1, depending on whether string1 is lexicographically equal to
687string2. Options are -nocaseor -lengthinteger.
688string first string1 string2 [startIndex]
689Return index (-1 if not found) in string2 of first occurrence of string1
690starting at startIndex (default 0).
691string index string charIndex
692Returns for index an integer, the charIndex’th character in string. If index is
693end, the last character in string, and if index is end-integer, the last
694character minus the specified offset.
695string is class [options] string
696Returns 1 if string is a valid member of the specified character class, 0
697otherwise. If option -strictis specified, then an empty string returns 0,
698otherwise 1 on any class. If -failindexvarname is specified then, on
699failure, the index in the string where the class was no longer valid will be
700stored in varname. Character classes are
701alnum Alphabetic or digit character
702alpha Alphabetic character
703ascii Character in 7-bit ascii range
704boolean Any of Tcl boolean forms
705control A control character
706digit A digit character
707double Any of Tcl double forms with optional surrounding
708white space; 0 returned for under/overflow with
709varname set to -1
710false Any Tcl boolean false form
71117
712Tcl/Tk Reference Guide
713graph Any printing character except space
714integer Any of Tcl integer forms with optional surrounding
715white space; 0 returned for under/overflow with
716varname set to -1
717lower A lower case alphabetic character
718print Any printing character including space
719punct A punctuation character
720space A white-space character
721true Any Tcl boolean true form
722upper A upper case character
723wordchar A valid word character
724xdigit A digit or letter in the range [a–fA–F]
725string last string1 string2 lastIndex
726Return index (-1 if not found) in string2 of last occurrence of string1 no
727higher than lastIndex (default end).
728string length string
729Returns the number of characters in string.
730string map [-nocase] charMap string
731Replaces characters in string based on the key-value pairs in charMap. Each
732instance of a key in the string will be replaced with its corresponding value.
733string match [-nocase] pattern string
734Returns 1 if glob pattern matches string, 0 otherwise.
735string range string first last
736Returns characters from string at indices first through last inclusive. The
737indices are as for string index.
738string repeat string count
739Returns new string formed by string repeated count times.
740string replace string first last [newstring]
741Removes characters from string at indices first through last inclusive. If
742newstring is supplied, it will replace the removed characters. The indices are
743as for string index.
744string tolower string [first [last]]
745Returns new string formed by converting all chars in string to lower case at
746indices first through last inclusive. The indices are as for string index.
747string totitle string [first [last]]
748Returns new string formed by converting the first character in string to upper
749case and the remainder to lower case at indices first through last inclusive.
750The indices are as for string index.
751string toupper string [first [last]]
752Returns new string formed by converting all chars in string to upper case at
753indices first through last inclusive. The indices are as for string index.
754string trim string [chars]
755Returns new string formed by removing from string any leading or trailing
756characters present in the set chars (default whitespace).
757string trimleft string [chars]
758Same as string trim for leading characters only.
759string trimright string [chars]
760Same as string trim for trailing characters only.
76118
762Tcl/Tk Reference Guide
763string wordend string index
764Returns index of character just after last one in word at index in string.
765string wordstart string index
766Returns index of first character of word at index in string.
767subst [-nobackslashes] [-nocommands] [-novariables] string
768Returns result of backslash, command, and variable substitutions on string.
769Each may be turned off by switch.
77013. System Interaction
771cd [dirName]
772Change working directory to dirName.
773clock clicks [-milliseconds]
774Returns hi-res system-dependent integer time value. If -millisecondsis
775specified, then the value is guaranteed to be of millisecond granularity.
776clock format clockVal [-formatstring] [-gmt boolean]
777Convert integer clockVal to human-readable format defined by string which
778recognizes (at least) the following place holders:
779%% % %p AM/PM
780%a weekday (abbr) %Q Stardate
781%A weekday (full) %r locale time; %I:%M:%S %p
782%b month (abbr) %R %H:%M
783%B month (full) %S seconds (00 – 59)
784%C century (19 or 20) %s seconds since epoch
785%d day (01 – 31) %t \t
786%D %m/%d/%y %T %H:%M:%S
787%e day (1 – 31) %U week, Sun–Sat (00 – 52)
788%H hour (00 – 23) %u weekday (Mon=1, Sun=7)
789%h month (abbr) %V week, Jan 4 is week 1 (01 – 53)
790%I hour (01 – 12) %W week, Mon–Sun (00 – 52)
791%j day (001 – 366) %w weekday (Sun=0 – Sat=6)
792%k hour (0 – 23) %x locale date; %m/%d/%y
793%l hour (1 – 12) %X locale time; %H:%M:%S
794%M minute (00 – 59) %y year (00 – 99)
795%m month (01 – 12) %Y year (full)
796%n \n %Z time zone
797%c locale date & time; %a %b %d %H:%M:%S %Y
798The default format is ”%a %b %d %H:%M:%S %Z %Y”.
799clock scan dateString [-base clockVal] [-gmt boolean]
800Convert dateString to an integer clock value. If dateString contains a 24
801hour time only, the date given by clockVal is used.
802clock seconds
803Return current date and time as system-dependent integer value.
804exec [-keepnewline] arg [arg . . . ]
805Execute subprocess using each arg as word for a shell pipeline and return
806results written to standard out, optionally retaining the final newline char.
807The following constructs can be used to control I/O flow.
808| pipe (stdout)
809|& pipe (stdout and stderr)
810<fileName stdin from file
81119
812Tcl/Tk Reference Guide
813<@ fileId stdin from open file
814<<value pass value to stdin
815>fileName stdout to file
8162>fileName stderr to file
817>& fileName stdout and stderr to file
818>>fileName append stdout to file
8192>>fileName append stderr to file
820>>& fileName stdout and stderr to file
821>@ fileId stdout to open file
8222>@ fileId stderr to open file
823>&@ fileId stdout and stderr to open file
824& run in background
825glob [switches] pattern [pattern . . . ]
826Returns list of all files in current directory that match any of the given glob
827patterns, as interpreted by the given switches. Switches are
828-directorydirectory
829Search starting in the given directory. May not be
830used with -path.
831-join The pattern arguments are treated as a single pattern
832obtained by joining the arguments with directory
833separators.
834-nocomplain Allows an empty list to be returned without error.
835-pathpathPrefix Search with the given pathPrefix where the rest of the
836name matches the given patterns. May not be used
837with -directory.
838-tails Only return part of file which follows last directory
839named in -directoryor -path specification.
840-typestypeList Only match files or directories which match typeList,
841where the items in the list have two forms (which
842may be mixed.)
843The first form is: b (block special file), c (character
844special file), d (directory), f (plain file), l (symbolic
845link), p (named pipe), or s (socket), where multiple
846types may be specified in the list. Return all files
847which match at least one of the types given.
848For the second form, all the types must match. These
849are r, w, x as file permissions, and readonly,
850hiddenas special permission cases.
851pid [fileId]
852Return process id of process pipeline fileId if given, otherwise return process
853id of interpreter process.
854pwd Returns the current working directory.
85514. File Input/Output
856close fileId
857Close the open file channel fileId.
858eof fileId
859Returns 1 if an end-of-file has occurred on fileId, 0 otherwise.
86020
861Tcl/Tk Reference Guide
862fblocked fileId
863Returns 1 if last read from fileId exhausted all available input.
864fconfigure fileId [option [value]]
865Sets and gets options for I/O channel fileId. Options are:
866-blockingboolean Whether I/O can block process.
867-buffering full|line|none
868How to buffer output.
869-buffersizebyteSize Size of buffer.
870-encodingname
871Specify Unicode encoding to name or binary.
872-eofcharchar | {inChar outChar}
873Sets character to serve as end-of-file marker.
874-translationmode | {inMode outMode}
875Sets how to translate end-of-line markers.
876Modes are auto, binary, cr, crlf, and lf.
877For socket channels (read-only settings):
878-error
879Returns current error status.
880-sockname
881Returns three element list with address, host name and port number.
882-peername
883For client and accepted sockets, three element list of peer socket.
884For serial device channels:
885-modebaud,parity,data,stop
886Set baud rate, parity (n, o, e, m or s), data bits, and stop bits of
887channel.
888-handshaketype
889Set handshake control (none, rtsctsor xonxoff).
890-queue
891Return a list of two integers: current number of bytes in input queue
892and output queue.
893-timeoutmsec
894Set timeout for blocking reads.
895-ttycontrol{signal boolean . . . }
896Setup the handshake output lines (rts or dtr) permanently or send a
897BREAK (break).
898-ttystatus
899Return list of current modem status and handshake signals: {CTS
900boolean DSR boolean RING boolean DCD boolean }
901-xchar{xonChar xoffChar}
902Set software handshake characters.
903fcopy inId outId [-size size] [-commandcallback]
904Transfer data to outId from inId until eof or size bytes have been transferred.
905If -commandis given, copy occurs in background and runs callback when
906finished appending number of bytes copied and possible error message as
907arguments.
908fileevent fileId readable|writable[script]
909Evaluate script when channel fileId becomes readable/writable.
910flush fileId
911Flushes any output that has been buffered for fileId.
91221
913Tcl/Tk Reference Guide
914gets fileId
915Read and return next line from channel fileId, discarding newline character.
916gets fileId varName
917Read next line from channel fileId, discarding newline character, into
918varName. Return count of characters read, or -1 if end-of-file.
919open item [access [perms]]
920Open item (a file, serial port or command pipeline) and return its channel id.
921A command pipeline (the first character of item is ‘|’) is a list as described
922for exec. If a new file is created, its permission are set to the conjunction of
923perms (default 0666) and the process umask. The first form of access may be
924r Read only. File must exist.
925r+
926Read and write. File must exist.
927w Write only. Truncate if exists.
928w+
929Read and write. Truncate if exists.
930a Write only. File must exist. Access position at end.
931a+
932Read and write. Access position at end.
933The second form of access may be a list containing any of the following
934flags (although one of the flags must be either RDONLY, WRONLYor RDWR.)
935RDONLY Open the file for reading only.
936WRONLY Open the file for writing only.
937RDWR Open the file for both reading and writing.
938APPEND Set the file pointer to the end of the file prior to each write.
939CREAT Create the file if it doesn’t already exist.
940EXCL If CREATis also specified, an error is returned if the file
941already exists.
942NOCTTY Prevent the terminal device from becoming the controlling
943terminal of the process.
944NONBLOCK Prevents the process from blocking while opening the file,
945and possibly in subsequent I/O operations.
946TRUNC If the file exists it is truncated to zero length.
947puts [-nonewline] [fileId] string
948Write string to fileId (default stdout) optionally omitting newline char.
949read [-nonewline] fileId
950Read all remaining bytes from fileId, optionally discarding last character if it
951is a newline.
952read fileId numBytes
953Read numBytes bytes from fileId.
954seek fileId offset [origin]
955Change current access position on fileId to offset bytes from origin which
956may be start(default), current, or end.
957socket [option . . . ] host port
958Open a client-side TCP socket to server host on port (integer or service
959name). Options are:
960-myaddraddr
961Set network address of client (if multiple available).
962-myportport Set connection port of client (if different from server).
96322
964Tcl/Tk Reference Guide
965-async Make connection asynchronous.
966socket -servercommand [-myaddraddr] port
967Open server TCP socket on port (integer or service name) invoking
968command once connected with three arguments: the channel, the address,
969and the port number. If port is zero, the operating system will choose a port
970number.
971tell fileId
972Return current access position in fileId.
97315. Multiple Interpreters
974interp alias srcPath srcCmd
975Returns list whose elements are the targetCmd and args associated with the
976alias srcCmd in interpreter srcPath.
977interp alias srcPath srcCmd {}
978Deletes the alias srcCmd in interpreter srcPath.
979interp alias srcPath srcCmd targetPath targetCmd [arg . . .]
980Creates an alias srcCmd in interpreter srcPath which when invoked will run
981targetCmd and args in the interpreter targetPath.
982interp aliases [path]
983Returns list of all aliases defined in interpreter path.
984interp create [-safe] [- -] [path]
985Creates a slave interpreter (optionally safe) named path.
986interp delete path [path . . . ]
987Deletes the interpreter(s) path and all its slave interpreters.
988interp eval path arg [arg . . .]
989Evaluates concatenation of args as command in interpreter path.
990interp exists path
991Returns 1 if interpreter path exists, 0 otherwise.
992interp expose path hiddenCmd [exposedCmd]
993Make hiddenCmd in interpreter path exposed (optionally as exposedCmd).
994interp hide path exposedCmd [hiddenCmd]
995Make exposedCmd in interpreter path hidden (optionally as hiddenCmd).
996interp hidden path
997Returns list of hidden commands in interpreter path.
998interp invokehidden path [-global] hiddenCmd [arg . . . ]
999Invokes hiddenCmd with specified args in interpreter path (at the global
1000level if -global is given).
1001interp issafe [path]
1002Returns 1 if interpreter path is safe, 0 otherwise.
1003interp marktrusted [path]
1004Marks interpreter path as trusted.
1005interp recursionlimit path [newLimit]
1006Queries or sets recursion limit (default 1000) for interpreter path.
1007interp share srcPath fileId destPath
1008Arranges for I/O channel fileId in interpreter srcPath to be shared with
1009interpreter destPath.
1010interp slaves [path]
1011Returns list of names of all slave interpreters of interpreter path.
101223
1013Tcl/Tk Reference Guide
1014interp target path alias
1015Returns Tcl list describing target interpreter of alias in interpreter path.
1016interp transfer srcPath fileId destPath
1017Moves I/O channel fileId from interpreter srcPath to destPath.
1018For each slave interpreter created, a new Tcl command is created by the same name
1019in its master. This command has the alias, aliases, eval, expose, hide, hidden,
1020invokehidden, issafe, marktrusted and recursionlimit subcommands like
1021interp, but without the srcPath and path arguments (they default to the slave itself)
1022and without the targetPath argument (it defaults to the slave’s master).
1023A safe interpreter is created with the following commands exposed:
1024after eval info package string
1025append expr interp pid subst
1026array fblocked join proc switch
1027binary fcopy lappend puts tell
1028break fileevent lindex read time
1029case flush linsert regexp trace
1030catch for list regsub unset
1031clock foreach llength rename update
1032close format lrange return uplevel
1033concat gets lreplace scan upvar
1034continue global lsearch seek variable
1035eof if lsort set vwait
1036error incr namespace split while
1037A safe interpreter is created with the following commands hidden:
1038cd exit glob open socket
1039encoding fconfigure load pwd source
1040exec file
1041The following support procedures are also hidden:
1042auto_exec_ok auto_import auto_load
1043auto_load_index auto_qualify unknown
1044The $env variable is also not present in a safe interpreter.
104516. Packages
1046package forget package . . .
1047Remove all info about each package from interpreter.
1048package ifneeded package version [script]
1049Tells interpreter that if version version of package, evaluating script will
1050provide it.
1051package names
1052Returns list of all packages in the interpreter that are currently provided or
1053have an ifneeded script available.
1054package provide package [version]
1055Tells interpreter that package version is now provided. Without version, the
1056currently provided version of package is returned.
1057package require [-exact] package [version]
1058Tells interpreter that package must be provided. Only packages with
1059versions equal to or later than version (if provided) are acceptable. If
1060-exactis specified, the exact version specified must be provided.
1061package unknown [command]
1062Specifies a last resort Tcl command to provide a package which have append
1063as its final two arguments the desired package and version.
106424
1065Tcl/Tk Reference Guide
1066package vcompare version1 version2
1067Returns -1 if version1 is earlier than version2, 0 if equal, and 1 if later.
1068package versions package
1069Returns list of all versions numbers of package with an ifneeded script.
1070package vsatisfies version1 version2
1071Returns 1 if version2 scripts will work unchanged under version1, 0
1072otherwise.
1073pkg_mkIndex [switches] directory [pattern . . . ]
1074Build the pkgIndex.tclfile for automatic loading of packages. Each
1075glob pattern (default *.tcl *.[info sharedlibextension]
1076selects script or binary files in directory. Switches are:
1077-direct (Default) The generated index will implement direct loading
1078of the package upon package require.
1079-lazy The generated index will delay loading until the use of one
1080of the commands provided by the package,
1081-loadpkgPat
1082The index process will pre-load any packages that exist in
1083the current interpreter and match glob pkgPat into the slave
1084interpreter used to generate the index.
1085-verbose Generate output during the indexing process.
1086::pkg::create -name pkgName -versionversion options . . .
1087Create appropriate package ifneeded command for version version of
1088package pkgName. Options are:
1089-loadfilespecList
1090A binary library that must be loaded. The filespecList
1091contains one or two elements: the first is the name of the file
1092to load, the second (optional) is a list of commands supplied
1093by loading that file.
1094-sourcefilespecList
1095A Tcl library that must be sourced. The filespecList contains
1096one or two elements: the first is the name of the file to load,
1097the second (optional) is a list of commands supplied by
1098loading that file.
109917. Namespaces
1100namespace children [namespace] [pattern]
1101Returns list of child namespaces belonging to namespace (defaults to
1102current) which match pattern (default *).
1103namespace code script
1104Returns new script string which when evaluated arranges for script to be
1105evaluated in current namespace. Useful for callbacks.
1106namespace current
1107Returns fully-qualified name of current namespace.
1108namespace delete [namespace . . . ]
1109Each given namespace is deleted along with their child namespaces,
1110procedures, and variables.
1111namespace eval namespace arg [arg . . . ]
1112Activates namespace and evaluates concatenation of args’s inside it.
111325
1114Tcl/Tk Reference Guide
1115namespace exists namespace
1116Returns 1 if namespace is a valid namespace in the current context, returns 0
1117otherwise.
1118namespace export [-clear] [pattern . . . ]
1119Adds to export list of current namespace all commands that match given
1120pattern’s. If -clear is given, the export list is first emptied.
1121namespace forget [namespace::pattern . . . ]
1122Removes from current namespace any previously imported commands from
1123namespace that match pattern.
1124namespace import [-force] [namespace::pattern . . . ]
1125Imports into current namespace commands matching pattern from
1126namespace. The -force option allows replacing of existing commands.
1127namespace inscope namespace listArg [arg . . . ]
1128Activates namespace (which must already exist) and evaluates inside it the
1129result of lappend of arg’s to listArg.
1130namespace origin command
1131Returns fully-qualified name of imported command.
1132namespace parent [namespace]
1133Returns fully-qualified name of parent namespace of namespace.
1134namespace qualifiers string
1135Returns any leading namespace qualifiers in string.
1136namespace tail string
1137Returns the simple name (strips namespace qualifiers) in string.
1138namespace which [-command|-variable] name
1139Returns fully-qualified name of the command (or as variable, if -variable
1140given) name in the current namespace. Will look in global namespace if not
1141in current namespace.
1142variable [name value . . . ] name [value]
1143Creates one or more variables in current namespace (if name is unqualified)
1144initialized to optionally given values. Inside a procedure and outside a
1145namespace eval, a local variable is created linked to the given namespace
1146variable.
114718. Other Tcl Commands
1148after ms [arg1 arg2 arg3 . . .]
1149Arrange for command (concat of args) to be run after ms milliseconds have
1150passed. With no args, program will sleep for ms milliseconds. Returns the id
1151of the event handler created.
1152after cancel id|arg1 arg2 . . .
1153Cancel previous after command either by command or the id returned.
1154after idle [arg1 arg2 arg3 . . .]
1155Arrange for command (concat of args) to be run later when Tk is idle.
1156Returns the id of the event handler created.
1157after info [id]
1158Returns information on event handler id. With no id, returns a list of all
1159existing event handler ids.
1160auto_execok execFile
1161Returns full pathname if an executable file by the name execFile exists in
1162user’s PATH, empty string otherwise.
116326
1164Tcl/Tk Reference Guide
1165auto_load command
1166Attempts to load definition for cmd by searching $auto_pathand
1167$env(TCLLIBPATH)for a tclIndex file which will inform the interpreter
1168where it can find command’s definition.
1169auto_mkindex directory pattern [pattern . . . ]
1170Generate a tclIndex file from all files in directory that match glob patterns.
1171auto_reset
1172Destroys cached information used by auto_execok and auto_load.
1173bgerror message
1174User defined handler for background Tcl errors. Default exists for Tk which
1175posts a dialog box containing the error message with an application
1176configurable button (default is to save the stack trace to a file.) This behavior
1177can be redefined with the global options:
1178*ErrorDialog.function.text buttonText
1179*ErrorDialog.function.command tclProc
1180If selected, tclProc is called with one argument: the text of the stack trace. If
1181either of these options is set to the empty string, then the additional button
1182will not be displayed in the dialog.
1183catch script [varName]
1184Evaluate script and store results into varName. If there is an error, a
1185non-zero error code is returned and an error message stored in varName.
1186encoding convertfrom [encoding] data
1187Convert data to Unicode from the specified encoding. If encoding is not
1188specified, the current system encoding is used.
1189encoding convertto [encoding] string
1190Convert string from Unicode to the specified encoding. If encoding is not
1191specified, the current system encoding is used.
1192encoding names
1193Returns a list containing the names of all of the encodings that are currently
1194available.
1195encoding system [encoding]
1196Query or set the system encoding.
1197error message [info] [code]
1198Interrupt command interpretation with an error described in message. Global
1199variables errorInfoand errorCodewill be set to info and code.
1200eval arg [arg . . . ]
1201Returns result of evaluating the concatenation of args’s as a Tcl command.
1202expr arg [arg . . . ]
1203Returns result of evaluating the concatenation of arg’s as an operator
1204expression. See Operators for more info.
1205global varName [varName . . . ]
1206Declares given varName’s as global variables.
1207history add command [exec]
1208Adds command to history list, optionally executing it.
1209history change newValue [event]
1210Replaces value of event (default current) in history with newValue.
1211history clear
1212Erase the history list and reset event numbers.
1213history event [event]
1214Returns value of event (default -1) in history.
121527
1216Tcl/Tk Reference Guide
1217history info [count]
1218Returns event number and contents of the last count events.
1219history keep [count]
1220Set number of events to retain in history to count.
1221history nextid
1222Returns number for next event to be recorded in history.
1223history redo [event]
1224Re-evaluates event (default -1).
1225incr varName [increment]
1226Increment the integer value stored in varName by increment (default 1).
1227load file [pkgName [interp]]
1228Load binary code for pkgName (default derived from file name) from file
1229(dynamic lib) into interp. The initialization procedure for pkgName is then
1230called to incorporate it into interp.
1231load {} pkgName [interp]
1232Search for statically linked or previously loaded pkgName. The initialization
1233procedure for pkgName is then called to incorporate it into interp.
1234proc name args body
1235Create a new Tcl procedure (or replace existing one) called name where args
1236is a list of arguments and body Tcl commands to evaluate when invoked.
1237rename oldName newName
1238Rename command oldName so it is now called newName. If newName is the
1239empty string, command oldName is deleted.
1240set varName [value]
1241Store value in varName if given. Returns the current value of varName.
1242source fileName
1243Read file fileName (up to ’∧Z’ character) and evaluate its contents as a Tcl
1244script.
1245tcl_endOfWord str start
1246Return index of the first end-of-word location after start in str.
1247tcl_findLibrary basename version patch initScript enVarName varName
1248Search for directory containing extension script library (one script of which
1249is initScript) setting global varName with the result and sourcing initScript.
1250If varName is not preset, search for initScript in either directory
1251$env(envVarName) or (relative to directory containing info
1252nameofexecutable) ../lib/basenameversion, ../../lib/basenameversion,
1253../library, ../../library, ../../basename(version|patch)/library or
1254../../../basename(version|patch)/library.
1255tcl_startOfNextWord str start
1256Return index of the first start-of-word location after start in str.
1257tcl_startOfPreviousWord str start
1258Return index of the first start-of-word location before start in str.
1259tcl_wordBreakAfter str start
1260Return index of the first word boundary after start in str.
1261tcl_wordBreakBefore str start
1262Return index of the first word boundary before start in str.
1263time script [count]
1264Call interpreter count (default 1) times to evaluate script. Returns string of
1265the form “503 microseconds per iteration”.
126628
1267Tcl/Tk Reference Guide
1268trace add command procName opsList tclProc
1269Arrange for tclProc to be executed whenever command procName is
1270modified as specified by opsList, one or more of renameor delete.
1271When triggered, tclProc is called with three arguments:
1272tclProc oldName newName op
1273newName is empty for a deleteoperation.
1274trace add execution procName opsList tclProc
1275Arrange for tclProc to be executed whenever command procName is
1276modified as specified by opsList, one or more of enter, leave,
1277enterstepor leavestep. When triggered, tclProc is called with
1278arguments:
1279tclProc command [code result] op
1280command is the complete command being executed. For enterand
1281enterstep, execution can be prevented by deleting command. For leave
1282and leavestep, code is the result code and result is the result string.
1283trace add variable varName opsList tclProc
1284Arrange for tclProc to be executed whenever varName is accessed as
1285specified by opsList, one or more of array, unset, read or write.
1286When triggered, tclProc is called with three arguments:
1287tclProc name1 name2 op
1288Name1 and name2 give the name(s) for the variable being accessed: if a
1289scalar or if an entire array is being deleted and the trace was registered on
1290the overall array then name1 is the variable’s name and name2 is empty; if
1291the variable is an array element then name1 is the array name and name2 is
1292the index into the array. Op indicates what operation is being performed on
1293the variable as defined above.
1294trace info type name
1295Return list for each trace type (command, execution or variable) set on
1296procName. Each element of the list is the opsList and tclProc associated
1297with the trace.
1298trace remove type procName opsList tclProc
1299Remove the trace type (command, execution or variable) set on procName
1300for the operations opsList with tclProc.
1301trace variable varName ops tclProc
1302Obsolete. Same as trace add variable varName ops tclProc.
1303trace vdelete varName ops tclProc
1304Obsolete. Same as trace remove variable varName ops tclProc.
1305trace vinfo varName
1306Obsolete. Same as trace info variable varName.
1307unknown cmdName [arg arg . . . ]
1308Called when the Tcl interpreter encounters an undefined command name.
1309unset [-nocomplain] [- -] varName [varName . . . ]
1310Removes the given variables and arrays from scope. If -nocomplainis
1311specified, any possible errors are suppressed.
1312update [idletasks]
1313Handle pending events. If idletasksis specified, only those operations
1314normally deferred until the idle state are processed.
1315uplevel [level] arg [arg . . . ]
1316Evaluates concatenation of arg’s in the variable context indicated by level,
131729
1318Tcl/Tk Reference Guide
1319an integer that gives the distance up the calling stack. If level is preceded by
1320‘#’, then it gives the distance down the calling stack from the global level.
1321upvar [level] otherVar myVar [otherVar myVar . . . ]
1322Makes myVar in local scope equivalent to otherVar at context level (see
1323uplevel) so they share the same storage space.
1324vwait varName
1325Enter Tcl event loop until global variable varName is modified.
132630
1327Tcl/Tk Reference Guide
132819. Tk Shell
1329wish [arg . . . ]
1330wish fileName [arg . . . ]
1331Wish reads Tcl commands from its standard input or from file fileName and
1332evaluates them.
1333With no arguments or with a first argument that starts with ‘-’, wish runs
1334interactively, sourcing the file .wishrc (if it exists) before reading the standard
1335input. Otherwise, an initial argument fileName is the name of a file to source.
1336The name of the application, which is used for purposes such as send commands,
1337is taken from the -name option, from fileName, or from the command name by
1338which wish was invoked.
1339The class of the application, which is used for purposes such as specifying options
1340with a resource manager property or .Xdefaults file, is the same as its name except
1341that the first letter is capitalized.
1342The following command line options are recognized:
1343-colormap new
1344Use a new private colormap instead of the default screen colormap.
1345-displaydisplay
1346X11 display for main window.
1347-geometrygeometry
1348Initial geometry of main window.
1349-namename Title to be displayed for the main window, and the name of the
1350interpreter for send commands.
1351-sync Execute all X server commands synchronously.
1352-use id Embed the main window for the application in the window whose
1353identifier is id.
1354-visualvisual
1355Visual to use for the window.
1356-- All remaining arguments become the value of $argv.
135720. Tk Special Variables
1358geometry The value of the -geometry command line option.
1359tk_library Directory containing library of standard Tk scripts.
1360tk_patchLevel Integer specifying current patch level for Tk.
1361tk::Priv Array containing information private to standard Tk
1362scripts.
1363tk_strictMotif When non-zero, Tk tries to adhere to Motif look-and-feel
1364as closely as possible.
1365tk_textRedraw Set by text widgets when they have debugging turned on.
1366tk_textRelayout
1367tk_version Current version of Tk in major.minor form.
136821. General Tk Widget Information
1369All widget are created with
1370widget pathname [ option1 value1 [ option2 . . . ] ]
137131
1372Tcl/Tk Reference Guide
1373where widget is the Tcl command corresponding to the class of widget desired (eg.
1374button) and pathname is a string which will be used to identify the newly created
1375widget. In general, a widget name is the concatenation of its parent’s name
1376followed by a period (unless the parent is the root window ‘.’) and a string
1377containing no periods (eg. .mainframe.btnframe.btn1).
1378Widget configuration options may be passed in the creation command. Options
1379begin with a ‘-’ and are always followed by a value string. After creation, options
1380may be changed using the configure widget command
1381pathname configure option1 value1 [ option2 . . . ]
1382and queried using the cget command
1383pathname cget option
1384Some of the widget options which multiple widgets support are described here for
1385brevity. For options that take screen units, values are in pixels unless an optional
1386one letter suffix modifier is present — c (cm), i (inch), m (mm), or p (points).
1387-activebackgroundcolor
1388Background color of widget when it is active.
1389A color is any of the valid names for a color defined in the color database, or
1390a specification of the red, green and blue intensities in the form:
1391#RGB #RRGGBB #RRRGGGBBB #RRRRGGGGBBBB
1392Each R, G, or B represents a single hexadecimal digit. The four forms permit
1393colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values. When fewer
1394than 16 bits are provided for each color, they represent the most significant
1395bits of the color. For example, #3a7 is the same as #3000a0007000.
1396-activeborderwidthwidth
1397Width in screen units of widget border when it is active.
1398-activeforegroundcolor
1399Foreground color of widget when it is active.
1400-activestylestyle
1401The style in which to draw the active element. One of dotbox, none or
1402underline(default).
1403-anchoranchorPos
1404How information is positioned inside widget. Valid anchorPos values are n,
1405ne, e, se, s, sw, w, nw, and center.
1406-backgroundcolor
1407Background color of widget in normal state (Abbrev: -bg).
1408-bitmapbitmap
1409Bitmap to display in the widget (error, gray12, gray25,
1410gray50, gray75, hourglass, info, questhead,
1411question, warning, @filename).
1412-borderwidthwidth
1413Width in screen units of widget border in normal state (Abbrev: -bd).
1414-commandtclCommand
1415Tcl command to evaluate when widget is invoked.
1416-cursorcursor
1417Cursor to display when mouse pointer is in widget. Valid formats:
1418name [fgColor [bgColor]
1419Name of cursor from /usr/include/X11/cursorfont.h.
1420@sourceName maskName fgColor bgColor
1421Get source and mask bits from files sourceName and maskName.
142232
1423Tcl/Tk Reference Guide
1424@sourceName fgColor
1425Get source bits from file sourceName (background transparent).
1426-disabledbackgroundcolor
1427Background color of widget when it is disabled. Use default if color is the
1428empty string.
1429-disabledforegroundcolor
1430Foreground color of widget when it is disabled. Use default if color is the
1431empty string.
1432-exportselectionboolean
1433Whether or not a selection in the widget should also be the X selection.
1434-fontfont
1435Font to use when drawing text inside the widget.
1436-foregroundcolor
1437Foreground color of widget in normal state (Abbrev: -fg).
1438-heightheight|textChars
1439Height of widget. Units depend on widget.
1440-highlightbackgroundcolor
1441Color of the rectangle drawn around the widget when it does not have the
1442input focus.
1443-highlightcolorcolor
1444Color of the rectangle drawn around the widget when it has the input focus.
1445-highlightthicknesswidth
1446Width in screen units of highlight rectangle drawn around widget when it
1447has the input focus.
1448-imageimage
1449Image to display in the widget (see Images).
1450-insertbackgroundcolor
1451Color to use as background in the area covered by the insertion cursor.
1452-insertborderwidthwidth
1453Width in screen units of border to draw around the insertion cursor.
1454-insertofftimemilliseconds
1455Time the insertion cursor should remain “off” in each blink cycle.
1456-insertontimemilliseconds
1457Time the insertion cursor should remain “on” in each blink cycle.
1458-insertwidthwidth
1459Width in screen units of the insertion cursor.
1460-jumpboolean
1461Whether to notify scrollbars and scales connected to the widget to delay
1462updates until mouse button is released.
1463-justify left|center|right
1464How multiple lines line up with each other.
1465-orient horizontal|vertical
1466Which orientation widget should use in layout.
1467-padxwidth
1468Extra space in screen units to request for the widget in X-direction.
1469-padyheight
1470Extra space in screen units to request for the widget in Y-direction.
1471-readonlybackgroundcolor
1472Background color to use when the widget state is readonly. Use default if
1473color is the empty string.
147433
1475Tcl/Tk Reference Guide
1476-relief flat|groove|raised|ridge|sunken
14773-D effect desired for the widget’s border.
1478-repeatdelaymilliseconds
1479Time a button or key must be held down before it begins to auto-repeat.
1480-repeatintervalmilliseconds
1481Time between auto-repeats once action has begun.
1482-selectbackgroundcolor
1483Background color to use when displaying selected items.
1484-selectborderwidthwidth
1485Width in screen units of border to draw around selected items.
1486-selectforegroundcolor
1487Foreground color to use when displaying selected items.
1488-setgridboolean
1489Whether this widget controls the resizing grid for its toplevel window.
1490-statestate
1491Current state of widget: normal, disabled, active(for button-type
1492widgets), or readonly(for entry or spinbox widgets.)
1493-takefocusfocusType
1494If 0 or 1, signals that the widget should never or always take the focus. If
1495empty, Tk decides. Otherwise, evaluates focusType as script with the widget
1496name appended as argument. The return value of the script must be 0, 1 or
1497empty.
1498-textstring
1499Text to be displayed inside the widget.
1500-textvariablevariable
1501Variable which contains a text string to be displayed inside the widget.
1502-troughcolorcolor
1503Color to use for the rectangular trough areas in widget.
1504-underlineindex
1505Integer index of a character to underline in the widget.
1506-widthwidth|textChars
1507Width of widget. Units depend on widget.
1508-wraplengthlength
1509Maximum line length in screen units for word-wrapping.
1510-xscrollcommandcmdPrefix
1511Prefix for a command used to communicate with horizontal scrollbars.
1512-yscrollcommandcmdPrefix
1513Prefix for a command used to communicate with vertical scrollbars.
151422. Widget Scroll Commands
1515The Canvas, Listbox and Text widgets support the following scrolling commands.
1516The Entry and Spinbox widgets support the xview command and the scan
1517command with the y coordinate dropped.
1518widget scan mark x y
1519Records x and y as widget’s current view anchor.
1520widget scan dragto x y [gain]
1521Shift the view by gain (default 10) times the difference between the
1522coordinates x and y and the current view anchor coordinates.
152334
1524Tcl/Tk Reference Guide
1525widget xview
1526Return a two element list specifying the fraction of the horizontal span of the
1527widget at the left and right edges of the window.
1528widget xview moveto fraction
1529Adjust the view in the window so that fraction of the total width of the
1530widget is off-screen to the left.
1531widget xview scroll number units|pages
1532Shift the view by number one-tenths (unit) or nine-tenths (pages) the
1533window’s width in the horizontal direction.
1534widget yview
1535Return a two element list specifying the fraction of the vertical span of the
1536widget at the top and bottom edges of the window.
1537widget yview moveto fraction
1538Adjust the view in the window so that fraction of the total height of the
1539widget is off-screen to the top.
1540widget yview scroll number units|pages
1541Shift the view by number one-tenths (unit) or nine-tenths (pages) the
1542window’s height in the vertical direction.
1543The Text Widget also supports the following:
1544text yview [-pickplace] index
1545Changes view of widget’s window to make character at index visible. If
1546-pickplaceis specified, index will appear at the top of the window.
1547The Entry (xview only), Listbox and Spinbox (xview only) Widgets also support
1548the following:
1549widget xview index
1550Adjusts view so that character position index is at left edge.
1551widget yview index
1552Adjusts view so that element at index is at top of window.
155323. Entry Validation
1554The Entry and Spinbox widgets support entry validation with the use of the
1555-validate, -validatecommandand -invalidcommandoptions.
1556The validateCommand will be evaluated according to the -validatemode as
1557follows:
1558none No validation will occur.
1559focus Evaluate validateCommand when the entry receives or loses focus.
1560focusin Evaluate validateCommand when the entry receives focus.
1561focusout Evaluate validateCommand when the entry loses focus.
1562key Evaluate validateCommand when the entry is edited.
1563all Evaluate validateCommand for all above conditions.
1564It is possible to perform percent substitutions on validateCommand and
1565invalidCommand, just as you would in a bind script. The following substitutions
1566are recognized:
1567%d Type of action: 1 for insert, 0 for delete, or -1 for focus, forced or
1568textvariable validation.
1569%i Index of char string to be inserted/deleted if present, otherwise -1.
1570%P The value of the entry should edition occur.
1571%s The current value of entry before edition.
157235
1573Tcl/Tk Reference Guide
1574%S The text string being inserted/deleted, if any.
1575%v The type of validation currently set.
1576%V The type of validation that triggered the callback: key, focusin,
1577focusoutor forced.
1578%W The name of the entry widget.
157924. The Canvas Widget
1580Canvas Options
1581-background -insertbackground -selectborderwidth
1582-borderwidth -insertborderwidth -selectforeground
1583-cursor -insertofftime -takefocus
1584-height -insertontime -width
1585-highlightbackground -insertwidth -xscrollcommand
1586-highlightcolor -relief -yscrollcommand
1587-highlightthickness -selectbackground
1588-closeenoughfloat
1589How close the mouse cursor must be to an item before it is considered to be
1590“inside” the item.
1591-confineboolean
1592Whether it is allowable to set the canvas’s view outside the scroll region.
1593-scrollregioncorners
1594List of four coordinates describing the left, top, right, and bottom of a
1595rectangular scrolling region.
1596-xscrollincrementdistance
1597Specifies the increment for horizontal scrolling in screen units.
1598-yscrollincrementdistance
1599Specifies the increment for vertical scrolling in screen units.
1600Coordinates and distances are specified in screen units which are floating point
1601numbers optionally suffixed with a scale letter. Examples: 5 (pixel), 2.2i (inch),
16024.1c (cm), 3m (mm), 21p (pts, 1/72 inch)
1603Larger y-coordinates refer to points lower on the screen.
1604Larger x-coordinates refer to points farther to the right.
1605Coordinate lists:
1606The list of coordinates may be specified either as a single Tcl list, or
1607as a sequence of discrete elements.
1608Tag or id: An id is the integer assigned when an item is created while a tag is
1609any non-integer form. Tags may be associated with multiple items. A
1610tagOrId may be a logical expression using operators ’&&’, ’||’, ’∧’,
1611’!’ and parenthesized subexpressions.
1612Tags: current
1613Character indices:
1614charIndex, end, insert, sel.first, sel.last, @x,y
1615Line/polygon indices:
1616evenNumber, end, insert, sel.first, sel.last, @x,y
1617Dash patterns:
161836
1619Tcl/Tk Reference Guide
1620intList Each element represents the number of pixels of a line segment. The
1621odd segments are drawn using the outlinecolor, the others are
1622transparent.
1623charString Only the characters [.,-_ ] are supported. The space can be used to
1624enlarge the space between other line elements. Equivalence of
1625characters to intList:
1626’.’ 2 4
1627’,’ 4 4
1628’-’ 6 4
1629’_’ 8 4
1630’[.,-_] ’ Enlarge 2nd number by factor of 2
1631Canvas Commands
1632canvas addtag tag searchSpec [arg arg . . . ]
1633Add tag to the list of tags associated with each item that satisfy searchSpec.
1634See Canvas Search Specs below.
1635canvas bbox tagOrId [tagOrId . . . ]
1636Returns a list with four elements giving an approximate bounding box for all
1637the items named by the tagOrId arguments.
1638canvas bind tagOrId [sequence [command]]
1639Associates command to be invoked on events specified with sequence with
1640the items given by tagOrId.
1641canvas canvasx screenx [gridspacing]
1642Returns the canvas x-coordinate that is displayed at screen x-coordinate
1643screenx possibly rounding to nearest multiple of gridspacing units.
1644canvas canvasy screeny [gridspacing]
1645Returns the canvas x-coordinate that is displayed at screen y-coordinate
1646screeny possibly rounding to nearest multiple of gridspacing units.
1647canvas coords tagOrId [x0 y0 . . . ]
1648canvas coords tagOrId [coordList]
1649Query or modify the coordinates that define an item.
1650canvas create type x y [x y . . . ] [option value . . . ]
1651canvas create type coordList [option value . . . ]
1652Create a new item of type type at specified coordinates and with list options.
1653canvas dchars tagOrId first [last]
1654For items given by tagOrId, delete the characters in the range given by first
1655and last (defaults to first), inclusive.
1656canvas delete [tagOrId . . . ]
1657Delete each of the items given by each tagOrId.
1658canvas dtag tagOrId [tagToDelete]
1659Remove tag tagToDelete from the taglist of items given by tagOrId.
1660canvas find searchSpec [arg arg . . . ]
1661Returns a list of the items that satisfy the specification searchSpec. See
1662Canvas Search Specs below.
1663canvas focus tagOrId
1664Set the focus to the first textual item given by tagOrId.
1665canvas gettags tagOrId
1666Return a list of the tags associated with the first item given by tagOrId.
166737
1668Tcl/Tk Reference Guide
1669canvas icursor tagOrId index
1670Set the insertion cursor for the item(s) given by tagOrId to just before the
1671character position index .
1672canvas index tagOrId index
1673Returns a decimal string giving the numerical index within tagOrId
1674corresponding to character position index.
1675canvas insert tagOrId beforeThis string
1676Insert string just before character position beforeThis in items given by
1677tagOrId that support textual insertion.
1678canvas itemcget tagOrId option
1679Returns the value option for the item given by tagOrId.
1680canvas itemconfigure tagOrId [option value . . . ]
1681Modifies item-specific options for the items given by tagOrId.
1682canvas lower tagOrId [belowThis]
1683Move the items given by tagOrId to a new position in the display list just
1684before the first item given by belowThis.
1685canvas move tagOrId xAmount yAmount
1686Move the items given by tagOrId in the canvas coordinate space by adding
1687xAmount and yAmount to each items x and y coordinates, respectively.
1688canvas postscript [option value . . . ]
1689Generate a Encapsulated Postscript representation for part or all of the
1690canvas. See Canvas Postscript Options below.
1691canvas raise tagOrId [aboveThis]
1692Move the items given by tagOrId to a new position in the display list just
1693after the first item given by aboveThis.
1694canvas scale tagOrId xOrigin yOrigin xScale yScale
1695Re-scale items given by tagOrId in canvas coordinate space to change the
1696distance from xOrigin,yOrigin by a factor of xScale,yScale respectively.
1697canvas scan args
1698See Widget Scroll Commands above.
1699canvas select adjust tagOrId index
1700Adjust nearest end of current selection in tagOrId to be at index and set the
1701other end to be the new selection anchor.
1702canvas select clear
1703Clear the selection if it is in the widget.
1704canvas select from tagOrId index
1705Set the selection anchor in tagOrId to just before the character at index.
1706canvas select item
1707Return id of the selected item. Returns a empty string if there is none.
1708canvas select to tagOrId index
1709Set the selection to extend between index and anchor point in tagOrId.
1710canvas type tagOrId
1711Returns the type of the first item given by tagOrId.
1712canvas xview|yview args
1713See Widget Scroll Commands above.
1714Canvas Search Specifications
1715above tagOrId
1716Selects the item just after the one given by tagOrId in the display list.
171738
1718Tcl/Tk Reference Guide
1719all Selects all the items in the canvas.
1720below tagOrId
1721Selects the item just before the one given by tagOrId in the display list.
1722closest x y [halo] [start]
1723Select the topmost, closest item to @x,y that is below start in the display list.
1724Any item closer than halo to the point is considered to overlap it.
1725enclosed x1 y1 x2 y2
1726Selects all the items completely enclosed within x1 y1 x2 y2.
1727overlapping x1 y1 x2 y2
1728Selects all the items that overlap or are enclosed within x1 y1 x2 y2.
1729withtag tagOrId
1730Selects all the items given by tagOrId.
1731Common Item Options
1732-dashpattern
1733Dash pattern for the normal state of an item. Default is a solid line.
1734-activedashpattern
1735Dash pattern for the active state of an item. Default is a solid line.
1736-disableddashpattern
1737Dash pattern for the disabled state of an item. Default is a solid line.
1738-dashoffsetoffset
1739Starting offset in pixels into the pattern provided by the -dash option.
1740-fillcolor
1741Color used to fill item’s area in its normal state.
1742-activefillcolor
1743Color used to fill item’s area in its active state.
1744-disabledfillcolor
1745Color used to fill item’s area in its disabled state.
1746-outlinecolor
1747Color used to draw the item’s outline in its normal state.
1748-activeoutlinecolor
1749Color used to draw the item’s outline in its active state.
1750-disabledoutlinecolor
1751Color used to draw the item’s outline in its disabled state.
1752-offsetoffset
1753The stipple offset of the form x,y or side where side can be n, ne, e, se, s,
1754sw, w, nw, or center.
1755-outlinestipplebitmap
1756Stipple pattern used to draw the item’s outline in its normal state.
1757-activeoutlinestipplebitmap
1758Stipple pattern used to draw the item’s outline in its active state.
1759-disabledoutlinestipplebitmap
1760Stipple pattern used to draw the item’s outline in its disabled state.
1761-stipplebitmap
1762Stipple pattern used to fill the the item in its normal state.
1763-activestipplebitmap
1764Stipple pattern used to fill the the item in its active state.
1765-disabledstipplebitmap
1766Stipple pattern used to fill the the item in its disabled state.
176739
1768Tcl/Tk Reference Guide
1769-statestate
1770Override the canvas widget’s global state option.
1771-tagstagList
1772Replace any existing tags with tagList which may be empty.
1773-widthoutlineWidth
1774Width of the outline drawn around the item’s region in its normal state.
1775-activewidthoutlineWidth
1776Width of the outline drawn around the item’s region in its active state.
1777-disabledwidthoutlineWidth
1778Width of the outline drawn around the item’s region in its disabled state.
1779Canvas Item Types
1780canvas create arc x1 y1 x2 y2 [option value . . . ]
1781canvas create arc coordList [option value . . . ]
1782-activedashpattern -disabledoutlinecolor
1783-activefillcolor -disabledstipplebitmap
1784-activeoutlinestipplebitmap -disabledwidthoutlineWidth
1785-activeoutlinecolor -fill color
1786-activestipplebitmap -offsetoffset
1787-activewidthoutlineWidth -outlinestipplebitmap
1788-dashoffsetoffset -outlinecolor
1789-dashpattern -statestate
1790-disableddashpattern -stipplebitmap
1791-disabledfillcolor -tags tagList
1792-disabledoutlinestipplebitmap -widthoutlineWidth
1793-extentdegrees
1794Size of the angular range occupied by arc measured counter-clockwise from
1795the start.
1796-startdegrees
1797Starting angle measured from 3-o’clock position.
1798-style pieslice|chord|arc
1799How to “complete” the region of the arc.
1800canvas create bitmap x y [option value . . . ]
1801canvas create bitmap coordList [option value . . . ]
1802-statestate -tags tagslist
1803-anchoranchorPos
1804How to position the bitmap relative to the positioning point for the item: n,
1805ne, e, se, s, sw, w, nw, or center(default).
1806-backgroundcolor
1807Color to use for the bitmap’s ’0’ valued pixels in its normal state.
1808-activebackgroundbitmap
1809Color to use for the bitmap’s ’0’ valued pixels in its active state.
1810-disabledbackgroundbitmap
1811Color to use for the bitmap’s ’0’ valued pixels in its disabled state.
1812-bitmapbitmap
1813Bitmap to display in the item in its normal state.
1814-activebitmapbitmap
1815Bitmap to display in the item in its active state.
181640
1817Tcl/Tk Reference Guide
1818-disabledbitmapbitmap
1819Bitmap to display in the item in its disabled state.
1820-foregroundcolor
1821Color to use for the bitmap’s ’1’ valued pixels in its normal state.
1822-activeforegroundbitmap
1823Color to use for the bitmap’s ’1’ valued pixels in its active state.
1824-disabledforegroundbitmap
1825Color to use for the bitmap’s ’1’ valued pixels in its disabled state.
1826canvas create image x y [option value . . . ]
1827canvas create image coordList [option value . . . ]
1828-statestate -tags tagslist
1829-anchoranchorPos
1830How to position the image relative to the positioning point for the item: n,
1831ne, e, se, s, sw, w, nw, or center(default).
1832-imagename
1833Name of the image to display in its normal state.
1834-activeimagename
1835Name of the image to display in its active state.
1836-disabledimagename
1837Name of the image to display in its disabled state.
1838canvas create line x1 y1 . . . xN yN [option value . . . ]
1839canvas create line coordList [option value . . . ]
1840-activedashpattern -disabledstipplebitmap
1841-activefillcolor -disabledwidthoutlineWidth
1842-activestipplebitmap -fill color
1843-activewidthoutlineWidth -statestate
1844-dashoffsetoffset -stipplebitmap
1845-dashpattern -tags tagList
1846-disableddashpattern -widthoutlineWidth
1847-disabledfillcolor
1848-arrow none|first|last|both
1849Specify on which ends of the line to draw arrows.
1850-arrowshapeshape
1851Three element list which describes shape of arrow.
1852-capstyle butt|projecting|round
1853How to draw caps at endpoints of the line. One of butt (default),
1854projectingor round.
1855-joinstyle bevel|miter|round
1856How joints are to be drawn at vertices. One of bevel, miter (default), or
1857round.
1858-smoothsmoothMethod
1859Should the line be drawn as a set of parabolic splines (true or false), or
1860as smoothMethod? The only built-in method is bezier.
1861-splinestepsnumber
1862Degree of smoothness desired for curves.
1863canvas create oval x1 y1 x2 y2 [option value . . . ]
1864canvas create oval coordList [option value . . . ]
1865-activedashpattern -disabledoutlinecolor
186641
1867Tcl/Tk Reference Guide
1868-activefillcolor -disabledstipplebitmap
1869-activeoutlinestipplebitmap -disabledwidthoutlineWidth
1870-activeoutlinecolor -fill color
1871-activestipplebitmap -offsetoffset
1872-activewidthoutlineWidth -outlinestipplebitmap
1873-dashoffsetoffset -outlinecolor
1874-dashpattern -statestate
1875-disableddashpattern -stipplebitmap
1876-disabledfillcolor -tags tagList
1877-disabledoutlinestipplebitmap -widthoutlineWidth
1878canvas create polygon x1 y1 . . . xN yN [option value . . . ]
1879canvas create polygon coordList [option value . . . ]
1880-activedashpattern -disabledoutlinecolor
1881-activefillcolor -disabledstipplebitmap
1882-activeoutlinestipplebitmap -disabledwidthoutlineWidth
1883-activeoutlinecolor -fill color
1884-activestipplebitmap -offsetoffset
1885-activewidthoutlineWidth -outlinestipplebitmap
1886-dashoffsetoffset -outlinecolor
1887-dashpattern -statestate
1888-disableddashpattern -stipplebitmap
1889-disabledfillcolor -tags tagList
1890-disabledoutlinestipplebitmap -widthoutlineWidth
1891-joinstylestyle
1892How joints are to be drawn at vertices. One of bevel, miter (default), or
1893round.
1894-smoothboolean
1895Should the polygon be drawn as a set of parabolic splines.
1896-splinestepsnumber
1897Degree of smoothness desired for curved perimeter.
1898canvas create rectangle x1 y1 x2 y2 [option value . . . ]
1899canvas create rectangle coordList [option value . . . ]
1900-activedashpattern -disabledoutlinecolor
1901-activefillcolor -disabledstipplebitmap
1902-activeoutlinestipplebitmap -disabledwidthoutlineWidth
1903-activeoutlinecolor -fill color
1904-activestipplebitmap -offsetoffset
1905-activewidthoutlineWidth -outlinestipplebitmap
1906-dashoffsetoffset -outlinecolor
1907-dashpattern -statestate
1908-disableddashpattern -stipplebitmap
1909-disabledfillcolor -tags tagList
1910-disabledoutlinestipplebitmap -widthoutlineWidth
1911canvas create text x y [option value . . . ]
1912canvas create text coordList [option value . . . ]
1913-activefillcolor -fill color
1914-activestipplebitmap -statestate
1915-disabledfillcolor -stipplebitmap
1916-disabledstipplebitmap -tags tagList
191742
1918Tcl/Tk Reference Guide
1919-anchoranchorPos
1920How to position the text relative to the positioning point for the item: n, ne,
1921e, se, s, sw, w, nw, or center(default).
1922-fontfontName
1923Font to use for the text item.
1924-justify left|right|center
1925How to justify text within its bounding region. One of left (default),
1926right or center.
1927-textstring
1928Characters to be displayed in the text item.
1929-widthlineLength
1930Maximum line length for the text. If zero, break only on \n.
1931canvas create window x y [option value . . . ]
1932canvas create window coordList [option value . . . ]
1933-statestate -tags tagList
1934-anchoranchorPos How to position the text relative to the positioning point
1935for the item: n, ne, e, se, s, sw, w, nw, or center
1936(default).
1937-heightheight Height in screen units to assign item’s window.
1938-widthwidth Width in screen units to assign item’s window.
1939-windowpathName Window to associate with item.
1940Canvas Postscript Options
1941-channelchannelId
1942Specifies the name of an opened channel in which to write the Postscript. If
1943not specified, the Postscript is returned as the result of the command.
1944-colormapvarName
1945Specifies a color mapping to use where varName is an array variable whose
1946elements specify Postscript code to set a particular color value.
1947-colormode color|grey|mono
1948Specifies how to output color information.
1949-filefileName
1950Specifies the name of the file in which to write the Postscript. If not
1951specified, the Postscript is returned as the result of the command.
1952-fontmapvarName
1953Specifies a font mapping to use where varName is an array variable whose
1954elements specify the Postscript font and size to use as a two element list.
1955-heightsize
1956Specifies the height of the area of the canvas to print. Defaults to the height
1957of the canvas window
1958-pageanchoranchor
1959Specifies which point of the printed area should be appear over the
1960positioning point on the page. Defaults to center.
1961-pageheightsize
1962Specifies that the Postscript should be scaled in both x and y so that the
1963printed area is size high on the Postscript page.
1964-pagewidthsize
1965Specifies that the Postscript should be scaled in both x and y so that the
1966printed area is size wide on the Postscript page.
196743
1968Tcl/Tk Reference Guide
1969-pagexposition
1970Set the x-coordinate of the positioning point on the page to position.
1971-pageyposition
1972Set the y-coordinate of the positioning point on the page to position.
1973-rotateboolean
1974Whether the printed area is to be rotated 90 degrees. (“landscape”).
1975-widthsize
1976Specifies the width of the area of the canvas to print. Defaults to the width of
1977the canvas window
1978-x position
1979Set the x-coordinate of the left edge of canvas area to print.
1980-y position
1981Set the y-coordinate of the top edge of canvas area to print.
1982Tkspline 0.4 Package
1983
1984An additional smoothing method for canvas line and polygon items. Package
1985command is:
1986package require Tkspline
1987canvas create line . . . -smooth spline. . .
1988canvas create polygon . . . -smooth spline. . .
1989Spline smoothing requires 3n + 1 points, where n is the number of spline
1990segments.
1991The curves generated with the standard -smooth trueoption have the following
1992properties:
1993• the curve is always tangential to a straight line between consecutive points.
1994• the curve is only guaranteed to intersect the first and last points of lines.
1995• the curve is not guaranteed to intersect any points of polygons.
1996With -smooth splinethe curves generated have the following different
1997properties:
1998• the curve is guaranteed to intersect the first point, and every third point after
1999that.
2000• each segment of the curve shares endpoints with the adjacent segments, but
2001is otherwise independant of them.
2002• the curve is guaranteed to be tangential to a line between n and n + 1 at
2003point n, and also to a line between n + 2 and n + 3 at point n + 3.
2004• the curve is not guaranteed to be smooth at the junctions between segments
2005unless the shared point and the points either side of it are on a straight line.
200625. The Entry Widget
2007Entry Widget Options
2008-background -highlightcolor -relief
2009-borderwidth -highlightthickness -selectbackground
2010-cursor -insertbackground -selectborderwidth
2011-disabledbackground -insertborderwidth -selectforeground
201244
2013Tcl/Tk Reference Guide
2014-disabledforeground -insertofftime -state
2015-exportselection -insertontime -takefocus
2016-font -insertwidth -textvariable
2017-foreground -justify -width
2018-highlightbackground -readonlybackground -xscrollcommand
2019-invalidcommandtclCommand
2020Script to evaluate when validateCommand returns false. (Abbrev:
2021-invcmd).
2022-showchar
2023Show char rather than actual characters for each character in entry.
2024-validatemode
2025Mode in which validation should operate: none (default), focus,
2026focusin, focusout, key, or all. See Validation above.
2027-validatecommandtclCommand
2028Evaluate tclCommand, which must return a boolean, to validate the input
2029into the entry widget. If it returns false then the addition is rejected and will
2030not occur, and the invalidCommand will be evaluated. (Abbrev: -vcmd).
2031Entry Indices: number, anchor, end, insert, sel.first,
2032sel.last,@x-coord
2033Entry Widget Commands
2034entry bbox index
2035Returns bounding box of character given by index.
2036entry delete first [last]
2037Delete characters from first through character just before last.
2038entry get
2039Returns the entry’s string.
2040entry icursor index
2041Display insertion cursor just before character at index.
2042entry index index
2043Returns the numerical index corresponding to index.
2044entry insert index string
2045Insert string just before character at index.
2046entry scan option args
2047See Widget Scroll Commands above.
2048entry selection adjust index
2049Adjust nearest end of current selection to be at index and set the other end to
2050the anchor point.
2051entry selection clear
2052Clear the selection if currently in the widget.
2053entry selection from index
2054Set the anchor point to be at index.
2055entry selection present
2056Returns 1 is any characters are selected, 0 otherwise.
2057entry selection range start end
2058Select the characters from start through character just before end.
2059entry selection to index
2060Set the selection to extend between index and anchor point.
206145
2062Tcl/Tk Reference Guide
2063entry validate
2064Force an evaluation of validateCommand.
2065entry xview args
2066See Widget Scroll Commands above.
206726. The Listbox Widget
2068Listbox Widget Options
2069-activestyle -height -selectforeground
2070-background -highlightbackground -setgrid
2071-borderwidth -highlightcolor -state
2072-cursor -highlightthickness -takefocus
2073-disabledforeground -relief -width
2074-exportselection -selectbackground -xscrollcommand
2075-font -selectborderwidth -yscrollcommand
2076-foreground
2077-listvariable Name of a variable, the value of which is a list to be
2078displayed inside the widget.
2079-selectmodemode One of single, browse(default), multipleor
2080extended
2081Listbox Indices: number (starts at 0), active, anchor, end, @x,y
2082Listbox Item Options
2083-background -selectbackground -selectforeground
2084-foreground
2085Listbox Widget Commands
2086listbox activate index
2087Sets the active element to index.
2088listbox bbox index
2089Returns a list {x y width height} bounding element at index.
2090listbox curselection
2091Returns list of indices of all elements currently selected.
2092listbox delete index1 [index2]
2093Delete range of elements from index1 to index2 (defaults to index1).
2094listbox get index1 [index2]
2095Return as a list contents of elements from index1 to index2.
2096listbox index index
2097Returns position index in number notation.
2098listbox insert index [element . . . ]
2099Insert specified elements just before element at index.
2100listbox itemcget index option
2101Returns the value option for the item given by index.
2102listbox itemconfigure index [option value] . . .
2103Query or Modify item-specific options for the items given by option.
2104listbox nearest y
2105Return index of element nearest to y-coordinate.
210646
2107Tcl/Tk Reference Guide
2108listbox scan args
2109See Widget Scroll Commands above.
2110listbox see index
2111Adjust the view in window so element at index is completely visible.
2112listbox selection anchor index
2113Set the selection anchor to element at index.
2114listbox selection clear first [last]
2115De-select elements between first and last inclusive.
2116listbox selection includes index
2117Returns 1 if element at index is selected, 0 otherwise.
2118listbox selection set first [last]
2119Add all elements between first and last inclusive to selection.
2120listbox size
2121Returns number of elements in listbox.
2122listbox xview|yview args
2123See Widget Scroll Commands above.
212427. The Menu Widget
2125Menu Widget Options
2126-activebackground -borderwidth -foreground
2127-activeborderwidth -cursor -relief
2128-activeforeground -disabledforeground -takefocus
2129-background -font
2130-postcommandtclCommand
2131Specify Tcl command to invoke immediately before the menu is posted.
2132-selectcolorcolor
2133Specifies indicator color for checkbutton and radiobutton entries.
2134-tearoffboolean
2135Whether to include a tear-off entry at top of menu.
2136-tearoffcommandtclCmd
2137Specifies command to be run when menu is torn off. The name of the menu
2138and the new torn-off window will be appended on invocation.
2139-titlestring
2140Uses string for title of window used when the menu is torn off.
2141-typetype
2142Used at creation where type is one of menubar, tearoff, or normal.
2143Entry Types: cascade, checkbutton, command, radiobutton,
2144separator
2145Menu Indices: number, end, active, last, none, @y-coord,
2146matchPattern
2147Menu Widget Commands
2148menu activate index
2149Change state of entry at index to be sole active entry in menu.
2150menu add type [option value . . . ]
2151Add new entry of type type to bottom of menu. See below for options.
215247
2153Tcl/Tk Reference Guide
2154menu clone newMenuName [cloneType]
2155Clones menu as a new menu newMenuName of type cloneType (see -type).
2156menu delete index1 [index2]
2157Delete all entries between index1 and index2 inclusive.
2158menu entrycget index option
2159Return current value of option for entry at index.
2160menu entryconfigure index [option value . . . ]
2161Set option values for entry at index.
2162menu index index
2163Returns the numerical index corresponding to index.
2164menu insert index type [option value . . . ]
2165Same as add but inserts new entry just before entry at index.
2166menu invoke index
2167Invoke the action of the menu entry at index.
2168menu post x y
2169Display menu on screen at root-window coordinates given by x y.
2170menu postcascade index
2171Post sub-menu associated with cascade entry at index.
2172menu type index
2173Returns type of menu entry at index.
2174menu unpost
2175Unmap window so it is no longer displayed.
2176menu yposition index
2177Returns the y-coordinate within the menu window of the topmost pixel in
2178the entry specified by index.
2179Menu Entry Options
2180The following options work for all cascade, checkbutton, command, and
2181radiobutton entries unless otherwise specified.
2182-activebackground -bitmap -image
2183-activeforeground -font -state
2184-background -foreground -underline
2185-acceleratorstring
2186Specifies string to display at right side of menu entry.
2187-columnbreakvalue
2188When value is 1, entry appears at top of a new column in menu.
2189-commandtclCommand
2190TCL command to evaluate when entry is invoked.
2191-compoundhow
2192Should both image and text be displayed, and if so, how the image is placed
2193relative to the text. The value how is one of bottom, center, left,
2194none (default), right or top.
2195-hidemarginvalue
2196When value is 1, the standard margins are not drawn around entry.
2197-indicatoronboolean
2198Whether indictor for checkbutton or radiobutton entry should be displayed.
2199-labelstring
2200Textual string to display on left side of menu entry.
220148
2202Tcl/Tk Reference Guide
2203-menupathName
2204Pathname to a menu to post when cascade entry is active.
2205-offvaluevalue
2206Value to store in checkbutton entry’s associated variable when de-selected.
2207-onvaluevalue
2208Value to store in checkbutton entry’s associated variable when selected.
2209-selectcolorcolor
2210Color for indicator in checkbutton and radiobutton entries.
2211-selectimageimage
2212Image to draw in indicator for checkbutton and radiobutton entries.
2213-valuevalue
2214Value to store in radiobutton entry’s associated variable when selected.
2215-variablevariable
2216Name of global variable to set when checkbutton or radiobutton is selected.
221728. The Text Widget
2218Text Widget Options
2219-background -highlightthickness -selectbackground
2220-borderwidth -insertbackground -selectborderwidth
2221-cursor -insertborderwidth -selectforeground
2222-exportselection -insertofftime -setgrid
2223-font -insertontime -state
2224-foreground -insertwidth -takefocus
2225-height -padx -width
2226-highlightbackground -pady -xscrollcommand
2227-highlightcolor -relief -yscrollcommand
2228-autoseparatorsboolean Should separators be automatically inserted in the
2229undo stack.
2230-maxundointeger Maximum compound undo actions.
2231-spacing1size Space in screen units above paragraphs.
2232-spacing2size Space in screen units between paragraph lines.
2233-spacing3size Space in screen units below paragraphs.
2234-tabstabList
2235Set of tab stops as a list of screen distances giving their positions. Each stop
2236may be followed by one of left, right, center, or numeric.
2237-undoboolean Should undo mechanism be enabled.
2238-wrap none|char|word How to wrap lines.
2239Text Indices
2240Syntax: base [modifier . . . ]
2241Base: line.char, @x,y, end, mark, tag.first, tag.last, pathName
2242(embedded window), imageName (embedded image)
2243Modifier: ± count chars, ± count lines, linestart, lineend,
2244wordstart, wordend
2245Ranges: Ranges include all characters from the start index up to but not
2246including the character at the stop index.
224749
2248Tcl/Tk Reference Guide
2249Text Tag Options
2250-background -justify -spacing2
2251-borderwidth -relief -spacing3
2252-font -spacing1 -wrap
2253-foreground
2254-bgstipplebitmap Stipple pattern for background.
2255-elideboolean Whether the data should be elided (not displayed and
2256takes no space.)
2257-fgstipplebitmap Stipple pattern for foreground.
2258-lmargin1size Left margin of first line of a paragraph.
2259-lmargin2size Left margin of wrapped lines of a paragraph.
2260-offsetsize Offset of baseline from normal baseline.
2261-overstrikeboolean Whether to overstrike text.
2262-rmarginsize Right margin of all lines.
2263-tabstabList Set of tab stops (see -tabsabove).
2264-underlineboolean Whether to underline text.
2265Text Embedded Window Options
2266-align top|center|bottom|baseline
2267How window is vertically aligned with its line.
2268-createtclCommand
2269Script to create and return window pathname if no -windowoption is
2270given.
2271-padxwidth
2272Extra space in screen units to leave on the left and right side of window.
2273-padyheight
2274Extra space in screen units to leave on the top and bottom of window.
2275-stretchboolean
2276Whether window should be stretched vertically to fill line.
2277-windowpathName
2278Name of window to display.
2279Text Embedded Image Options
2280-align top|center|bottom|baseline
2281Where image is displayed on the line.
2282-imageimage
2283Specifies Tk image to use for embedded image.
2284-nameimageName
2285Specifies name which may be used to reference the embedded image.
2286-padxwidth
2287Extra space in screen units to leave on the left and right side of image.
2288-padyheight
2289Extra space in screen units to leave on the top and bottom of image.
229050
2291Tcl/Tk Reference Guide
2292Text Widget Commands
2293text bbox index
2294Returns a list {x y width height} bounding character at index.
2295text compare index1 op index2
2296Compares indices index1 and index2 according to relational operator op.
2297text debug boolean
2298Turn on/off debugging and internal consistency checks in the B-tree code
2299associated with text widgets.
2300text delete index1 [index2 . . . ]
2301Delete range of given text range.
2302text dlineinfo index
2303Returns a list {x y width height baseline} describing the screen area taken by
2304display line at index.
2305text dump [switches] index1 [index2]
2306Returns detailed info on text widget contents in given text range. Switches
2307include -all, -image, -mark, -tag, -text, -windowfor specifying
2308type of info returned. The switch -commandcommand exists to invoke a
2309procedure on each element type in the range.
2310text edit modified [boolean]
2311Query or set the modified flag.
2312text edit redo
2313Reapply last undone edits provided no other edits were done since then.
2314text edit reset
2315Clears the undo and redo stacks.
2316text edit separator
2317Inserts a separator (boundary) on the undo stack.
2318text edit undo
2319Undoes the last edit action. An edit action is defined as all the insert and
2320delete commands that are recorded on the undo stack between two
2321separators.
2322text get index1 [index2 . . . ]
2323Returns characters in given range. With multiple indices, a list is returned.
2324text image cget index option
2325Return current value of option for embedded image at index.
2326text image configure index [option [value [option value . . . ]]]
2327Modifies embedded image-specific options for the image at index.
2328text image create index [option value . . . ]
2329Create a new embedded image at position index with specified options.
2330text image names
2331Returns list of names of all images embedded in text widget.
2332text index index
2333Returns position index in line.char notation.
2334text insert index [string [tagList string tagList . . . ]]
2335Insert string into text at index applying tags from tagList.
2336text mark gravity markName [left|right]
2337Returns (or sets) which adjacent character a mark is attached to.
2338text mark names
2339Returns a list of the names of all marks currently set.
234051
2341Tcl/Tk Reference Guide
2342text mark next | previous index
2343Return name of next/previous mark at or after/before index.
2344text mark set markName index
2345Set mark markName to position just before character at index.
2346text mark unset markName [markName . . . ]
2347Remove each mark specified so they are no longer usable as indices.
2348text scan args
2349See Widget Scroll Commands above.
2350text search [switches] pattern index [stopIndex]
2351Returns index of first character matching pattern in text range index to
2352stopIndex. Switches: -forwards, -backwards, -exact, -regexp,
2353-countvar, -nocase, -elide
2354text see index
2355Adjust the view in window so character at index is completely visible.
2356text tag add tagName index1 [index2 . . . ]
2357Apply tag tagName to characters in given range.
2358text tag bind tagName [sequence [tclCommand]]
2359Arrange for tclCommand to be run whenever event sequence occurs for a
2360character with tag tagName.
2361text tag cget tagName option
2362Return current value of option for tag tagName.
2363text tag configure tagName [option [value [option value . . . ]]]
2364Modifies tag-specific options for the tag tagName.
2365text tag delete tagName [tagName . . . ]
2366Delete all tag information for given tags.
2367text tag lower tagName [belowThis]
2368Change priority of tag tagName so it is just below tag belowThis.
2369text tag names [index]
2370Returns a list of the names of all tags associated with character at index. If
2371index is not given, returns list of all tags defined in widget.
2372text tag nextrange tagName index1 [index2]
2373Searches character range index1 to index2 (default end) for the first region
2374tagged with tagName. Returns character range of region found.
2375text tag prevrange tagName index1 [index2]
2376Like nextrange but searches backwards from index1 to index2 (default 1.0).
2377text tag raise tagName [aboveThis]
2378Change priority of tag tagName so it is just above tag aboveThis.
2379text tag ranges tagName
2380Returns a list describing all character ranges tagged with tagName.
2381text tag remove tagName index1 [index2 . . . ]
2382Remove tag tagName for all characters in range index1 to index2.
2383text window cget index option
2384Return current value of option for embedded window at index.
2385text window configure index [option [value [option value . . . ]]]
2386Modifies embedded window-specific options for the window at index.
2387text window create index [option value . . . ]
2388Create a new embedded window at position index with specified options.
2389text window names
2390Returns list of names of all windows embedded in text widget.
239152
2392Tcl/Tk Reference Guide
2393text xview|yview args
2394See Widget Scroll Commands above.
239529. Other Standard Widgets
2396Button
2397-activebackground -foreground -repeatdelay
2398-activeforeground -height -repeatinterval
2399-anchor -highlightbackground -state
2400-background -highlightcolor -takefocus
2401-bitmap -highlightthickness -text
2402-borderwidth -image -textvariable
2403-command -justify -underline
2404-cursor -padx -width
2405-disabledforeground -pady -wraplength
2406-font -relief
2407-compoundoption
2408Should the button display both an image and text, and if so, where the image
2409should be placed relative to the text. Valid options are bottom, center,
2410left, none (default), right and top.
2411-defaultstate
2412Set state of default ring, one of active, normal, or disabled.
2413-overrelief flat|groove|raised|ridge|sunken
2414Alternative relief for the button when the mouse cursor is over the widget.
2415button flash
2416Alternate checkbutton between active and normal colors.
2417button invoke
2418Toggle the selection state of the checkbutton and invoke the Tcl command
2419specified with -command(if present.)
2420Checkbutton
2421-activebackground -font -pady
2422-activeforeground -foreground -relief
2423-anchor -height -state
2424-background -highlightbackground -takefocus
2425-bitmap -highlightcolor -text
2426-borderwidth -highlightthickness -textvariable
2427-command -image -underline
2428-cursor -justify -width
2429-disabledforeground -padx -wraplength
2430-indicatoronboolean
2431Whether or not the indicator should be drawn.
2432-offrelief flat|raised
2433The relief (default raised) when the indicator is not drawn and the
2434checkbutton is off.
2435-offvaluevalue
2436Value given to variable specified with -variableoption when the
2437checkbutton is de-selected.
243853
2439Tcl/Tk Reference Guide
2440-onvaluevalue
2441Value given to variable specified with -variableoption when the
2442checkbutton is selected.
2443-overrelief flat|groove|raised|ridge|sunken
2444Alternative relief for the checkbutton when the mouse cursor is over the
2445widget.
2446-selectcolorcolor
2447Color used to fill in indicator when selected.
2448-selectimageimage
2449Image displayed in indicator when selected.
2450-variablevariable
2451Variable to associate with checkbutton.
2452checkbutton deselect
2453Deselect the checkbutton.
2454checkbutton flash
2455Alternate checkbutton between active and normal colors.
2456checkbutton invoke
2457Toggle the selection state of the checkbutton and invoke the Tcl command
2458specified with -command(if present.)
2459checkbutton select
2460Select the checkbutton.
2461checkbutton toggle
2462Toggle the selection state of the checkbutton.
2463Frame
2464-borderwidth -highlightcolor -relief
2465-cursor -highlightthickness -takefocus
2466-height -padx -width
2467-highlightbackground -pady
2468-backgroundcolor
2469Same as standard -backgroundoption except it may be the empty string
2470to preserve colormap.
2471-classname
2472Class name to use in querying the option database and for bindings.
2473-colormapcolormap
2474Color map to use for window. May be the word new or pathname of another
2475window.
2476-containerboolean
2477Whether the frame will be a container to embed another application.
2478-visualvisual
2479Visual to use for the window if different from parent.
2480Label
2481-activebackground -foreground -pady
2482-activeforeground -height -relief
2483-anchor -highlightbackground -takefocus
2484-background -highlightcolor -text
2485-bitmap -highlightthickness -textvariable
248654
2487Tcl/Tk Reference Guide
2488-borderwidth -image -underline
2489-cursor -justify -width
2490-disabledforeground -padx -wraplength
2491-font
2492-compoundwhere
2493Should the label display both an image and text, and where the image should
2494be placed relative to the text: one of bottom, center, left, none
2495(default), right or top.
2496Labelframe
2497-borderwidth -highlightbackground -relief
2498-cursor -highlightcolor -takefocus
2499-font -highlightthickness -text
2500-foreground -padx -width
2501-height -pady
2502-backgroundcolor
2503Same as standard -backgroundoption except color may be the empty
2504string to preserve colormap.
2505-classname
2506Class name to use in querying the option database and for bindings.
2507-colormapcolormap
2508Color map to use for window. May be the word new or pathname of another
2509window.
2510-containerboolean
2511Whether the labelframe will be a container to embed another application.
2512-labelanchoranchorPos
2513Where to place the label. Valid anchorPos values are n, ne, en, e, es, se,
2514s, sw, ws, w, wn, and nw (default).
2515-labelwidgetwindow
2516Widget to use as label.
2517-visualvisual
2518Visual to use for the window if different from parent.
2519Menubutton
2520-activebackground -foreground -relief
2521-activeforeground -height -state
2522-anchor -highlightbackground -takefocus
2523-background -highlightcolor -text
2524-bitmap -highlightthickness -textvariable
2525-borderwidth -image -underline
2526-cursor -justify -width
2527-disabledforeground -padx -wraplength
2528-font -pady
2529-compoundwhere
2530Should the menubutton display both an image and text, and where the image
253155
2532Tcl/Tk Reference Guide
2533should be placed relative to the text: one of bottom, center, left,
2534none (default), right or top.
2535-directiondirection
2536Where to pop up menu where direction is one of above, below, left,
2537right and flush.
2538-indicatoronboolean
2539If true then a small indicator will be displayed on the button’s right side and
2540the default menu bindings will treat this as an option menubutton.
2541-menupathName
2542Pathname of menu widget to post when button is invoked.
2543Message
2544-anchor -highlightbackground -relief
2545-background -highlightcolor -takefocus
2546-borderwidth -highlightthickness -text
2547-cursor -justify -textvariable
2548-font -padx -width
2549-foreground -pady
2550-aspectinteger
2551Ratio of text width to text height times 100 to use to display text.
2552Panedwindow
2553-background -height -relief
2554-borderwidth -orient -width
2555-cursor
2556-handlepadoffset
2557Offset (pixels) from top or left of sash to draw handle.
2558-handlesizelength
2559Side length (pixels) of a sash handle.
2560-opaqueresizeboolean
2561Whether panes should be resized as a sash is moved (true), or deferred until
2562the sash is placed (false).
2563-sashcursorcursor
2564Cursor to display when over a sash.
2565-sashpadpadding
2566Amount of padding (pixels) to leave on each side of a sash.
2567-sashrelief flat|groove|raised|ridge|sunken
2568Relief to use when drawing a sash.
2569-sashwidthwidth
2570Width (pixels) of each sash.
2571-showhandleboolean
2572Should sash handles be shown.
2573panedwindow add window . . . [option value . . . ]
2574Add window . . . to panedwindow, each in a separate pane. The
2575Panedwindow Management option value pairs are described below.
2576panedwindow forget window . . .
2577Remove pane containing window from the panedwindow.
257856
2579Tcl/Tk Reference Guide
2580panedwindow identify x y
2581Identify the panedwindow component underneath the window coordinates x
2582y. If over a sash or sash handle, return {index sash|handle}, otherwise
2583return an empty list.
2584panedwindow proxy coord
2585Return list containing x y coordinates of most recent sash proxy (used for
2586rubberband-style pane resizing) location.
2587panedwindow proxy forget
2588Remove proxy (used for rubberband-style pane resizing) from display.
2589panedwindow proxy place x y
2590Place proxy (used for rubberband-style pane resizing) at coordinates x y.
2591panedwindow sash coord index
2592Return current x y coordinates of top-left corner of region containing sash
2593given by index (an integer from 0 to 1 less than the number of panes in
2594panedwindow).
2595panedwindow sash dragto index x y
2596Move sash at index by difference between x y and coordinates given to last
2597sash mark command.
2598panedwindow sash mark index x y
2599Records x y coordinates for sash at index.
2600panedwindow sash place index x y
2601Move sash at index to coordinates x y.
2602panedwindow panecget window option
2603Query Panedwindow Management option (described below).
2604panedwindow paneconfigure window [option [value [option value . . . ]]]
2605Query or modify Panedwindow Management option (described below) for
2606window.
2607panedwindow panes
2608Return ordered list of widgets managed by panedwindow.
2609Panedwindow Management Options
2610-afterwindow
2611Insert new window after window.
2612-beforewindow
2613Insert new window before window.
2614-heightsize
2615Specify height (pixels) for window. The size may be an empty string.
2616-minsizen
2617Size of window cannot be made less than n (pixels).
2618-padxn
2619Extra space (pixels) to leave on each side of window.
2620-padyn
2621Extra space (pixels) to leave on top and bottom of window.
2622-stickystyle
2623For windows smaller than the containing pane, position or stretch the
2624window based on style (string containing zero or more of the characters
2625[nsew]).
2626-widthsize
2627Specify width (pixels) for window. The size may be an empty string.
262857
2629Tcl/Tk Reference Guide
2630Radiobutton
2631-activebackground -font -pady
2632-activeforeground -foreground -relief
2633-anchor -height -state
2634-background -highlightbackground -takefocus
2635-bitmap -highlightcolor -text
2636-borderwidth -highlightthickness -textvariable
2637-command -image -underline
2638-cursor -justify -width
2639-disabledforeground -padx -wraplength
2640-indicatoronboolean
2641Whether or not the indicator should be drawn.
2642-offrelief flat|raised
2643The relief (default raised) when the indicator is not drawn and the
2644radiobutton is off.
2645-overrelief flat|groove|raised|ridge|sunken
2646Alternative relief for the checkbutton when the mouse cursor is over the
2647widget.
2648-selectcolorcolor
2649Color used to fill in indicator when selected.
2650-selectimageimage
2651Image displayed in indicator when selected.
2652-valuevalue
2653Value given to variable specified with -variableoption when the
2654radiobutton is selected.
2655-variablevariable
2656Variable to associate with radiobutton.
2657radiobutton deselect
2658Deselect the radiobutton.
2659radiobutton flash
2660Alternate radiobutton between active and normal colors.
2661radiobutton invoke
2662Toggle the selection state of the radiobutton and evaluate the Tcl command
2663specified with -command(if present.)
2664radiobutton select
2665Select the radiobutton.
2666Scale
2667-activebackground -highlightbackground -repeatdelay
2668-background -highlightcolor -repeatinterval
2669-borderwidth -highlightthickness -state
2670-cursor -orient -takefocus
2671-font -relief -troughcolor
2672-foreground
2673-bigincrementnumber
2674A real value to use for large increments of the scale.
267558
2676Tcl/Tk Reference Guide
2677-commandtclCommand
2678Specified a TCL command to evaluate when scale’s value is changed. The
2679scale’s value will be appended as an additional argument.
2680-digitsinteger
2681An integer specifying how many significant digits should be retained.
2682-fromnumber
2683A real value corresponding to left or top end of the scale.
2684-labelstring
2685A string to display as label for the scale.
2686-lengthsize
2687Specifies the height (width) for vertical (horizontal) scales.
2688-resolutionnumber
2689Real value to which scale’s value will be rounded to an even multiple of.
2690-showvalueboolean
2691Whether or not scale’s current value should be displayed in side label.
2692-sliderlengthsize
2693Size of the slider, measured along the slider’s long dimension.
2694-sliderreliefrelief
2695Specify the relief used to display the slider.
2696-tickintervalnumber
2697A real value to specify the spacing between numerical tick marks displayed.
2698-to number
2699A real value corresponding to the right or bottom end of the scale.
2700-variablevariable
2701Name of a global variable to link to the scale.
2702-widthwidth
2703Narrow dimension of scale (not including border).
2704scale coords [value]
2705Returns x and y coordinates of point corresponding to value.
2706scale get [x y]
2707If x y is given, returns scale value at that coordinate position. Otherwise,
2708scale’s current value is returned.
2709scale identify x y
2710Returns string indicating part of scale at position x y. Maybe one of
2711slider, trough1, trough2or empty.
2712scale set value
2713Changes the current value of scale to value.
2714Scrollbar
2715-activebackground -highlightcolor -repeatdelay
2716-background -highlightthickness -repeatinterval
2717-borderwidth -jump -takefocus
2718-cursor -orient -troughcolor
2719-highlightbackground -relief
2720-activereliefnumber
2721Relief to use when displaying the element that is active.
272259
2723Tcl/Tk Reference Guide
2724-commandtclCommandPrefix
2725Prefix of a Tcl command to evaluate to change the view in the widget
2726associated with the scrollbar.
2727-elementborderwidthwidth
2728Width of borders around internal elements (arrows and slider).
2729-widthwidth
2730Narrow dimension of scrollbar (not including border).
2731Elements: arrow1, trough1, slider, trough2, arrow2
2732scrollbar activate [element]
2733Display element with active attributes.
2734scrollbar delta deltaX deltaY
2735Returns fractional position change for slider movement of deltaX deltaY.
2736scrollbar fraction x y
2737Returns a real number between 0 and 1 indicating where the point given by
2738pixel coords x y lies in the trough area of the scrollbar.
2739scrollbar get
2740Returns current scrollbar settings as the list {first last}.
2741scrollbar identify x y
2742Returns name of element under pixel coords x y.
2743scrollbar set first last
2744Describes current view of associated widget where first last are the
2745percentage distance from widget’s beginning of the start and end of the view.
2746Spinbox
2747-activebackground -highlightcolor -repeatdelay
2748-background -highlightthickness -repeatinterval
2749-borderwidth -insertbackground -selectbackground
2750-cursor -insertborderwidth -selectborderwidth
2751-disabledbackground -insertofftime -selectforeground
2752-disabledforeground -insertontime -state
2753-exportselection -insertwidth -takefocus
2754-font -justify -textvariable
2755-foreground -readonlybackground -width
2756-height -relief -xscrollcommand
2757-highlightbackground
2758-buttonbackgroundcolor
2759Background color.
2760-buttoncursorcursor
2761Cursor to be used when over the spin buttons.
2762-buttondownreliefrelief
2763Relief to be used for the upper spin button.
2764-buttonupreliefrelief
2765Relief to be used for the lower spin button.
2766-commandtclCommand
2767Command to evaluate whenever a spinbutton is invoked. Several percent
2768substitutions are recognized:
2769%W the widget path
2770%s the current value of the widget
277160
2772Tcl/Tk Reference Guide
2773%d the direction of the button pressed: up or down
2774-formatformat
2775Alternate format when setting the string value from the -from and -to
2776range. It must be valid floating-point format specifier of the form
2777%<pad>.<pad>f.
2778-fromfloat
2779Lowest floating-point value for a spinbox.
2780-incrementfloat
2781Floating-point adjustment to value when a spin button is pressed.
2782-invalidcommandtclCommand
2783Script to evaluate when validateCommand returns false. (Abbrev:
2784-invcmd).
2785-to float
2786Highest floating-point value for a spinbox.
2787-validatemode
2788Mode in which validation should operate: none (default), focus,
2789focusin, focusout, key, or all. See Validation above.
2790-validatecommandtclCommand
2791Evaluate tclCommand, which must return a boolean, to validate the input
2792into the spinbox widget. If it returns false then the addition is rejected and
2793will not occur, and the invalidCommand will be evaluated. (Abbrev:
2794-vcmd).
2795-valuesvalueList
2796Spinbox contents, starting with the first value.
2797-wrapboolean
2798Should the spinbox wrap around the values of data in the widget.
2799Elements: buttondown, buttonup, entry
2800Spinbox Indices: number, anchor, end, insert, sel.first,
2801sel.last,@x-coord
2802spinbox bbox index
2803Returns bounding box of character given by index.
2804spinbox delete first [last]
2805Delete characters from first through character just before last.
2806spinbox get
2807Returns the spinbox’s string.
2808spinbox icursor index
2809Display insertion cursor just before character at index.
2810spinbox identify x y
2811Returns string (one of none, buttondown, buttonupor entry)
2812indicating element of spinbox at position x y.
2813spinbox index index
2814Returns the numerical index corresponding to index.
2815spinbox insert index string
2816Insert string just before character at index.
2817spinbox invoke element
2818Invoke the action of the spinbox element buttondownor buttonup.
2819spinbox scan option args
2820See Widget Scroll Commands above.
282161
2822Tcl/Tk Reference Guide
2823spinbox selection adjust index
2824Adjust nearest end of current selection to be at index and set the other end to
2825the anchor point.
2826spinbox selection clear
2827Clear the selection if currently in the widget.
2828spinbox selection element [element]
2829Query or set the currently selected element. If a spinbutton element is
2830specified, it will be displayed depressed.
2831spinbox selection from index
2832Set the anchor point to be at index.
2833spinbox selection present
2834Returns 1 is any characters are selected, 0 otherwise.
2835spinbox selection range start end
2836Select the characters from start through character just before end.
2837spinbox selection to index
2838Set the selection to extend between index and anchor point.
2839spinbox set [string]
2840Query or set spinbox’s string.
2841spinbox validate
2842Force an evaluation of validateCommand.
2843spinbox xview args
2844See Widget Scroll Commands above.
2845Toplevel
2846-borderwidth -highlightcolor -relief
2847-cursor -highlightthickness -takefocus
2848-height -padx -width
2849-highlightbackground -pady
2850-backgroundcolor
2851Same as standard but my be empty to preserve colormap space.
2852-classstring
2853Class name for the window to be used by option database.
2854-colormapcolormap
2855Color map to use for window. May be the word new, pathname of other
2856toplevel, or empty for the default colormap of screen.
2857-containerboolean
2858Whether toplevel is a container used to embed another application.
2859-menupathName
2860Menu widget to be used as a menubar.
2861-screenscreen
2862Screen on which to place the window.
2863-use windowID
2864Toplevel should be embedded inside window identified by windowID (see
2865winfo id) which was created as a container.
2866-visualvisual
2867Visual to use for window.
286862
2869Tcl/Tk Reference Guide
287030. Images
2871image create type [name] [options value . . .]
2872Creates new image of type with options and returns name.
2873image delete name
2874Deletes the image name.
2875image height name
2876Returns pixel height of image name.
2877image inuse name
2878Returns 1 if the image is in use by any widgets, 0 otherwise.
2879image names
2880Returns a list of the names of all existing images.
2881image type name
2882Returns the type of image name.
2883image types
2884Returns a list of valid image types.
2885image width name
2886Returns pixel width of image name.
2887When an image is created, Tk creates a new command with the same name as the
2888image. For all image types, this command supports the cget and configure
2889methods in the same manner as widgets for changing and querying configuration
2890options.
2891The bitmap Image Type
2892-backgroundcolor
2893Set background color for bitmap.
2894-datastring
2895Specify contents of bitmap in X11 bitmap format.
2896-filefileName
2897Gives name of file whose contents define the bitmap in X11 bitmap format.
2898-foregroundcolor
2899Set foreground color for bitmap.
2900-maskdatastring
2901Specify contents of mask in X11 bitmap format.
2902-maskfilefileName
2903Gives name of file whose contents define the mask in X11 bitmap format.
2904The photo Image Type
2905-datastring
2906Specify contents of image in a supported format.
2907-formatformatName
2908Specify format for data specified with the -data or -fileoptions. In
2909standard Tk, the GIF/PGM/PPM formats are supported.
2910-filefileName
2911Specifies image data should be read from file fileName.
2912-gammanumber
2913Gamma correction. Values greater than 1 (default) lighten the image, less
2914than 1 darken the image.
291563
2916Tcl/Tk Reference Guide
2917-heightnumber
2918Fixes the height of the image to number pixels.
2919-palettepaletteSpec
2920Set the resolution of the color cube to be allocated for image.
2921-widthnumber
2922Fixes the width of the image to number pixels.
2923imageName blank
2924Blanks the image so has no data and is completely transparent.
2925imageName configure [option value . . .]
2926Query or modify the configuration options for the image. If no option is
2927specified, return a list describing all available options. If option is specified
2928with no value, return a list describing the one named option.
2929imageName copy sourceImage [option value . . .]
2930Copy a region from sourceImage to imageName using given options.
2931-fromx1 y1 [x2 y2]
2932Specifies rectangular region of source image to be copied.
2933-to x1 y1 [x2 y2]
2934Specifies rectangular region of target image to be affected.
2935-shrink
2936Will clip target image so copied region is in bottom-right corner.
2937-zoomx y
2938Magnifies source region by x y in respective direction.
2939-subsamplex y
2940Reduces source image by using only every x yth pixel.
2941-compositingrulerule
2942How transparent pixels are combined. One of overlay(default) or set.
2943imageName data [option value . . .]
2944Return image data. Options are:
2945-backgroundcolor
2946If color is specified, all transparent pixels will be replaced by color.
2947-formatformat-name
2948Specifies image format of file.
2949-fromx1 y1 [x2 y2]
2950Specifies a rectangular region of the image file to copy from.
2951-grayscale
2952All pixel data will be transformed into grayscale.
2953imageName get x y
2954Returns RGB value of pixel at coords x y as list of three integers.
2955imageName put data [options]
2956Sets pixels values to data (or single color if data is a valid color name).
2957Options are:
2958-formatformat-name
2959Specifies image format of data.
2960-fromx1 y1 [x2 y2]
2961Specifies a rectangular region of the image data to copy from.
2962-shrink
2963Will clip image so copied region is in bottom-right corner.
2964-to x y
2965Specifies coords of the top-left corner in image to copy into.
296664
2967Tcl/Tk Reference Guide
2968imageName read fileName [option value . . .]
2969Reads image data from file fileName (or single color if fileName is a valid
2970color name) into image using given options.
2971-formatformat-name
2972Specifies image format of file.
2973-fromx1 y1 x2 y2
2974Specifies a rectangular region of the image file to copy from.
2975-shrink
2976Will clip image so copied region is in bottom-right corner.
2977-to x y
2978Specifies coords of the top-left corner in image to copy into.
2979imageName redither
2980Redither the image.
2981imageName transparency get x y
2982Returns boolean indicating if the pixel at x y is transparent.
2983imageName transparency set x y boolean
2984Makes the pixel at x y transparent if boolean is true, opaque otherwise.
2985imageName write fileName [option value . . .]
2986Writes image data from image into file fileName.
2987-backgroundcolor
2988If color is specified, all transparent pixels will be replaced by color.
2989-formatformat-name
2990Specifies image format for the file.
2991-fromx1 y1 x2 y2
2992Specifies a rectangular region of the image to copy from.
2993-grayscale
2994All pixel data will be transformed into grayscale.
299531. Window Information
2996winfo atom [-displayofwindow] name
2997Returns integer identifier for atom given by name on window’s display.
2998winfo atomname [-displayofwindow] id
2999Returns textual name of atom given by integer id on window’s display.
3000winfo cells window
3001Returns number of cells in the colormap for window.
3002winfo children window
3003Returns list containing path names of window’s children in stacking order.
3004winfo class window
3005Returns the class name of window.
3006winfo colormapfull window
3007Return 1 if the colormap for window is full, 0 otherwise.
3008winfo containing [-displayofwindow] rootX rootY
3009Returns path name of window containing the point rootX rootY on window’s
3010display..
3011winfo depth window
3012Returns the depth (bits per pixel) of window.
3013winfo exists window
3014Returns 1 if window exists, 0 if it doesn’t.
301565
3016Tcl/Tk Reference Guide
3017winfo fpixels window number
3018Returns floating-point value giving the number of pixels in window
3019corresponding to the distance given by number.
3020winfo geometry window
3021Returns the pixel geometry for window, in the form widthxheight+x+y.
3022winfo height window
3023Returns height of window in pixels.
3024winfo id window
3025Returns a hexadecimal string indicating the platform identifier for window.
3026winfo interps [-displayofwindow]
3027Returns a list of all Tcl interpreters registered on window’s display.
3028winfo ismapped window
3029Returns 1 if window is currently mapped, 0 otherwise.
3030winfo manager window
3031Returns the name of the geometry manager currently responsible for
3032window.
3033winfo name window
3034Returns window’s name within its parent, as opposed to its full path name.
3035winfo parent window
3036Returns the path name of window’s parent.
3037winfo pathname [-displayofwindow] id
3038Returns the path name of the window whose X identifier is id on window’s
3039display.
3040winfo pixels window number
3041Returns the number of pixels in window corresponding to the distance given
3042by number, rounded to nearest integer.
3043winfo pointerx window
3044Returns mouse pointer’s x coordinate on window’s screen.
3045winfo pointerxy window
3046Returns mouse pointer’s x and y coordinates on window’s screen.
3047winfo pointery window
3048Returns mouse pointer’s y coordinate on window’s screen.
3049winfo reqheight window
3050Returns a decimal string giving window’s requested height, in pixels.
3051winfo reqwidth window
3052Returns a decimal string giving window’s requested width, in pixels.
3053winfo rgb window color
3054Returns a list of the three RGB values that correspond to color in window.
3055winfo rootx window
3056Returns the x-coordinate, in the root window of the screen, of the upper-left
3057corner of window (including its border).
3058winfo rooty window
3059Returns the y-coordinate, in the root window of the screen, of the upper-left
3060corner of window (including its border).
3061winfo screen window
3062Returns the name of the screen associated with window, in the form
3063displayName.screenIndex.
3064winfo screencells window
3065Returns the number of cells in the default color map for window’s screen.
306666
3067Tcl/Tk Reference Guide
3068winfo screendepth window
3069Returns the depth (bits per pixel) of window’s screen.
3070winfo screenheight window
3071Returns the height in pixels of window’s screen.
3072winfo screenmmheight window
3073Returns the height in millimeters of window’s screen.
3074winfo screenmmwidth window
3075Returns the width in millimeters of window’s screen.
3076winfo screenvisual window
3077Returns the visual class of window’s screen. Maybe one of:
3078directcolor, grayscale, pseudocolor, staticcolor,
3079staticgray, or truecolor.
3080winfo screenwidth window
3081Returns the width in pixels of window’s screen.
3082winfo server window
3083Returns server information on window’s display.
3084winfo toplevel window
3085Returns the pathname of the top-level window containing window.
3086winfo viewable window
3087Returns 1 if window and all its ancestors are mapped, 0 otherwise.
3088winfo visual window
3089Returns the visual class of window (see winfo screenvisual).
3090winfo visualid window
3091Returns the X identifier for the visual of window.
3092winfo visualsavailable window
3093Returns a list whose elements describe the visuals available for window’s
3094screen including class and depth..
3095winfo vrootheight window
3096Returns the height of the virtual root window associated with window.
3097winfo vrootwidth window
3098Returns the width of the virtual root window associated with window.
3099winfo vrootx window
3100Returns the x-offset of the virtual root window associated with window.
3101winfo vrooty window
3102Returns the y-offset of the virtual root window associated with window.
3103winfo width window
3104Returns window’s width in pixels.
3105winfo x window
3106Returns x-coordinate of the upper-left corner of window in its parent.
3107winfo y window
3108Returns y-coordinate of the upper-left corner of window in its parent.
310932. The Window Manager
3110wm aspect window [minNumer minDenom maxNumer maxDenom]
3111Query, set or cancel window’s desired aspect ratio range.
3112wm attributes window [option [value [option value . . .]]]
3113Query or set platform specific attributes for window.
311467
3115Tcl/Tk Reference Guide
3116wm client window [name]
3117Query, set or cancel window’s WM_CLIENT_MACHINE property which
3118informs window manager of client machine name on which the application
3119is running.
3120wm colormapwindows window [windowList]
3121Query or set window’s WM_COLORMAP_WINDOWS property which
3122identifies windowList windows within window with private colormaps.
3123wm command window [value]
3124Query, set or cancel window’s WM_COMMAND property. Informs
3125window manager of command used to invoke the application.
3126wm deiconify window
3127Arrange for window to be mapped on the screen.
3128wm focusmodel window [active|passive]
3129Query or set the focus model for window.
3130wm frame window
3131Returns the platform window identifier for the outermost decorative frame
3132containing window. If window has none, returns platform id of window itself.
3133wm geometry window [newGeometry]
3134Query or set geometry of window.
3135wm grid window
3136Return list containing current baseWidth baseHeight widthInc heightInc for
3137gridded window.
3138wm grid window {} {} {} {}
3139Indicates window is not to be managed as a gridded window.
3140wm grid window baseWidth baseHeight widthInc heightInc
3141Indicates window is to be managed as a gridded window with the specified
3142relation between grid and pixel units.
3143wm group window [pathName]
3144Query, set or cancel pathName of group leader for window.
3145wm iconbitmap window
3146Cancel bitmap used as icon image when window is iconified. Returns name
3147of previous bitmap.
3148wm iconbitmap window bitmap
3149Set bitmap to use as icon image when window is iconified.
3150wm iconify window
3151Arrange for window to be iconified.
3152wm iconmask window
3153Cancel bitmap used as mask icon image when window is iconified. Returns
3154name of previous bitmap.
3155wm iconmask window bitmap
3156Set bitmap to use to mask icon image when window is iconified.
3157wm iconname window [newName]
3158Query or set name to use as a label for window’s icon.
3159wm iconposition window [x y]
3160Query, set or cancel hint for position on root window to place window’s icon.
3161wm iconwindow window [pathName]
3162Query, set or cancel pathName of window to use as the icon when window is
3163iconified.
3164wm maxsize window [width height]
3165Query or set maximum size that window may be resized to in each direction.
316668
3167Tcl/Tk Reference Guide
3168wm minsize window [width height]
3169Query or set minimum size that window may be resized to in each direction.
3170wm overrideredirect window [boolean]
3171Query or set the override-redirect flag of window commonly used by window
3172manager to determine whether window should have a decorative frame.
3173wm positionfrom window [program|user]
3174Indicate from whom the window’s current position was requested.
3175wm protocol window
3176Return list of all protocols for which window has handlers.
3177wm protocol window name
3178Return current command associated with window for messages of protocol
3179name.
3180wm protocol window name {}
3181Cancel handler associated with window for messages of protocol name.
3182wm protocol window name command
3183Specify a Tcl command as handler of name protocol messages for window.
3184wm resizable topWindow [widthBoolean heightBoolean]
3185Query or set whether topWindow’s width and/or height is resizable.
3186wm sizefrom window [program|user]
3187Indicate from whom the window’s current size was requested.
3188wm stackorder window
3189Return a list of toplevel windows in stacking order, from lowest to highest.
3190wm stackorder window1 isabove|isbelowwindow2
3191Return boolean indicating if window1 is currently above or below window2
3192in the stacking order.
3193wm state window [newstate]
3194Query or set current state of window: normal, icon, iconic, or
3195withdrawn.
3196wm title window [string]
3197Query or set string as title for window’s decorative frame.
3198wm transient window
3199Return current master window if window is a transient window.
3200wm transient window {}
3201Inform window manager that window is not a transient window.
3202wm transient window [master]
3203Inform window manager that window is a transient of window master.
3204wm withdraw window
3205Arranges for window to be withdrawn from the screen.
320633. Binding and Virtual Events
3207bind tag
3208Returns list of all sequences for which a bindings exists for tag.
3209bind tag sequence
3210Returns the script bound to the given sequence for tag.
3211bind tag sequence tclCommand
3212Binds tclCommand to the given sequence for tag. If tclCommand is the
3213empty string, the binding is deleted. If the first character of tclCommand is a
3214+, then it is appended to the currently associated script. Does %-substitution
3215on tclCommand (See Event Fields below)
321669
3217Tcl/Tk Reference Guide
3218bindtags window [tagList]
3219Sets the current precedence order of tags for window to tagList. If tagList is
3220an empty list, the tags are set back to the defaults.
3221event add <<virtual>> sequence [sequence . . . ]
3222Arrange for virtual event <<virtual>>to be triggered when anyone of given
3223sequences occur.
3224event delete <<virtual>> [sequence . . . ]
3225Deletes given sequences (or all if none given) from list that triggers the
3226virtual event <<virtual>>.
3227event generate window event [-whenwhen] [option value . . . ]
3228Generate event in window as if it came from window system. Possible
3229options are listed in the Event Field table below. The -when option sets
3230when the event will be processed. Possible values for when are:
3231now process immediately (default)
3232tail place at end of event queue
3233head place at beginning of event queue
3234mark same as head but behind previous generated events
3235event info [<<virtual>>]
3236Returns list of sequences that trigger virtual event <<virtual>>(if not given,
3237returns list of defined virtual events).
3238The sequence argument is a list of one or more event patterns. An event pattern
3239may be a single ASCII character, a string of the form
3240<modifier-modifier-type-detail>, or <<name>>(virtual event).
3241Modifiers:
3242Alt Button4, B4 Meta, M Mod5, M5
3243Any Button5, B5 Mod1, M1 Quadruple
3244Button1, B1 Control Mod2, M2 Shift
3245Button2, B2 Double Mod3, M3 Triple
3246Button3, B3 Lock Mod4, M4
3247Types:
3248Activate Destroy Map
3249ButtonPress, Button Enter MapRequest
3250ButtonRelease Expose Motion
3251Circulate FocusIn MouseWheel
3252CirculateRequest FocusOut Property
3253Colormap Gravity Reparent
3254Configure KeyPress, Key ResizeRequest
3255ConfigureRequest KeyRelease Unmap
3256Create Leave Visibility
3257Deactivate
3258Details: for buttons, a number 1 – 5
3259for keys, a keysym (/usr/include/X11/keysymdef)
3260Tags: internal window (applies to just that window)
3261toplevel window (applies to all its internal windows)
3262window class name (applies to all widgets in class)
3263all (applies to all windows)
3264Event Fields:
3265Generate Option Code Valid Events
3266%% Single ‘%’
326770
3268Tcl/Tk Reference Guide
3269-abovewindow %a Configure
3270-borderwidthsize %B §, Configure
3271-buttonnumber %b ButtonPress, ButtonRelease
3272-countnumber %c Expose
3273-deltanumber %D MouseWheel
3274-detaildetail %d ‡, ConfigureRequest, Focus
3275-focusboolean %f ‡
3276-heightsize %h §, Expose, ResizeRequest
3277%i Window field all events
3278-keycodenumber %k %A KeyPress, KeyRelease
3279-keysymname %K %A %N KeyPress, KeyRelease
3280-mode notify %m ‡, Focus
3281-overrideboolean %o Configure, Map, Reparent
3282-placewhere %p Circulate, CirculateRequest
3283-rootwindow %R †, ‡
3284-rootxcoord %X †, ‡
3285-rootycoord %Y †, ‡
3286-sendeventboolean %E all events
3287-serialnumber %# all events
3288-statestate %s †, ‡, Visibility
3289-subwindowwindow %S †, ‡
3290-time integer %t †, ‡, Property
3291%T Type field all events
3292-warp boolean †
3293-widthsize %w §, Configure, Expose,
3294ResizeRequest
3295%W path name all events
3296-x coord %x †, ‡, Configure, Expose,
3297Gravity, Reparent
3298-y coord %y †, ‡, Configure, Expose,,
3299Gravity, Reparent
3300† ButtonPress, ButtonRelease, KeyPress,
3301KeyRelease, Motion
3302‡ Enter, Leave
3303§ ConfigureRequest, Create
330434. Geometry Management
3305The pack Command
3306pack [configure] slave [slave . . .] [options]
3307Sets how slave windows should be managed by pack geometry master.
3308-aftersibling -fill none|x|y|both
3309-anchoranchor -in master
3310-beforesibling -side top|bottom|left|right
3311-expandboolean
3312-ipadxpixels
3313How much horizontal internal padding to leave on each side of the slave(s).
3314-ipadypixels
3315How much vertical internal padding to leave on on the top and bottom of the
3316slave(s).
331771
3318Tcl/Tk Reference Guide
3319-padxpixels
3320How much horizontal external padding to leave on each side of the slave(s).
3321-padx{leftPixels rightPixels}
3322How much horizontal external padding to leave on the left and right side of
3323the slave(s).
3324-padypixels
3325How much vertical external padding to leave on the top and bottom of the
3326slave(s).
3327-pady{topPixels bottomPixels}
3328How much vertical external padding to leave on the top and bottom of the
3329slave(s).
3330pack forget slave [slave . . .]
3331Unmanages the given slave windows.
3332pack info slave
3333Returns list containing current pack configuration of window slave.
3334pack propagate master [boolean]
3335Enables or disables propagation for the window master.
3336pack slaves master
3337Returns lists of slaves in the window master.
3338The place Command
3339place window option value [option value . . .]
3340Sets how window should be placed inside its master.
3341place [configure] window [option [value [option value . . .]]]
3342Query or modify how window should be placed inside its master.
3343-anchoranchor -relheightsize -rely location
3344-heightsize -relwidthsize -x location
3345-in master -relx location -y location
3346-widthsize -bordermode inside|outside|ignore
3347-bordermodemode
3348Degree to which borders within master determine placement of slave. One
3349of inside(default), outsideor ignore.
3350place forget window
3351Unmanages window.
3352place info window
3353Returns list containing current place configuration of window.
3354place slaves window
3355Returns lists of slaves in the window master.
3356The grid Command
3357grid [configure] slave|x|∧ [slave|x|∧ . . . ] [option value . . .]
3358Sets how slave windows should be managed by grid geometry master.
3359-columnspann -in other -row n
3360-columnn -rowspann -sticky[n][s][e][w]
3361-ipadxpixels
3362How much horizontal internal padding to leave on each side of the slave(s).
336372
3364Tcl/Tk Reference Guide
3365-ipadypixels
3366How much vertical internal padding to leave on on the top and bottom of the
3367slave(s).
3368-padxpixels
3369How much horizontal external padding to leave on each side of the slave(s).
3370-padx{leftPixels rightPixels}
3371How much horizontal external padding to leave on the left and right side of
3372the slave(s).
3373-padypixels
3374How much vertical external padding to leave on the top and bottom of the
3375slave(s).
3376-pady{topPixels bottomPixels}
3377How much vertical external padding to leave on the top and bottom of the
3378slave(s).
3379grid bbox master [column row [column2 row2]]
3380Returns bounding box in pixels of space occupied by whole grid (no args),
3381the cell (2 args), or area spanning between given cells (4 args).
3382grid columnconfigure master columnList [options]
3383Set/query column properties of given columns in grid master.
3384-minsizesize Minimum size of column.
3385-pad amount Padding to add to sides of largest slave.
3386-uniformtag Groups column with others having same tag (an arbitrary
3387string). Apportions space for all in the group in strict
3388proportion to their weights.
3389-weightint Relative weight for apportioning extra space.
3390grid forget slave [slave . . . ]
3391Removes (and unmaps) each slave from grid forgetting its configuration.
3392grid info slave
3393Returns list describing configuration state of slave.
3394grid location master x y
3395Returns column and row containing screen units x y in master. If x y is
3396outside grid, -1 is returned.
3397grid propagate master [boolean]
3398Set/query whether master tries to resize its ancestor windows to fit grid.
3399grid remove slave [slave . . . ]
3400Removes (and unmaps) each slave from grid remembering its configuration.
3401grid rowconfigure master rowList [options]
3402Set/query row properties of given rows in grid master. Same options as for
3403columnconfigure but for rows.
3404grid size master
3405Returns size of grid (as columns rows) for master.
3406grid slaves master [-row row] [-columncolumn]
3407With no options, a list of all slaves in master is returned. Otherwise, returns
3408a list of slaves in specified row or column.
3409Grid Relative Placement
3410- Increases columnspan of slave to the left.
3411x Leave an empty column.
3412∧ Extends the rowspan of slave above.
341373
3414Tcl/Tk Reference Guide
341535. Fonts
3416font actual fontDesc [-displayofwindow] [option]
3417Returns actual value for option used by fontDesc on window’s display. If
3418option is not given, the complete option/actual value list is returned.
3419font configure fontname [option [value option value . . . ]]
3420Query/set font options for application created font fontname.
3421font create [fontname [option value . . . ]]
3422Create new application font fontname with given font options.
3423font delete fontname [fontname . . . ]
3424Delete given application created fonts.
3425font families [-displayofwindow]
3426Returns list of know font families defined on window’s display.
3427font measure fontDesc [-displayofwindow] text
3428Returns width in pixels used by text when rendered in fontDesc on window.
3429font metrics fontDesc [-displayofwindow] [metric]
3430Query font metrics of fontDesc on window’s display where metric maybe be
3431one of -ascent, -descent, -linespace, or -fixed. If metric is not
3432given, the complete metric/value list is returned.
3433font names
3434Returns list of application created fonts.
3435Font Description:
34361. fontname
3437Name of font created by the application with font create.
34382. systemfont
3439Name of platform-specific font interpreted by graphics server.
34403. family [size [style . . . ]]
3441A Tcl list with first element the name of a font family, the optional second
3442element is desired size, and additional elements chosen from normalor
3443bold, romanor italic, underlineand overstrike.
34444. X-font name
3445A Unix-centric font name of the form
3446-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resyspacing-width-charset-encoding. The ‘*’ character may be used as a wild
3447card.
34485. option value [option value . . . ]
3449A Tcl list of option/values as valid for font create.
3450Font Options:
3451-familyname Font family (e.g. Courier, Times, Helvetica).
3452-sizesize Size in points (or pixels if negative).
3453-weightweight Either normal(default) or bold.
3454-slantslant Either roman(default) or italic.
3455-underlineboolean Whether or not font is underlined.
3456-overstrikeboolean Whether or not font is overstriked.
345736. Other Tk Commands
3458bell [-displayofwindow] [-nice]
3459Ring the X bell on window’s display. The -nice option will attempt to
346074
3461Tcl/Tk Reference Guide
3462avoid waking the screen saver.
3463clipboard clear [-displayofwindow]
3464Claim ownership of clipboard on window’s (default ‘.’) display, clearing its
3465contents.
3466clipboard append [-displayofwindow] [-formatfmt] [-type type] data
3467Append data of type (default STRING) to clipboard on window’s (default
3468‘.’) display.
3469clipboard get [-displayofwin] [-type type]
3470Retrieve the clipboard on win’s (default ‘.’) display as type (default
3471STRING).
3472destroy [window window . . .]
3473Destroy the given windows and their descendents.
3474focus [-force] window
3475Sets the input focus for window’s display to window. The -forceoption
3476cause the focus to be set even if another application has it.
3477focus [-displayofwindow]
3478Returns name of focus window on window’s display.
3479focus -lastforwindow
3480Returns the window which most recently had focus and is a descendent of
3481window’s toplevel .
3482grab current [window]
3483Returns name of current grab window on window’s display. If window is
3484omitted, returns list of all windows grabbed by application.
3485grab release window
3486Releases grab on window.
3487grab [set] [-global] window
3488Sets a grab on window which will be local unless -globalspecified.
3489grab status window
3490Returns none, local, or globalto describe grab state of window.
3491::safe::loadTk slave [-use window] [-displaydisplayName]
3492Initialize the required data structures in the safe interpreter slave and then
3493load Tk into it.
3494lower window [belowThis]
3495Places window below window belowThis in stacking order.
3496option add pattern value [priority]
3497Adds option with pattern value at priority (0 – 100) to database.
3498option clear
3499Clears option database and reloads from user’s Xdefaults.
3500option get window name class
3501Obtains option value for window under name and class if present.
3502option readfile fileName [priority]
3503Reads options from Xdefaults-style file into option database at priority.
3504raise window [aboveThis]
3505Places window above window aboveThis in stacking order.
3506selection clear [-displayofwindow] [-selectionselection]
3507Clears selection (default PRIMARY) on window’s display.
3508selection get [-displayofwindow] [-selectionselection] [-type type]
3509Retrieves selection from window’s display using representation type.
3510selection handle [-selectionsel] [-type type] [-formatfmt] win cmd
3511Arranges for cmd to be run whenever sel of type is owned by win.
351275
3513Tcl/Tk Reference Guide
3514selection own [-displayofwindow] [-selectionselection]
3515Returns path name of window which owns selection on window’s display.
3516selection own [-selectionselection] [-commandcommand] window
3517Causes window to become new owner of selection and arranges for
3518command to be run when window later loses the selection.
3519send [-displayofwindow] [-async] interp cmd [arg arg . . .]
3520Evaluate cmd with args in the Tk application interp on window’s display. If
3521-asyncis specified, the send command will return immediately.
3522tk appname [newName]
3523Set the interpreter name of the application to newName.
3524tk caret window [option value . . . ]
3525Query or set accessibility caret location for display of window. Options are:
3526-x pixels Window-relative X coordinate.
3527-y pixels Window-relative Y coordinate.
3528-heightpixels Height of window or cursor.
3529tk scaling [-displayofwindow] [floatNumber]
3530Set scaling factor for conversion between physical units and pixels on
3531window’s display where floatNumber is pixels per point ( 1/72 inch).
3532tk useinputmethods [-displayofwindow] [boolean]
3533Sets and queries whether Tk should use XIM (X Input Methods) for filtering
3534events. The resulting state is returned. Default is true for the main display.
3535tk windowingsystem
3536Returns one of x11, win32, classicor aqua.
3537tkwait variable varName
3538Pause program until global variable varName is modified.
3539tkwait visibility window
3540Pause program until window’s visibility has changed.
3541tkwait window window
3542Pause program until window is destroyed.
3543tk_bisque
3544Set default color palette to old bisque scheme.
3545tk_chooseColor [option value . . . ]
3546Pops up dialog for user to choose color and returns choice. Options are:
3547-initialcolorcolor Makes default choice color.
3548-parentwindow Makes window parent of dialog.
3549-titlestring Makes string title of dialog window.
3550tk_chooseDirectory [option value . . . ]
3551Pops up dialog for user to select a directory and returns choice. Options are:
3552-initialdirdirname Makes initial directory dirname.
3553-parentwindow Makes window parent of dialog.
3554-titlestring Makes string title of dialog window.
3555-mustexistboolean May non-existent directories be
3556chosen?
3557tk_dialog topw title text bitmap default string [string . . .]
3558Pops up dialog using toplevel window topw with a button for each string
3559argument. Returns index of button user presses, starting from 0 for the
3560leftmost button. The index default specifies the default button.
3561tk_focusNext window
3562Returns the next window after window in focus order.
356376
3564Tcl/Tk Reference Guide
3565tk_focusPrev window
3566Returns the previous window before window in focus order.
3567tk_focusFollowsMouse
3568Change focus model of application so focus follows the mouse pointer.
3569tk_getOpenFile [option value . . . ]
3570Pops up dialog for user to choose an existing filename and returns choice.
3571Options are:
3572-defaultextensionextension
3573String to append to filename if no extensions exists on chosen
3574filename.
3575-filetypesfilePatternList
3576List of filepattern elements of the form
3577typeName {extension [extension . . . ]} [{macType . . . }]
3578-initialdirdirectory Display files in directory.
3579-initialfilefileName Make default choice fileName.
3580-multipleboolean Allow choice of multiple files.
3581-parentwindow Makes window parent of dialog.
3582-titlestring Makes string title of dialog window.
3583tk_getSaveFile [option value . . . ]
3584Pops up dialog for user to choose a filename and returns choice. Options are
3585same as for tk_getOpenFile.
3586tk_menuSetFocus menuWindow
3587Save the current focus and sets the focus to menuWindow. menu name.
3588tk_messageBox [option value . . . ]
3589Displays a message dialog and returns the unique symbolic name of button
3590pressed by user. Options are:
3591-defaultname Make button name the default.
3592-messagestring Display string as dialog’s message.
3593-parentwindow Makes window parent of dialog.
3594-titlestring Makes string title of dialog window.
3595-icon error|info|question|warning
3596Adds specified icon to dialog.
3597-type buttonSet
3598One of abortretryignore, ok, okcancel, retrycancel,
3599yesno or yesnocancel.
3600tk_optionMenu w varName value [value . . .]
3601Creates option menu with name w consisting of the given values. The current
3602value is stored in global variable varName. Returns internal menu name.
3603tk_popup menu x y [entry]
3604Post popup menu so that entry is positioned at root coords x y.
3605tk_setPalette color
3606Changes the color scheme for Tk so the default background color is color
3607and other default colors are computed.
3608tk_setPalette name color [name color . . . ]
3609Set the default color for the named options in the color scheme explicitly.
3610Possible options are:
3611activeBackground highlightColor
3612activeForeground insertBackground
3613background selectColor
3614disabledForeground selectBackground
361577
3616Tcl/Tk Reference Guide
3617foreground selectForeground
3618highlightBackground troughColor
3619tk_textCopy window
3620The default binding for the copy key for the text widget.
3621tk_textCut window
3622The default binding for the cut key for the text widget.
3623tk_textPaste window
3624The default binding for the paste key for the text widget.
362578
3626Tcl/Tk Reference Guide
362737. TclX 8.4
3628The TclX package extends Tcl’s capabilities by adding new commands. Package
3629command is:
3630package require Tclx
363138. TclX Special Variables and Commands
3632tclx_library Path to the TclX runtime library.
3633TCLXENV Array containing information private to TclX.
3634mainloop The procedure which sets up a top-level event loop.
363539. TclX General Commands
3636dirs List the directories in the directory stack.
3637commandloop options
3638Create an interactive command loop reading from stdinand writing
3639results to stdout. In interactive mode, the results of a set command with
3640two arguments is not printed.
3641If SIGINTis configured to generate a Tcl error, it can be used to delete the
3642current command being typed without aborting the program in progress.
3643Options are:
3644-async
3645Read from stdin until a complete command is available, evaluating
3646it at that point.
3647-interactivemode
3648Enable or disable interactive command mode. Mode is one of:
3649on Enable
3650off Disable
3651tty Enable if stdinis associated with a terminal (default)
3652-prompt1tclCommand
3653Use the result of evaluating tclCommand as the main command
3654prompt, otherwise evaluate $tcl_prompt1.
3655-prompt2tclCommand
3656Use the result of evaluating tclCommand as the continuation
3657command prompt, otherwise evaluate $tcl_prompt2.
3658-endcommandtclCommand
3659Evaluate tclCommand when the command loop terminates.
3660echo [string . . . ]
3661Write each string (separated by a space) and a final newline to stdout.
3662infox version
3663Return TclX version number.
3664infox patchlevel
3665Return TclX patch level.
3666infox have_fchown
3667Return 1 if the fchownsystem call is available, 0 otherwise.
366879
3669Tcl/Tk Reference Guide
3670infox have_fchmod
3671Return 1 if the fchmodsystem call is available, 0 otherwise.
3672infox have_flock
3673Return 1 if the flock system call is available, 0 otherwise.
3674infox have_fsync
3675Return 1 if the fsync system call will sync individual files, 0 otherwise.
3676infox have_ftruncate
3677Return 1 if the ftruncatesystem call is available, 0 otherwise.
3678infox have_msgcats
3679Return 1 if XPG message catalogs are available, 0 if not.
3680infox have_posix_signals
3681Return 1 if Posix signals are available, 0 otherwise.
3682infox have_signal_restart
3683Return 1 if restartable signals are available, 0 if not.
3684infox have_truncate
3685Return 1 if the truncatesystem call is available, 0 otherwise.
3686infox have_waitpid
3687Return 1 if the waitpidsystem call is available, 0 otherwise.
3688infox appname
3689Return the value of the C variable tclAppName.
3690infox applongname
3691Return the value of the C variable tclLongAppName.
3692infox appversion
3693Return the value of the C variable tclAppVersion.
3694infox apppatchlevel
3695Return the value of the C variable tclAppPatchlevel.
3696for_array_keys varName arrayName tclCommand
3697Shortcut for: foreach varName [array names arrayName] tclCommand
3698for_recursive_glob varName dirList globList tclCommand
3699Recursively search dirList (but do not follow symbolic links) using patterns
3700in globList. Evaluate tclCommand for each file matched setting varName to
3701the name of the file.
3702loop varName firstValue limitValue [increment] tclCommand
3703Shortcut for: for {set varName firstValue}
3704{$varName compare $limitValue}
3705{incr varName increment}
3706tclCommand
3707If increment (default 1) is negative, the loop counts down. The values of
3708firstValue, limitValue and increment are integer expressions only evaluated
3709once at the beginning of the loop.
3710popd
3711Pop the top entry from the directory stack and make it the current directory.
3712pushd [dirName]
3713Push the current directory onto the directory stack and cd to dirName
3714(default [pwd].)
3715recursive_glob dirList globList
3716Recursively search dirList (but do not follow symbolic links) using patterns
3717in globList. Return a list of all files matched.
3718showproc [procName . . . ]
3719Show the definition of procName (default is all loaded procedures.)
372080
3721Tcl/Tk Reference Guide
3722try_eval tclCommand catchCommand [finalCommand]
3723Evaluate tclCommand in the current context. If an error occurs and
3724catchCommand is not empty, then catchCommand is evaluated and its result
3725becomes the result of try_eval. The context of catchCommand includes the
3726global variables:
3727errorResult The result, including the error message, of tclCommand
3728errorCode As set by Tcl
3729errorInfo As set by Tcl
3730If the error is to be continued, use the following command
3731error $errorResult $errorCode $errorInfo
3732If finalCommand is not empty, it is evaluated after tclCommand and
3733catchCommand. If an error occurs within finalCommand, then it becomes
3734the result of the try_eval command.
373540. TclX Debugging Commands
3736cmdtrace level options
3737cmdtrace on options
3738Trace commands executed depth below or at level, or all commands for on.
3739Options are:
3740noeval Print arguments unevaluated, otherwise evaluated.
3741notruncate Do not truncate trace lines to 60 characters.
3742procs Trace procedure calls only.
3743fileId Write trace output to fileId rather than stdout.
3744commandtclProc
3745For each line traced, call tclProc with arguments:
3746command The command before any argument
3747substitution.
3748argv Final argument list.
3749evalLevel Call level.
3750procLevel Procedure call level.
3751Tracing is turned off during tclProc execution. The values of
3752errorInfoand errorCodeare saved and restored on
3753return from tclProc.
3754cmdtrace off
3755Disable tracing.
3756cmdtrace depth
3757Returns the current maximum trace level, or zero if trace is disabled.
375841. TclX Development Commands
3759edprocs [procName . . . ]
3760Write procName (default all defined procedures) to a temporary file, invoke
3761the editor specified by $env(EDITOR)(default vi), and then source the
3762file if it was changed.
3763profile [-commands] [-eval] on
3764Collect performance data by procedure name. If -commandsis specified,
3765include data for Tcl commands as well. For -eval, the call stack rather
3766than the procedure scope stack is used to group statistics.
376781
3768Tcl/Tk Reference Guide
3769profile off profDataVar
3770Terminate profiling and store the results in profDataVar.
3771profrep profDataVar sortKey [fileId] [title]
3772Generates a report from profDataVar collected by the profile command
3773writing to fileId (default stdout) with optional title. The sortKey (one of
3774calls, cpu or real) indicates how to sort the data.
3775saveprocs fileName [procName . . . ]
3776Saves procName (if omitted, all defined procedures) to fileName.
377742. TclX Unix Access Commands
3778alarm float
3779Schedule a SIGALRMto be signaled after float seconds have elapsed. If float
3780is zero, cancel any previous request. Returns the number of seconds left in
3781the previous alarm.
3782execl [-argv0argv0] progName [argList]
3783Do an execl, replacing the current program, with progName passing
3784arguments argList. The -argv0option specifies an alternate value for
3785argv[0].
3786chroot dirName
3787Invoke the chroot(2) system call.
3788fork
3789Fork the current Tcl process, returning zero to the child and the child’s
3790process number to the parent.
3791id user [name]
3792id userid [uid]
3793Query or set the real and effective user ID.
3794id convert userid uid
3795id convert user name
3796Convert user ID number to a user name, or vice versa.
3797id group [name]
3798id groupid [gid]
3799Query or set the real and effective group ID.
3800id groups
3801id groupids
3802Return the current group names or ID numbers.
3803id convert groupid gid
3804id convert group name
3805Convert group ID number to a group name, or vice versa.
3806id effective user
3807id effective userid
3808Return the effective user name or ID number.
3809id effective group
3810id effective groupid
3811Return the effective group name or ID number.
3812id host
3813Same as info hostname.
3814id process
3815Same as pid.
3816id process parent
3817Return the parent process ID of the current process.
381882
3819Tcl/Tk Reference Guide
3820id process group
3821Return the group ID of the current process.
3822id process group set
3823Set the process group ID of the current process to its process ID.
3824kill [-pgroup] [signal] pidList
3825Send signal (default SIGTERM) to the each process in pidList or process
3826group for -pgroup. If present, signal is either the signal number or the
3827symbolic name.
3828link [-sym] srcPath destPath
3829Same as file link.
3830nice [priorityincr]
3831Query or set the process priority. Return the current priority.
3832readdir [-hidden] dirPath
3833Returns a list containing the contents (except for ”.” and ”..”) of directory
3834dirPath.
3835signal [-restart] action sigList [tclCommand]
3836Specify action to take when Unix signal sigList (numbers, symbolic names
3837or * for all signals) is received. Use -restartto restart blocking system
3838calls if action is not error. Action is one of:
3839default Perform system default action.
3840ignore Ignore the signal.
3841error Generate a catchable Tcl error with $errorCodeset to
3842SIGNAME.
3843trap Evaluate tclCommand and continue if an error is not returned.
3844Percent substitution is done for \%S (the signal name).
3845get Return current settings of sigList as a keyed list of signal names
3846and values, where each value is a list:
3847action default, ignore, error or trap
38480 or 1 0 if not blocked, 1 if blocked
3849tclCommand If action is trap
3850flag indicates if -restartis set
3851set Set signals from a keyed list in the format returned by get.
3852block Block the specified signals.
3853unblock Unblock the specified signals.
3854sleep integer
3855The process will sleep for integer seconds.
3856system command1 [command2 . . . ]
3857Concatenates commands with a space, then evaluate the result using the
3858standard system shell. The exit code of the command is returned.
3859sync [fileId]
3860Invoke the sync(2), or fsync(2) if fileId is specified, system call.
3861times
3862Return a list of the process and child execution times (milliseconds):
3863utime stime cutime cstime
3864umask [octalmask]
3865Set or query the file-creation mask.
3866wait [-nohang] [-untraced] [-pgroup] [pid]
3867Wait for termination of any (or specific pid) process created with execl. For
3868-nohang, don’t block but return an empty list if no process has terminated.
386983
3870Tcl/Tk Reference Guide
3871For -untraced, then the status of stopped children whose status has not
3872yet been reported are also returned. If -pgroupis specified and pid is not,
3873then wait on any process whose process groupd ID is they same as the
3874calling process. If both -pgroupand pid are specified, interpret pid as a
3875process group ID.
3876Return a three-element list:
3877{pid EXIT exitCode} The process exited normally
3878{pid SIG signalName} The process terminated due to a signal
3879{pid STOP signalName} The process is currently stopped
388043. TclX File Commands
3881bsearch fileId key [varName] [cmpProc]
3882Search fileId, an ASCII file sorted in ascending order, for a match using key
3883and the first white-space delimited field on a line. If varName is omitted,
3884return the matched line. Otherwise return 1 for a match (0 if no match) with
3885the line stored in varName.
3886If cmpProc is specified, evaluate it with arguments key and line. The
3887procedure must return -1, 0 or 1 depending on the comparison.
3888chmod [-fileid] mode fileList
3889Set permissions of files (or fileIds for -fileid) specified in fileList to
3890mode. Mode can be either numberic or symbolic.
3891chown [-fileid] idList fileList
3892Set owner of files (or fileIds for -fileid) as specified in fileList. The list
3893idList contains one or two elements: a user name or number and group
3894name, number or {} (indicating the login group). If no second element,
3895group ownership is unaltered.
3896chgrp [-fileid] group fileList
3897Set group ownership of files (or fileIds for -fileid) specified in fileList.
3898The group is a group name or number.
3899dup fileId [targetFileId]
3900Duplicate fileId (or a number) returning a new fileId. If targetFileId is
3901specified, the original file is closed.
3902fcntl fileId attribute [value]
3903Query or set file options (boolean) for fileId. Attributes are:
3904RDONLY opened for input (query only)
3905WRONLY opened for output (query only)
3906RDWR opened for input and output (query only)
3907READ readable (query only)
3908WRITE writable (query only)
3909APPEND opened for append-only output
3910NONBLOCK same as fconfigure -blocking
3911CLOEXEC close on exec flag
3912NOBUF same as fconfigure -buffering
3913LINEBUF same as fconfigure -buffering
3914KEEPALIVE keep a socket connection alive.
3915flock switches fileId [start] [length] [origin]
3916Lock all (or part from start (default 0) for length relative to origin) of fileId.
391784
3918Tcl/Tk Reference Guide
3919If length is omitted or 0, lock extends to the end of the file. Origin is one of
3920start (default), currentor end. Switches are:
3921-read create a read lock
3922-write create a write lock
3923-nowait return 1 if the lock is obtained, 0 otherwise
3924for_file varName filename tclCommand
3925Loop over lines in filename evaluating tclCommand with varName set to
3926each line of the file.
3927funlock fileId [start] [length] [origin]
3928Remove all (or part from start (default 0) for length relative to origin) of a
3929lock placed on fileId with flock.
3930fstat fileId stat [arrayVar]
3931Same as file stat with an additional item key tty. Its value is 1 if fileId is
3932associated with a terminal and 0 otherwise. If arrayVar is omitted, return a
3933key-value list.
3934fstat fileId [item]
3935Return individual (identified by item) result of stat on fileId. Item identifiers
3936are the same as above.
3937fstat fileId localhost
3938For a socket connection, return a list containing the local IP address,
3939hostname and port number.
3940fstat fileId remotehost
3941For a socket connection, return a list containing the remote IP address,
3942hostname and port number.
3943ftruncate [-fileid] file newsize
3944Truncate files (or fileIds for -fileid) specified in fileList to newsize.
3945lgets fileId [varName]
3946Read a Tcl list from fileId discarding the final newline. If varName is
3947omitted, return the list. Otherwise return the number of characters read and
3948store the list in varName.
3949pipe [readVar writeVar]
3950Create a pipe either setting readVar and writeVar to the read and write
3951fileIds, or return a two-element list of the same.
3952read_file [-nonewline] fileName
3953Read entire contents of fileName optionally discarding the last newline
3954character.
3955read_file fileName numBytes
3956Read at least numBytes characters from fileName.
3957select readFileIds [writeFileIds] [exceptFileIds] [float]
3958Wait float seconds (default forever) using the select(2) system call for zero
3959or more files to become ready for reading, writing, or a pending exception
3960condition. The list of fileId’s may be empty. An empty list is returned if the
3961timeout expired, or a three-element list each element of which is a list of the
3962appropriate fileId’s.
3963write_file fileName string [string . . . ]
3964Write each string as a newline terminated line to fileName.
396585
3966Tcl/Tk Reference Guide
396744. TclX Network Programming Support
3968host_info addresses host
3969host_info official_name host
3970host_info aliases host
3971Query the default nameserver for host (a name or IP number.)
397245. TclX File Scanning Commands
3973File scanning requires a scan context to search ASCII files. A scan context contains
3974one or more match statements, each of which associate regular expressions with
3975code to be executed when the expressions are matched.
3976scancontext create
3977Return a new contextHandle.
3978scancontext delete contexthandle
3979Delete contextHandle.
3980scancontext copyfile contexthandle [copyFileId]
3981Query or set the copyfile copyFileId for unmatched lines.
3982scanfile [-copyfilecopyFileId] contextHandle fileId
3983Scan each line (starting from the current file position) from fileId using
3984contextHandle. If -copyfileis specified, copyFileId is used for the
3985duration of the command to write all lines unmatched by any pattern or the
3986default pattern.
3987scanmatch [-nocase] contextHandle [regexp] tclCommand
3988Associate tclCommand with regexp in contextHandle. If regexp is omitted,
3989the default match is associated with tclCommand. When scanning, a match
3990is attempted with each regexp (in the order added) and, if successful,
3991tclCommand is evaluated. A continue command will terminate scanning for
3992the current line, while return terminates the scanmatch command itself.
3993The array matchInfois available to tclCommand with keys:
3994line The matched line.
3995offset The file offset of the first character of the matched line.
3996linenum The line number (relative to the first line scanned) of the
3997matched line.
3998context The current context handle.
3999handle The fileId for the file being scanned.
4000copyHandle The fileId specified by -copyfile.
4001submatchN Nth parenthesized sub-expression of the regexp.
4002subindexN List of starting and ending indices for the Nth parenthesized
4003sub-expression of the regexp.
400446. TclX Math Commands
4005The following math functions operate as procedures taking the same arguments as
4006the expr command. The result is returned.
4007abs ceil floor log10 sqrt
4008acos cos fmod pow tan
4009asin cosh hypot round tanh
4010atan double int sin
4011atan2 exp log sinh
401286
4013Tcl/Tk Reference Guide
4014Two additional functions are available:
4015max num1 [. . . numN]
4016expr max(num1, num2)
4017Return numeric maximum.
4018min num1 [. . . numN]
4019expr min(num1, num2)
4020Return numeric minumum.
4021random limit
4022Return a pseudorandom integer such that 0 ≤ number < limit.
4023random seed [integer]
4024Seed the random number generator, optionally providing integer seed.
402547. TclX List Manipulation Commands
4026intersect lista listb
4027Return the sorted logical intersection of lista and listb.
4028intersect3 lista listb
4029Return a list of three sorted lists: everything in lista not in listb, the
4030intersection of lista and listb, and everything in listb not in lista.
4031lassign list varName1 [varName2 . . . ]
4032Assign successive elements of list to the specified variables. If list contains
4033fewer elements than there are varNames, then the additional variables are set
4034to {}. If list contains more elements that there are varNames, then return the
4035unassigned elements.
4036lcontain list element
4037Return 1 if element exists in list, 0 otherwise.
4038lempty list
4039Return 1 if list is empty, 0 otherwise.
4040lmatch [switches] list pattern
4041Same as lsearch -all. Return all elements of list matching pattern.
4042Switches are:
4043-exact string match
4044-glob glob pattern match (default)
4045-regexp regex match
4046lrmdups list
4047Same as lsort -unique.
4048lvarcat varName string [string . . . ]
4049Form a single list by concatenating each string to varName. Return and
4050assign the result to varName.
4051lvarpop varName [indexExpr] [string]
4052Replace or delete (if string not present) element indexExpr (default 0) of list
4053stored in varName with string. Return the original value of the element
4054replaced. If indexExpr begins with end or len, it is replaced by the index
4055of the last element or the length of the list respectively.
4056lvarpush varName string [indexExpr]
4057Insert string before element indexExpr (default 0) of list stored in varName.
4058If indexExpr begins with end or len, it is replaced by the index of the last
4059element or the length of the list respectively.
406087
4061Tcl/Tk Reference Guide
4062union lista listb
4063Return the sorted union (duplicates removed) of lista and listb.
406448. TclX Keyed Lists
4065A keyed list is a list, each element of which is a list containing a key-value pair.
4066The key-value pairs are referred to as fields. Fields may contain subfields; ‘.’ is the
4067separator character. Subfields are actually fields where the value is another keyed
4068list.
4069keyldel keylistVar key
4070Delete the field key from the keyed list in keylistVar.
4071keylget keylistVar [key] [varName]
4072Return (or set varName with) the value associated with key from the keyed
4073list in keylistVar If varName is specified, return 1 if key was found, 0
4074otherwise. If key is omitted, then return a list of all keys in the keyed list
4075keyListVar.
4076keylkeys keylistVar [key]
4077Return a list of all keys (or subfield keys of item key) in the keyed list in
4078keylistVar.
4079keylset keylistVar key value [key2 value2 . . . ]
4080Set element key in the keyed list stored in keylistVar, to value.
408149. TclX String/Character Commands
4082ccollate [-local] string1 string2
4083Same as string compare if -localomitted. Otherwise comparison uses
4084the current locale. This command will not work with UTF or binary data.
4085cconcat [string1] [string2 . . . ]
4086Return the concatenation of the arguments.
4087cequal string string
4088Same as string equal.
4089cindex string indexExpr
4090Returns the character indexed by the indexExpr from string. If indexExpr
4091begins with end or len, it is replaced by the index of the last character or
4092the length of the string respectively.
4093clength string
4094Same as string length.
4095crange string firstExpr lastExpr
4096Return characters from string indexed by firstExpr through lastExpr. If
4097either firstExpr or lastExpr begins with end or len, it is replaced by the
4098index of the last character or the length of the string respectively.
4099csubstr string firstExpr lengthExpr
4100Return lengthExpr characters from string indexed by firstExpr. If either
4101firstExpr or lastExpr begins with end or len, it is replaced by the index of
4102the last character or the length of the string respectively.
4103ctoken stringVar separators
4104Return the first string delimitted by separators from the string stored in
4105stringVar. Replace the contents of stringVar with the remainder of its
4106original value.
410788
4108Tcl/Tk Reference Guide
4109ctype [-failindexvarName] class string
4110Return 1 if all characters in string are of class, 0 otherwise. If
4111-failindexis specified, store the index of the first non-matching
4112character in varName. Classes are:
4113alnum characters are alphabetic or numeric
4114alpha characters are alphabetic
4115ascii characters are ASCII
4116cntrl characters are control characters
4117digit characters are decimal digits
4118graph characters are printable but not white-space
4119lower characters are lowercase
4120space characters are white-space
4121print characters are printable
4122punct characters are punctuation
4123upper characters are uppercase
4124xdigit characters are hexadecimal digits
4125ctype char number
4126Return the Unicode character equivalent to number.
4127ctype ord character
4128Return the decimal Unicode value of character.
4129replicate string integer
4130Same as string repeat.
4131translit from to string
4132Translate characters in string, replacing from characters with the
4133corresponding to characters. Both from and to may contain character ranges
4134in the form ’X-Y’. This command only works with ascii characters.
413550. TclX XPG/3 Message Catalog Commands
4136catopen [-fail] catName
4137catopen [-nofail] catName
4138Return catHandle, the result of opening message catalog catName. If
4139-fail (default -nofail) is specified, an error occurs if the open fails.
4140catgets catHandle setNumber msgNumber defaultMsg
4141Retrieve message msgNumber in setNumber from catHandle. If not found,
4142return defaultMsg.
4143catclose [-fail] catHandle
4144catclose [-nofail] catHandle
4145Close catHandle. If -fail (default -nofail) is specified, an error occurs
4146if the close fails.
414789
4148Tcl/Tk Reference Guide
414951. Img 1.2.4 Package
4150
4151This package adds the pixmap image type, and provides the additional photo
4152image types bmp, png, jpeg, tiff, xbm, xpm and window. Package command is:
4153package require Img
4154The pixmap Image Type
4155-datastring
4156Specify contents of pixmap in XPM format.
4157-filefileName
4158Gives name of file whose contents define the pixmap in XPM format.
4159Additional photo Image Types
4160For the imageName read and imageName write commands, the -formatoption
4161is used to provide image type specific options. These options are appended to the
4162format string.
4163imageName read filename -format”bmp”
4164imageName write filename -format”bmp”
4165imageName read filename -format”gif [option value]”
4166-indexn
4167Selects a specific image from a multi-image GIF file.
4168imageName write filename -format”gif”
4169-backgroundcolor
4170Usually only valid for the bitmap image type, for GIF it now may be used to
4171indicate a transparent color.
4172imageName read filename -format”jpeg [option value . . .]”
4173-fastboolean
4174Fast, low-quality processing.
4175-grayscaleboolean
4176Force incoming image to grayscale
4177imageName write filename -format”jpeg [option value . . .]”
4178-grayscaleboolean
4179Create monochrome file.
4180-qualityn
4181Compression quality (0..100; 5 – 95 is useful range). Default is 75.
4182-smoothn
4183Perform smoothing (10 – 30 is enough for most GIF’s). Default is 0.
4184-optimizeboolean
4185Optimize Huffman table.
4186-progressiveboolean
4187Create progressive file.
4188imageName read filename -format”png”
4189imageName write filename -format”png [option value . . .]”
4190Each option value is used to write a text chunk such as Author, Title, Description,
4191etc.
419290
4193Tcl/Tk Reference Guide
4194-backgroundcolor
4195Usually only valid for the bitmap image type, for PNG it now may be used
4196to indicate a transparent color.
4197imageName read filename -format”postscript [option value . . .]”
4198-zoomx [y]
4199Multiply image size by given scale factors. If y is missing, the default is the
4200same as x. x and y are allowed to be in floating point format, but they are
4201rounded to the nearest practically possible value. For postscript the zoom
4202factors should be multiples of 1/72.
4203imageName read filename -format”tiff”
4204imageName write filename -format”tiff [option value . . .]”
4205-compressiontype
4206May be one of deflate, jpeg, packbits, lzw, or none.
4207-byteorderwhich
4208May be one of bigendian, littleendian, network,
4209smallendianor {}.
4210image create photo . . . -format window -data pathname
4211Pathname must be an existing window, and must be currently mapped.
4212imageName read filename -format”xbm”
4213imageName write filename -format”xbm”
4214imageName read filename -format”xpm”
4215imageName write filename -format”xpm”
421652. Tcllib 1.4
4217The Tcl Standard Library is a collection of Tcl packages that provide useful utility
4218functions.
4219::math
4220Utility math functions. Package command is:
4221package require math
4222::math::cov value value . . .
4223Return the coefficient of variation expressed as percent of two or more
4224numeric values.
4225::math::fibonacci n
4226Return the n’th Fibonacci number.
4227::math::integrate {x0 y0 x1 y1 x2 y2 x3 y3 x4 y4 . . . }
4228Return a list containing the area under a curve defined by a set of at least five
4229x,y pairs and the error bound.
4230::math::max value . . .
4231Return the maximum of one or more numeric values.
4232::math::mean value . . .
4233Return the arithmetic mean, or average of one or more numeric values.
4234::math::min value . . .
4235Return the minimum of one or more numeric values.
4236::math::prod value . . .
4237Return the product of one or more numeric values.
423891
4239Tcl/Tk Reference Guide
4240::math::random [value1 [value2]]
4241Return a random number. With no arguments, return a floating point value
4242between 0 and 1. With one argument, return an integer between 0 and
4243value1. With two arguments, return an integer between value1 and value2.
4244::math::sigma value value . . .
4245Return the population standard deviation of two or more numeric values.
4246::math::stats value value . . .
4247Return a list containing the mean, standard deviation, and coefficient of
4248variation expressed as percent of two or more numeric values.
4249::math::sum value . . .
4250Return the sum of one or more numeric values.
4251::profiler
4252Provide a simple Tcl source code profiler. It collects only function-level
4253information, not the more detailed line-level information. Profiling is initiated via
4254the ::profiler::init command. Package command is:
4255package require profiler
4256::profiler::init
4257Initiate profiling. All procedures created after this command is called will be
4258profiled.
4259::profiler::dump pattern
4260Dump profiling information for the all functions matching pattern (default
4261all.) The result is a list of key/value pairs that maps function names to
4262information about that function. The information about each function is in
4263turn a list of key/value pairs:
4264totalCalls
4265The total number of times functionName was called.
4266callerDist
4267A list of key/value pairs mapping each calling function that called
4268functionName to the number of times it called functionName.
4269compileTime
4270The runtime, in clock clicks, of functionName the first time that it was
4271called.
4272totalRuntime
4273The sum of the runtimes of all calls of functionName.
4274averageRuntime
4275Average runtime of functionName.
4276descendantTime
4277Sum of the time spent in descendants of functionName.
4278averageDescendantTime
4279Average time spent in descendants of functionName.
4280::profiler::print [pattern]
4281Print profiling information for all functions matching pattern (default all.)
4282::profiler::reset [pattern]
4283Reset profiling information for all functions matching pattern (default all.)
4284::profiler::resume [pattern]
4285Resume profiling for all functions matching pattern (default all.)
4286::profiler::sortFunctions key
4287Return list of functions sorted by a particular profiling statistic. Values for
428892
4289Tcl/Tk Reference Guide
4290key are: calls, exclusiveTime, compileTime,
4291nonCompileTime, totalRuntime, avgExclusiveTime, and
4292avgRuntime. The result is a list of lists, where each sublist consists of a
4293function name and the value of key for that function.
4294::profiler::suspend [pattern]
4295Suspend profiling for all functions matching pattern (default all.)
4296::struct::graph
4297Create and manipulate directed graph objects. Package command is:
4298package require struct
4299::struct::graph graphName
4300Create a new graph object with an associated global Tcl command whose
4301name is graphName.
4302graphName arc append arc [-key key] value
4303Append value to current value associated with key (default data) for arc.
4304graphName arc delete arc . . .
4305Remove the specified arcs from the graph.
4306graphName arc exists arc
4307Return true if the specified arc exists in the graph.
4308graphName arc get arc [-key key]
4309Return the value associated with key (default data) for arc.
4310graphName arc getall arc
4311Return list of all key/value pairs for arc.
4312graphName arc insert start end [child]
4313Insert an arc named child (or a generated arc name) beginning at the node
4314start and ending at end.
4315graphName arc keyexists arc [-key key]
4316Return true if key (default data) exists for arc.
4317graphName arc keys arc
4318Return list of all keys for arc.
4319graphName arc lappend arc [-key key] value
4320Append value (as a list) to current value associated with key (default data)
4321for arc.
4322graphName arc set arc [-key key] [value]
4323Set or get the key (default data) value associated with arc. If value omitted,
4324return current value.
4325graphName arc source arc
4326Return the node that arc begins at.
4327graphName arc target arc
4328Return the node that arc ends at.
4329graphName arc unset arc [-key key]
4330Remove a keyed (default data) value from arc.
4331graphName arcs [[-key key] [-valuevalue]] [-connection nodelist]
4332Return a list of all arcs. The list can be limited to arcs based on the keyed
4333values associated with the arc, the nodes that are connected by the arc, or
4334both. The -connection restriction may be one of
4335-in All arcs whose target is one of nodelist.
4336-out Return all arcs whose source is one of nodelist.
4337-adj Return all arcs adjacent to at least one of nodelist.
433893
4339Tcl/Tk Reference Guide
4340-inner Return all arcs adjacent to two of nodelist.
4341-embedding Return all arcs adjacent to exactly one of nodelist.
4342graphName destroy
4343Destroy the graph.
4344graphName get [-key key]
4345Return the value associated with key (default data) for the graph.
4346graphName getall
4347Return the value associated with key (default data) for the graph.
4348graphName keyexists [-key key]
4349Return true if key (default data) exists for the graph.
4350graphName keys
4351Return list of all keys for the graph.
4352graphName node append node [-key key] value
4353Append value to current value associated with key (default data) for node.
4354graphName node degree [-in|-out] node
4355Return number of (incoming -in or outgoing -out, default all) arcs
4356adjacent to node.
4357graphName node delete node . . .
4358Remove node and all its arcs from the graph.
4359graphName node exists node
4360Return true if node exists in the graph.
4361graphName node get node [-key key]
4362Return the value associated with key (default data) for node.
4363graphName node getall node
4364Return list of all key/value pairs for node.
4365graphName node insert [child]
4366Insert a node named child (or a generated name) into the graph. The node
4367has no arcs connected to it. The value ”” is assigned to key data.
4368graphName node keyexists node [-key key]
4369Return true if key (default data) exists for node.
4370graphName node keys node
4371Return list of all keys for node.
4372graphName node lappend node [-key key] value
4373Append value (as a list) to current value associated with key (default data)
4374for node.
4375graphName node opposite node arc
4376Return the node at the other end of arc, which has to be adjacent to node.
4377graphName node set node [-key key] [value]
4378Set or get the key (default data) value associated with arc. If value omitted,
4379return current value.
4380graphName node unset node [-key key]
4381Remove a keyed (default data) value from node.
4382graphName nodes [[-key key] [-valuevalue]] [-connection nodelist]
4383Return a list of all nodes. The list can be limited to nodes based on the keyed
4384values associated with the nodes, the nodes that are connected by the nodes,
4385or both. The possible -connection restrictions are the same as for method
4386arcs.
4387graphName set [-key key] [value]
4388Set or return one of the keyed values associated with a graph for key (default
4389data).
439094
4391Tcl/Tk Reference Guide
4392graphName swap node1 node2
4393Swap the position of node1 and node2 in the graph.
4394graphName unset [-key key]
4395Remove a keyed value from the graph. If no key is specified, data is
4396assumed.
4397graphName walk node [-orderorder] [-type type] [-dir dir] -commandcmd
4398Perform a breadth-first or depth-first walk of the graph starting at node going
4399in either the direction of outgoing or opposite to the incoming arcs.
4400-type bfs breadth-first
4401-type dfs depth-first (default)
4402-order pre pre-order (default)
4403-order post post-order
4404-order both both-order
4405-dir backward the direction opposite to the incoming arcs
4406-dir forward the direction of the outgoing arcs
4407As the walk progresses, cmd will be evaluated at each node, with the mode
4408(enter or leave) and values graphName and the name of the node
4409appended.
4410::struct::queue
4411Create and manipulate queue objects.
4412::struct::queue queueName
4413Create a new queue object with an associated global Tcl command whose
4414name is queueName.
4415queueName clear
4416Remove all items from the queue.
4417queueName destroy
4418Destroy the queue.
4419queueName get [count]
4420Return and remove the front count (default 1) items of the queue. If count is
44211, the result is a simple string; otherwise it is a list.
4422queueName peek [count]
4423Return the front count (default 1) items of the queue. If count is 1, the result
4424is a simple string; otherwise it is a list.
4425queueName put item . . .
4426Put item into the queue.
4427queueName size
4428Return the number of items in the queue.
4429::struct::stack
4430Create and manipulate stack objects.
4431::struct::stack stackName
4432Create a new stack object with an associated global Tcl command whose
4433name is stackName.
4434stackName clear
4435Remove all items from the stack.
4436stackName destroy
4437Destroy the stack.
443895
4439Tcl/Tk Reference Guide
4440stackName peek [count]
4441Return the top count (default 1) items of the stack. If count is 1, the result is
4442a simple string; otherwise it is a list.
4443stackName pop [count]
4444Return and remove the top count (default 1) items of the stack. If count is 1,
4445the result is a simple string; otherwise it is a list.
4446stackName push item . . .
4447Put item onto the stack.
4448stackName size
4449Return the number of items on the stack.
4450::struct::tree
4451Create and manipulate tree objects.
4452::struct::tree treeName
4453Create a new tree object with an associated global Tcl command whose
4454name is treeName.
4455treeName append node [-key key] value
4456Appends value to one of the keyed values (default data) associated with
4457node.
4458treeName children node
4459Return a list of the children of node.
4460treeName cut node
4461Removes node from the tree, but not its children. The children of node are
4462made children of the parent of node.
4463treeName delete node . . .
4464Remove node and all its children from the tree.
4465treeName depth node
4466Return number of steps from node to the root node.
4467treeName destroy
4468Destroy the tree.
4469treeName exists node
4470Return true if node exists in the tree.
4471treeName get node [-key key]
4472Return value associated with key (default data) for node.
4473treeName getall node
4474Return list of key/value pairs (suitable for use with array set for node.
4475treeName index node
4476Returns index of node in its parent’s list of children.
4477treeName insert parent index [child . . . ]
4478Insert child . . . (default a generated name) in the child list of parent at
4479index. If index is end, the new nodes will be added after the current last
4480child. If parent is root, it refers to the root of the tree. A new node has the
4481value ”” assigned to key data. If child already exist in treeName, it will be
4482moved from its original location. Return a list of nodes added.
4483treeName isleaf node
4484Return true if node is a leaf of the tree.
4485treeName keys node
4486Return list of keys for node.
448796
4488Tcl/Tk Reference Guide
4489treeName keyexists node [-key key]
4490Return true if key (default data) exists for node.
4491treeName lappend node [-key key] value
4492Append value (as a list) to one of the keyed (default data) values of node.
4493treeName move parent index node . . .
4494Make the node children of parent, inserting them into the parent’s child list
4495at index.
4496treeName next node
4497Return right sibling of node, or the empty string if node was the last child of
4498its parent.
4499treeName numchildren node
4500Return number of immediate children of node.
4501treeName parent node
4502Return parent of node.
4503treeName previous node
4504Return left sibling of node, or the empty string if node was the first child of
4505its parent.
4506treeName set node [-key key] [value]
4507Set or get one of the keyed (default data) values of node. If value omitted,
4508return current value.
4509treeName size [node]
4510Return the number of descendants of node (default root.)
4511treeName splice parent from [to] [child]
4512Insert child (or a generated name) in the child list of parent at from. If parent
4513is root, it refers to the root of the tree. The children of parent which are in
4514the range of from and to (default end) are made children of child. Return
4515child.
4516treeName swap node1 node2
4517Swap the position of node1 and node2.
4518treeName unset node [-key key]
4519Remove a keyed (default data) value from node.
4520treeName walk node [-orderorder] [-type type] -commandcmd
4521Perform a breadth-first or depth-first walk of the tree starting at node.
4522-type bfs breadth-first
4523-type dfs depth-first (default)
4524-order in in-order
4525-order pre pre-order (default)
4526-order post post-order
4527-order both both-order
4528As the walk progresses, cmd will be evaluated at each node. Percent
4529substitution will be performed on cmd before evaluation. The following
4530substitutions are recognized:
4531%% Insert the literal % character.
4532%t Name of the tree object.
4533%n Name of the current node.
4534%a Name of the action occuring; one of enter, leave, or visit.
453597
4536Tcl/Tk Reference Guide
453753. Tktable 2.8 Package
4538
4539The Tktable package provides a table widget for Tk. Package command is:
4540package require Tktable
4541table pathName options . . .
4542Create a new Tcl command whose name is pathName, a table widget. The
4543pathName of the window is returned.
4544Tktable Options
4545-anchor -highlightcolor -invertselected
4546-background -highlightthickness -justify
4547-cursor -insertbackground -relief
4548-exportselection -insertborderwidth -state
4549-font -insertofftime -takefocus
4550-foreground -insertontime -xscrollcommand
4551-highlightbackground -insertwidth -yscrollcommand
4552-autoclearboolean
4553Does the first keypress in a cell delete previous text (default false).
4554-bordercursorcursor
4555Show cursor (default crosshair) when over borders.
4556-borderwidthpixels
4557A value or list of values indicating the width of the 3-D border for interior
4558table cells. (Abbrev: -bd).
4559-browsecommandtclCommand
4560Evaluate tclCommand anytime the active cell changes. (Abbrev:
4561-browsecmd). Does %-substitution on tclCommand (See Tktable
4562Command Substitution below).
4563-cacheboolean
4564Should (default off) an internal cache of the table contents be kept.
4565-colorigininteger
4566What column index (default 0) is the left-most column in the table.
4567-colsinteger
4568Number of columns (default 10) in the table.
4569-colseparatorcharacter
4570A separator character (default a Tcl list) used when cutting or pasting data in
4571a table.
4572-colstretchmodemode
4573The stretch mode for columns to fill extra allocated window space, one of:
4574none Do not (default) stretch columns.
4575unset Only stretch columns without a specific width set.
4576all Stretch all columns by the same number of pixels.
4577last Stretch only the last column.
4578fill Adjust columns to fit window (only valid for -rowstretch).
4579This mode may be removed in the future.
4580-coltagcommandtclCommand
4581Evaluate tclCommand colNumber to determine the tag to be used for a given
4582column. It should return the tag name, or a null string.
458398
4584Tcl/Tk Reference Guide
4585-colwidthwidth
4586Default column width (default 10). Interpreted as characters when width is
4587positive, otherwise as pixels.
4588-commandtclCommand
4589If -usecommandis true, evaluate tclCommand to retrieve cell values
4590instead of the -variablearray. Does %-substitution on tclCommand (See
4591Tktable Command Substitution below).
4592-drawmodemode
4593The table drawing mode, one of:
4594slow Draw with no flashing, but it is slow for larger tables.
4595compatible
4596Draw directly to the screen (default) using Tk functions.
4597fast Draw directly to the screen using X functions. This restricts
4598-borderwidthto 0 or 1. It is best for large tables, but can
4599flash and is not 100% Tk compatible.
4600single As fast, but only single pixel lines are drawn.
4601-flashmodeboolean
4602Should (default false) cells flash when their value changes.
4603-flashtimeinteger
4604Time in 1/4 seconds (default 2) for which a cell should flash when its value
4605changes.
4606-heightinteger
4607The desired height in rows. If zero or less, make just large enough to hold all
4608the rows. The height can be further limited by -maxheight.
4609-invertselectedboolean
4610Should (default false) the foreground/background of an item simply be
4611swapped rather than merging the sel tag options when the cell is selected.
4612-ipadxpixels
4613The internal offset X padding (default 0) for text in a cell. Only affects one
4614side (depending on -anchor).
4615-ipadypixels
4616The internal offset Y padding (default 0) for text in a cell. Only affects one
4617side (depending on -anchor).
4618-maxheightpixels
4619The maximum (default 600) height requested by the window.
4620-maxwidthpixels
4621The maximum (default 800) width requested by the window.
4622-multilineboolean
4623The default setting for the multiline tag option. Default is true.
4624-padxpixels
4625The left and right X padding (default 0) for a cell.
4626-padypixels
4627The top and bottom Y padding (default 0) for a cell.
4628-resizeborderstype
4629What kind of interactive border resizing to allow, one of row, col, both
4630(default) or none.
4631-rowheightheight
4632Default row height (default 1). Interpreted as lines when height is positive,
4633otherwise as pixels.
463499
4635Tcl/Tk Reference Guide
4636-roworigininteger
4637What row index (default 0) is the top-most row in the table.
4638-rowsinteger
4639Number of rows (default 10) in the table.
4640-rowseparatorcharacter
4641A separator character (default a Tcl list) used when cutting or pasting data in
4642a table.
4643-rowstretchmodemode
4644The stretch mode for rows to fill extra allocated window space. Same modes
4645as -colstretchmode.
4646-rowtagcommandtclCommand
4647Evaluate tclCommand rowNumber to determine the tag to be used for a
4648given row. It should return the tag name, or a null string.
4649-selectioncommandtclCommand
4650Evaluate tclCommand when the selection is retrieved (ie: evaluating
4651”selection get”). (Abbrev: -selcmd). Does %-substitution on tclCommand
4652(See Tktable Command Substitution below).
4653-selectmodestyle
4654The style for manipulating the selection. One of single, browse
4655(default), multipleor extended.
4656-selecttitleboolean
4657Should (default false) title cells be allowed in the selection.
4658-selecttypemode
4659The type of selection for the table, one of row, col, cell (default), or
4660both (meaning row and col).
4661-sparsearrayboolean
4662Should an associated Tcl array be kept as a sparse array (default true).
4663-titlecolsinteger
4664Number of columns (default 0) to use as a title area.
4665-titlerowsinteger
4666Number of rows (default 0) to use as a title area.
4667-usecommandboolean
4668Should the -commandoption be used. Automatically set true if
4669-commandis used, but will reset itself falseif the command returns an
4670error.
4671-validateboolean
4672Should validation occur (default false) for the active buffer.
4673-validatecommandtclCommand
4674Evaluate tclCommand, which must return a boolean, to validate the input
4675into the active cell. If it returns false then the addition is rejected and will not
4676occur. (Abbrev: -vcmd). Does %-substitution on tclCommand (See Tktable
4677Command Substitution below).
4678-variablevarName
4679Attach global array variable varName to the table. Keys are row,colfor
4680cells, or activefor the value of the active cell buffer.
4681-widthinteger
4682The desired width in columns. If zero or less, make just large enough to hold
4683all the columns. The width can be further limited by -maxwidth.
4684-wrapinteger
4685The default wrap value for tags. Defaults to false.
4686100
4687Tcl/Tk Reference Guide
4688Tktable Indices
4689row,col, active, anchor, bottomright, end, origin, topleft, @x,y
4690Tktable Tag Options
4691-anchor -font -justify
4692-background -foreground -relief
4693-borderwidth -image -state
4694-multilineboolean Should text be displayed with newlines on multiple lines.
4695-showtextboolean Should the text be shown over an image.
4696-wrapboolean Should characters wrap in a cell that is not wide enough.
4697Builtin Tag Names: active, flash, sel, title
4698Tktable Embedded Window Options
4699-background -padx -relief
4700-borderwidth -pady
4701-stickysticky Stickiness of the window inside the cell, as defined by
4702the grid command.
4703-windowpathName Name of a window to display.
4704Tktable Command Substitution
4705Substitution is performed on the tclCommand:
4706-selectioncommand -command -browsecommand -validatecommand
4707%c maximum number
4708of columns in any
4709row
4710column
4711%C equivalent to %r,%c
4712%i number of cells 0 for get, 1
4713for set
4714current cursor position
4715%r number of rows row
4716%s default value of selection
4717empty
4718for get,
4719current
4720value for
4721set
4722index of last active
4723cell
4724current value
4725%S undefined undefined index of the new
4726active cell
4727potential new value
4728%W window pathname
4729Tktable Commands
4730table activate index
4731Sets the active cell to index.
4732table bbox first [last]
4733Return a list {x y width height }, the bounding box for first [last].
4734table border mark x y [row|column]
4735Record x y and the row and/or column border under that point, if any. If row
4736or columnis omitted, return a tuple of both border indices (an empty item
4737means no border). Otherwise, just the specified item is returned.
4738101
4739Tcl/Tk Reference Guide
4740table border dragto x y
4741Compute the difference between x y and x y of the last border mark
4742command. Adjust the previously marked border by the difference.
4743table cget option
4744General Tk widget cget command.
4745table clear cache [first [last]]
4746Clears all or specified section of the cache.
4747table clear sizes [first [last]]
4748Clears all or the specified row and column areas of specific height/width
4749dimensions.
4750table clear tags [first [last]]
4751Clears all or the specified area of all row, column and cell tags.
4752table clear all [first [last]]
4753Performs all of the above clear functions on all or the specified area.
4754table configure [option [value [option value . . . ]]]
4755General Tk widget configure command.
4756table curselection [value]
4757Query the sorted indices of the currently selected cells, or set all the selected
4758cells to the given value.
4759table curvalue [value]
4760Query or set the value of the cell being edited (indexed by active).
4761table delete active index1 [index2]
4762Delete the character after index1, or from index1 to index2 of the active
4763cell. An index is a number, insertor end.
4764table delete cols [switches [--]] col [count]
4765Delete count (default 1) columns starting at (and including) col. If count is
4766negative, delete columns to the left, otherwise to the right. Switches are:
4767-holddimensions
4768Do not adjust the table column dimension (empty
4769columns may appear).
4770-holdselection
4771Maintain the selection on the absolute cells values.
4772Default is to clear the selection.
4773-holdtags Do not move tags or adjust widths.
4774-holdwindows Do not move embedded windows.
4775-keeptitles Do not change title area cells.
4776table delete rows [switches [--]] row [count]
4777Delete count (default 1) rows starting at (and including) row. If count is
4778negative delete rows going up, otherwise going down. Switches are the same
4779as for column deletion.
4780table get first [last]
4781Return a list of values of the cells specified by first and last.
4782table height
4783Return list describing all rows for which a height has been set.
4784table height row
4785Return height of row in characters (positive number) or pixels (negative).
4786table height row value row value . . .
4787Set each row to height value in lines (positive number) or pixels (negative).
4788If value is default, then row uses the default height as specified by
4789-rowheight.
4790102
4791Tcl/Tk Reference Guide
4792table hidden
4793Returns all hidden cells (those cells covered by a spanning cell).
4794table hidden index
4795Return the spanning cell covering index, if any.
4796table hidden index index . . .
4797Return 1 if all indices are hidden cells, 0 otherwise.
4798table icursor [arg]
4799Query or set the location of the insertion cursor in the active cell. Arg is one
4800of: 0 (before the first character), insert(current insertion point) or end
4801(end of the text).
4802table index index [row|col]
4803Return cell coordinate corresponding to index in the form row,col. If row or
4804col is specified, then return only that portion.
4805table insert active index string
4806Insert string at index (one of number, insertor end) in the active cell.
4807table insert cols [switches [--]] col [count]
4808Inserts count (default 1) columns starting at col. If count is negative, insert
4809before col, otherwise insert after. Switches are the same as for column
4810deletion.
4811table insert rows [switches [--]] row [count]
4812Inserts count (default 1) rows starting at row. If count is negative, insert
4813above row, otherwise insert below. Switches are the same as for column
4814deletion.
4815table reread
4816Reread old contents of the cell back into the editing buffer.
4817table scan args
4818See Tk Widget Scroll Commands.
4819table see index
4820Adjust the view in window so cell at index is visible.
4821table selection anchor index
4822Set selection anchor to cell index.
4823table selection clear first [last]
4824Clear any selection of the cells between first and last. If first is all, remove
4825selection from all cells.
4826table selection includes index
4827Return 1 if the cell at index is currently selected, 0 if not.
4828table selection set first [last]
4829Select all of the cells between first and last.
4830table set index [value [index value . . . ]]
4831Sets the cells at index to the associated value.
4832table set col index [valueList [index valueList . . . ]]
4833Set cells at index and subsequent rows to each value in the associated
4834valueList.
4835table set row index [valueList [index valueList . . . ]]
4836Set cells at index and subsequent columns to each value in the associated
4837valueList.
4838table spans
4839Return list {index span . . . }of all known spans.
4840table spans index
4841Return the span at index, if any.
4842103
4843Tcl/Tk Reference Guide
4844table spans index rows,cols [index rows,cols . . . ]
4845Set span beginning at index for the specified number of rows,cols. A span of
48460,0 unsets any span on that cell.
4847table tag cell tagName
4848Return list of cells that use tagName.
4849table tag cell tagName index . . .
4850Apply tagName to the specified cells. If tagName is {}, reset the cells to the
4851default tag.
4852table tag cget tagName option
4853Return current value of option for tag tagName.
4854table tag col tagName
4855Return list of columns that use tagName.
4856table tag col tagName [col . . . ]
4857Apply tagName to the specified columns. If tagName is {}, reset the
4858columns to the default tag.
4859table tag configure tagName [option [value [option value . . . ]]]
4860Modifies tag-specific options for the tag tagName.
4861table tag delete tagName
4862Delete tagName.
4863table tag exists tagName
4864Return 1 if tagName exists, 0 otherwise.
4865table tag includes tagName index
4866Return 1 if index has tag tagName, 0 otherwise.
4867table tag lower tagName [belowThis]
4868Change priority of tag tagName so it is just below tag belowThis.
4869table tag names [pattern]
4870Returns a list of the names of all defined tags matching glob pattern (default
4871*).
4872table tag raise tagName [aboveThis]
4873Change priority of tag tagName so it is just above tag aboveThis.
4874table tag row tagName
4875Return list of rows that use tagName.
4876table tag row tagName row . . .
4877Apply tagName to the specified rows. If tagName is {}, reset the rows to the
4878default tag.
4879table validate index
4880Force an evaluation via the -validatecommandon cell at index.
4881table width
4882Return list describing all columns for which a width has been set.
4883table width col
4884Return width of col in characters (positive number) or pixels (negative).
4885table width col value col value . . .
4886Set each col to width value in lines (positive number) or pixels (negative). If
4887value is default, then col uses the default width as specified by
4888-colwidth.
4889table window cget index option
4890Return current value of option for window at index.
4891table window configure index [option [value [option value . . . ]]]
4892Modifies embedded window-specific options for the cell at index.
4893104
4894Tcl/Tk Reference Guide
4895table window delete index . . .
4896Delete embedded window from the table and delete the window.
4897table window move indexFrom indexTo
4898Move embedded window from indexFrom to indexTo. If a window already
4899exists in cell indexTo, it will be deleted.
4900table window names [pattern]
4901Return list of all cells containing embedded windows matching glob pattern
4902(default *).
4903table xview|yview args
4904See Tk Widget Scroll Commands.
490554. Vu 2.1.0 Package
4906
4907This package implements Tk bargraph, piechart and dial widgets, and adds
4908stripchart and barchart canvas item types. Package command is:
4909package require vu
4910Bargraph Widget
4911vu::bargraph pathName options . . .
4912Create a new Tcl command whose name is pathName, a bargraph widget.
4913The pathName of the window is returned.
4914Bargraph Options
4915-background -font -highlightthickness
4916-borderwidth -highlightbackground -orient
4917-cursor -highlightcolor -relief
4918-alabels { {position string useTick } . . . }
4919Place string and/or a tick (if useTick is true¿ at an arbitrarily position along
4920the top or left length of the bar.
4921-alabfontfont
4922The font for -alabelsstring.
4923-fg color
4924-barcolorcolor
4925Color (default red) for the bargraph bar.
4926-basebaseVal
4927The base (default 0) of the bar. fromVal ≤ baseVal ≤ toVal.
4928-blabelsLabelList
4929Like -alabels, but for the right or bottom side of the bar.
4930-barbackgroundcolor
4931Background color for the bar region.
4932-barborderwidthunits
4933Width in pixels (default 2) of a bar border.
4934-blabfontfont
4935The font for -blabelsstring.
4936-digitsinteger
4937Maximum digits (default 6) after the decimal point for floating-point values.
4938105
4939Tcl/Tk Reference Guide
4940-fromfromVal
4941Value (default 0) displayed at bottom (or left) of a bargraph. If
4942fromVal > toVal, the bargraph will grow backwards.
4943-lengthunits
4944-heightunits
4945Total height in pixels (default 100) of a bar.
4946-labelstring
4947Use string as a label (placed on top) for the bargraph.
4948-mode mode
4949For mode bargraph, the bar grows from baseVal to the current value. For
4950slider, a fixed-width slider travels along the bar with its center point
4951indicating the current value.
4952-padxunits
4953The text elements of a bargraph are held together by glue (default 2 pixels)
4954that controls their relative positions with regard to one another and to the
4955central bar. The -padxoption loosens the glue and makes the elements
4956expand from each other horizontally.
4957-padyunits
4958Like -padx, but controls the vertical glue.
4959-showrangeboolean
4960If true (default), fromVal and toVal are labeled at the appropriate ends of the
4961bar.
4962-showvalueboolean
4963If true (default), the current value is labeled near the left or bottom end of
4964the bar.
4965-sliderlengthunits
4966In slidermode, the length (default 10) in pixels of the slider.
4967-textcolorcolor
4968Color for rendering text.
4969-tickcolorcolor
4970Color (default blue) for ticks.
4971-tickintervalnumber
4972The interval (default 20.0) between successive ticks. Zero indicates no ticks.
4973-ticklengthunits
4974Length in pixels (default 4) of a tick mark.
4975-to toVal
4976Value (default 100) displayed at top (or right) of a bargraph. If
4977fromVal > toVal, the bargraph will grow backwards.
4978-widthunits
4979Width in pixels (default 20) of a bar.
4980Bargraph Commands
4981bargraph cget option
4982General Tk widget option retrieval command.
4983bargraph configure [option1 value1 option2 . . . ]
4984General Tk widget configuration command.
4985bargraph get
4986Return the current value of the bargraph.
4987bargraph set [value]
4988Set the bar to height represented by value.
4989106
4990Tcl/Tk Reference Guide
4991Dial Widget
4992vu::dial pathName options . . .
4993Create a new Tcl command whose name is pathName, a dial widget. The
4994pathName of the window is returned.
4995Dial Options
4996-activebackground -highlightbackground -repeatdelay
4997-background -highlightcolor -repeatinterval
4998-borderwidth -highlightthickness -state
4999-cursor -orient -takefocus
5000-font -relief -variable
5001-foreground
5002-beginangleinteger
5003Angle (degrees) at which the scale of the dial will start. Zero is at top and the
5004angle increases clockwise. To start the scale at the left, use a negative value.
5005-bigincrementinteger
5006Size of the large increments. If 0 (default) use 1/10 the range of the dial.
5007-commandtclProcName
5008Call tclProcname with the value of the dial when it changes.
5009-constrainvalueboolean
5010If true, the value is constrained between the -fromand -to values and
5011-resolution. If false (default), only the displayed value is constrained.
5012-dialborderwidthunits
5013Width (default 3) for the inner dial border width.
5014-dialcolorcolor
5015Color (default -background) for the inner dial.
5016-dialreliefrelief
5017The relief (default raised) for the inner dial.
5018-digitsinteger
5019Significant digits to retain when converting the value of the dial to a string.
5020If zero, use the smallest value that guarantees that every possible dial
5021position prints as a different string.
5022-endangleinteger
5023Angle (in degrees) at which the scale will end.
5024-fromfloat
5025Value corresponding to the counterclockwise-most end of the dial.
5026-labelstring
5027Use string as the label (placed on top) for the dial.
5028-minortickintervalfloat
5029The spacing between minor tick marks (those without a numerical value or
5030tag.) If 0 (default), no minor tick marks will displayed.
5031-modetype
5032One of circle(default), or elipse.
5033-needlecolorcolor
5034Color of the needle.
5035-needletypetype
5036One of arc, line (default), or triangle.
5037107
5038Tcl/Tk Reference Guide
5039-pad units
5040The elements of a dial are held together by glue (default 2 pixels) that
5041controls their relative positions with regard to one another and to the central
5042dial. The -pad option loosens the glue and makes the elements expand
5043from each other.
5044-radiusunits
5045Desired radius of the central dial.
5046-resolutionfloat
5047The resolution (default 1.0) for the dial. If greater than zero then the value,
5048tick marks and endpoints will be rounded to an even multiple of float,
5049otherwise no rounding occurs.
5050-showtagswhich
5051Which tags to display at normal tick marks: value (default), label,
5052both, or none.
5053-showvalueboolean
5054If true, display the current value.
5055-tickcolorcolor
5056Color for the ticks.
5057-tickintervalfloat
5058The spacing between major tick marks (those with a numeric value or tag.)
5059If zero, no tick marks are displayed.
5060-tickwidthunits
5061Width of the line that ticks are displayed with. The default 0, means a simple
5062line.
5063-to float
5064Value corresponding to the clockwise-most end of the dial. The value may
5065be either less than or greater than -from.
5066Dial Commands
5067dial cget option
5068General Tk widget option retrieval command.
5069dial configure [option1 value1 option2 . . . ]
5070General Tk widget configuration command.
5071dial coords [value]
5072Return a list {x y}, the coordinates of the point represented by value (default
5073current value) along the radius of the dial.
5074dial get [x y]
5075Return the value (default current value) corresponding to pixel coordinates
5076x,y.
5077dial identify x y
5078Indicate what part of the dial lies under coordinates x,y:
5079dial x,y over the dial
5080left x,y to the left of the dial
5081right x,y to the right of the dial
5082dial label [-constrain] [value [string [value string . . . ]]]
5083Associate string with value (must be a major tick value). With
5084-constrain, value will be changed if necessary to a valid tick value.
5085With no arguments, all tags will be shown. With one value, only the label (if
5086any) for that value will be shown.
5087108
5088Tcl/Tk Reference Guide
5089dial set [value]
5090Query or set the value of the dial.
5091Pie Widget
5092vu::pie pathName options . . .
5093Create a new Tcl command whose name is pathName, a piegraph widget.
5094The pathName of the window is returned.
5095Pie Options
5096-background -foreground -highlightthickness
5097-borderwidth -highlightbackground -relief
5098-cursor -highlightcolor -takefocus
5099-font
5100-angleinteger
5101Viewing angle in degrees (0
5102◦ ≤ integer ≤ 90◦
5103). Zero (default) views the pie
5104as a flat circle, 90◦
5105as a flat line.
5106-labelstring
5107Use string as a title.
5108-legendstring
5109What fields are to be displayed in the legend and in what order. The default
5110is kvpl. Field identifiers are:
5111[number] K Key box (the colored square)
5112[number] V Value (the numerical value)
5113[number] P P (the percentage of the whole)
5114[number] L Label (the given label of the slice)
5115If number is zero, the field is not shown. The default value is -1.
5116For K, a positive value means display the slice’s color in a separate box,
5117negative means use the slice’s color as background for the whole text.
5118For V, P and L, a positive value specifies the maximum field length to
5119display, negative means use a field length equal to the longest required for
5120that field.
5121-origininteger
5122Rotation of the pie in degrees clockwise.
5123-precisionnumber
5124Precision (default 2) at which to display slice and percentage values.
5125-padxwidth
5126Space (default 2) in screen units to the right the pie.
5127-padyheight
5128Space (default 2) in screen units on the bottom of the pie.
5129-radiusunits
5130The radius (default 80) of the pie.
5131-shadowunits
5132Depth (default 0) of the shadow drawn when -angleis not 0.
5133-sliceborderboolean
5134If true (default) draw borders around the slices.
5135-smallfontfont
5136The font used to draw the values of the slices at their edges in the main pie
5137area.
5138109
5139Tcl/Tk Reference Guide
5140Pie Commands
5141pie cget option
5142General Tk widget option retrieval command.
5143pie configure [option1 value1 option2 . . . ]
5144General Tk widget configuration command.
5145pie delete pattern . . .
5146Delete slices that match the given glob pattern.
5147pie explode name1 [value1 [name2 value2 . . . ]]
5148Set the explode values of one or more slices. If only one name is given, then
5149the explode value for that slice is returned.
5150pie itemcget name option
5151Returns the current value of the configuration option given by option for
5152slice name.
5153pie itemconfigure name [option1] [value1 [option2 value2 . . . ]]
5154Query or modify the item-specific options for the items given by name.
5155Options are:
5156-foregroundcolor
5157Foreground color of the slice.
5158-labelstring
5159Label (defaults to name) of the slice.
5160-valuefloat
5161Value of the slice.
5162-explodeunits
5163Explode value of the slice, how far separated from the main pie to
5164display this piece.
5165pie lower name [belowThis]
5166Lower name slice below belowThis (default the bottom.)
5167pie names [pattern . . . ]
5168Return the names of the slices, according to glob pattern (default *.)
5169pie order name . . .
5170Move the named slices, in order, to the top.
5171pie raise name [aboveThis]
5172Raise name above aboveThis (default the top.)
5173pie swap name name
5174Swap the named slices.
5175pie set name1 [value1 name2 value2 . . . ]
5176Set the values of one or more slices. If only name1 is given, then return its
5177value.
5178pie value
5179Return the sum of the slice values.
5180Barchart Canvas Item
5181A barchart item displays a set of values in a barchart diagram. Scale lines indicate
5182the current scale value.
5183canvas create barchart x1 y1 x2 y2 [option value . . . ]
5184-tagstagList
5185-autocolorboolean
5186If true, use a built-in 6-color scheme.
5187110
5188Tcl/Tk Reference Guide
5189-backgroundcolor
5190Background color, or transparent if color is the empty string.
5191-barlinecolor
5192Color (default black) of a line drawn between and on top of each bar. If
5193color is empty, no line is drawn.
5194-fillcolor
5195Use color for the strip. If color is empty, the bar is transparent and a line is
5196drawn using -scalelinecolor.
5197-outlinecolor
5198Use color for the surrounding item frame, or no frame if color is empty.
5199-scalelinecolor
5200If a bar value is greater than -scalevaluethen scalevalue is increased
5201and a scaleline is drawn. If color is empty no scaleline is drawn.
5202-scalelinestyleinteger
5203The scaleline can be dashed: integer dots, integer empty, . . . . Default is 4.
5204-scalevaluefloat
5205Maximum Y value (default 100), before a scaleline is drawn.
5206-valuesvalueList
5207List of values. By default, one value is initially allocated.
5208Stripchart Canvas Item
5209A stripchart item shows a set of values in a X-Y diagram which is scaled
5210automatically. Scale lines indicate the current scale value.
5211canvas create stripchart x1 y1 x2 y2 [option value . . . ]
5212-tagstagList
5213-backgroundcolor
5214Background color, or transparent if color is the empty string.
5215-fillcolor
5216Fill the area under the stripline with color. If color is empty, only a line is
5217drawn using -striplinecolor.
5218-jumpscrollinteger
5219When no more room exists to insert a value, the strip will be moved left by
5220integer (default 5) pixels.
5221-outlinecolor
5222Use color for the surrounding item frame, or no frame if color is empty.
5223-scaleline black black
5224-scalelinecolor
5225If a value is greater than -scalevaluethen scalevalue is increased and a
5226scaleline is drawn. If color is empty no scaleline is drawn.
5227-scalelinestyleinteger
5228The scaleline can be dashed: integer dots, integer empty, . . . . Default is 4.
5229-scalevaluefloat
5230Maximum Y value (default 100), before a scaleline is drawn.
5231-striplinecolor
5232Use color for the stripline, or no stripline if color is empty.
5233-valuesvalueList
5234List of values to append on the right. A filled stripchart will require a list of
5235length X − jumpscroll − 2.
5236111
5237Tcl/Tk Reference Guide
523855. Vim 6.2 if tcl Interface
5239The vim (Vi IMproved) editor may be compiled with a Tcl interface. Ex commands
5240invoke the Tcl interpreter, which then provides access to vim via commands and
5241variables in the ::vimnamespace.
5242The Tcl commands exit and catch are replaced by custom versions. The exit
5243command terminates the current Tcl script (deleting the Tcl interpreter) and returns
5244to vim – use the :tcl command to create a new Tcl interpreter. The catch command
5245works as usual except that exit is not caught. A non-zero exit code causes the
5246ex-command that invoked the Tcl script to return an error.
5247Vim Ex-mode Commands
5248:tcl tclCommand . . .
5249Create (if necessary) a Tcl interpreter and evaluate tclCommand. Tcl objects
5250will persist from one command to the next.
5251[range] :tcl <<[endmarker]
5252tclScript
5253[endmarker]
5254Create (if necessary) a Tcl interpreter and evaluate tclScript. The endmarker
5255defaults to a dot (.). This form of the :tcl command is mainly useful for
5256including tcl code in Vim scripts.
5257[range] :tcldo tclCommand
5258Evaluate tclCommand for each line in range (default 1,$) setting Tcl global
5259variables line and lnum. line may be modified.
5260:tclfile file
5261Same as :tcl source file.
5262::vim Special Variables and I/O Streams
5263::vim::current
5264An array (updated after ::vim::command is called) containing current
5265objects available in vim. The elements are:
5266buffer The name of the buffer command for the current buffer.
5267window The name of the window command for the current window.
5268::vim::lbase
5269If it is set to ’1’ (default), then lines and columns start at 1 within ::vim,
5270othewise 0.
5271::vim::range
5272An array with three elements, start, begin and end. Each is a line
5273number corresponding to the current range. The values of begin and
5274start are identical.
5275vimout
5276Tcl’s stdoutfile ID is mapped to vimoutand any data written to the
5277stream is displayed in the vim message area.
5278vimerr
5279Tcl’s stderrfile ID is mapped to vimerrand any data written to the
5280stream is displayed in the vim message area.
5281112
5282Tcl/Tk Reference Guide
5283::vim Commands
5284Access to vim buffers and windows is via their name similar to way the a window
5285path name is used to refer an individual widget when using Tk.
5286::vim::beep
5287Honk. Does not return a result.
5288::vim::buffer exists number
5289Check if buffer number exists.
5290::vim::buffer number
5291Create a command for buffer number returning its name as the result.
5292::vim::buffer list
5293Create a command for each buffer number in list returning a list of their
5294names as the result.
5295Most buffer commands take line numbers as agruments. In addition to a
5296number (interpreted based on value of ::vim::lbase), the value can be
5297one of top, start, begin, first, bottom, end or last.
5298buffer append line string
5299Append string after line.
5300buffer command [-quiet] cmd
5301Execute vim ex-mode command in buffers context. The -quietoption
5302suppresses error messages from vim.
5303buffer count
5304Return number of lines in the buffer.
5305buffer delcmd tclCommand
5306Registers tclCommand as a deletion callback for the buffer. The command is
5307executed (in the global scope) just before the buffer is deleted.
5308buffer delete line [line]
5309Deletes a single or range of lines from the buffer.
5310buffer expr expression
5311Evaluates expression using vim’s internal expression evaluator in buffers
5312context returning the result as a string.
5313buffer get line [line]
5314Return a single or range of lines from the buffer.
5315buffer insert line string
5316Insert string before line.
5317buffer last
5318Return the number of the last line in the buffer based on value of
5319::vim::lbase.
5320buffer mark mark
5321Return the position of the mark as string row number columnnumber.
5322buffer name
5323Return the name of the file in the buffer.
5324buffer number
5325Return the number of this buffer.
5326buffer option option [value]
5327Query or set vim option in buffers context.
5328buffer set line string
5329buffer set line line list
5330Replace a single or range of lines in the buffer. If list contains more elements
5331than there are lines to replace, they are inserted. If list contains fewer
5332elements, the remaining lines are deleted.
5333113
5334Tcl/Tk Reference Guide
5335buffer windows
5336Returning a list of window command names created for each window that
5337displays this buffer.
5338::vim::command [-quiet] command
5339Execute vim ex-mode command. The -quietoption suppresses error
5340messages from vim.
5341::vim::expr expression
5342Evaluates expression using vim’s internal expression evaluator returning the
5343result as a string.
5344::vim::option option [value]
5345Query or set vim option.
5346::vim::window list
5347Create a window command for each window returning a list of command
5348names as the result.
5349window buffer
5350Create a command for the windows buffer returning its name as the result.
5351window command [-quiet] command
5352Execute vim ex-mode command in windows context. The -quietoption
5353suppresses error messages from vim.
5354window cursor
5355Return the current cursor position as string row number columnnumber
5356interpreted based on value of ::vim::lbase.
5357window cursor row col
5358Set the current cursor position interpreted based on value of
5359::vim::lbase.
5360window cursor arrayName
5361Set cursor position from arrayName elements row and columninterpreted
5362based on value of ::vim::lbase.
5363window delcmd tclCommand
5364Registers tclCommand as a deletion callback for the window. The command
5365is executed (in the global scope) just before the window is closed.
5366window expr expression
5367Evaluates expression using vim’s internal expression evaluator in windows
5368context returning the result as a string.
5369window height
5370window height number
5371Query or attempt to set the window’s height. Return the resulting height.
5372window optionoption [value]
5373Query or set vim option in windows context.
5374Vimconsole 1.2 Package
5375
5376This package provides an interactive shell in an xterm(1) window for the ::vim Tcl
5377interpreter. Package command is:
5378:tcl package require Vimconsole
5379::vimconsole::console
5380Start the interactive shell. This command is imported into the global
5381namespace.